ai_session_search/

db.rs

// SPDX-FileCopyrightText: 2026 Andrew Hundt
// SPDX-FileCopyrightText: 2026 Nisarg Patel
// SPDX-License-Identifier: Apache-2.0

use std::collections::HashMap;
use std::fs;
use std::num::{NonZeroU64, NonZeroUsize};
use std::path::Path;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};

use anyhow::{anyhow, bail, Context, Result};
use chrono::{DateTime, TimeZone, Utc};
use fuzzy_matcher::skim::SkimMatcherV2;
use fuzzy_matcher::FuzzyMatcher;
use nucleo_matcher::pattern::{AtomKind, CaseMatching, Normalization, Pattern};
use nucleo_matcher::{Config as NucleoConfig, Matcher as NucleoMatcher, Utf32Str};
use rayon::prelude::*;
use rusqlite::{params, Connection, ErrorCode, OptionalExtension};

use crate::hashing::FramedSha256;
use crate::message_search::selected_message_field_parts;
use crate::models::{
    AnalysisRequest, EditOp, FileCrossRef, FileEdit, FileEditSummary, FileQuery,
    MessageClassificationMatch, MessageFilters, MessageHit, MessageSearchMode, ParsedSession,
    ParserHealth, PlanningCount, Provider, ProviderParserHealth, Role, SearchExplain, SearchField,
    SearchFilters, SearchHit, SessionRecord, SessionTimeProfile, SessionWithTranscript,
};
use crate::runtime::ExecutionRuntime;
use crate::util::{
    fold_caseless, snippet_from_match, snippet_from_match_while, UnicodeLowerNeedle, SIGMAS,
};

/// On-disk index generation (NOT the package version). This release INTRODUCES index versioning:
/// the upstream session-only release never set SQLite's `pragma user_version`, so any pre-existing
/// index reads as `0`. [`Db::needs_backfill`] compares this constant against `user_version` to
/// trigger a one-time full reindex after an upgrade, without re-parsing on every run. Bump by
/// exactly 1 in a future release whenever a schema/parse change requires existing indexes to be
/// re-parsed; an upgrading user then reindexes once.
///
///   1: message-level index — the first versioned schema, layered over the upstream session-only
///      schema (`sessions` + `transcripts` + a `sessions_fts` table dropped on open since 1.0.0rc2,
///      unread since session search began scoring the complete corpus). It adds the per-message `messages`
///      table (normalized role / `tool_name` / ts / compaction across all providers) with its
///      `messages_fts` word index and the custom, parallel-built [`crate::trigram_index`]
///      substring/regex prefilter (`trigram_postings` / `trigram_meta`), plus the `file_edits`
///      table behind file-version recovery (`files …`). The parser excludes harness-injected
///      output from the `user` role (claude `<local-command-*>`, codex `<environment_context>`). An
///      upstream index is at `user_version = 0 < 1`, so the first run does a single full reindex to
///      populate the message-level schema, then stamps `user_version = 1`; the trigram base then
///      builds lazily on first regex use (no per-row trigram work during reindex).
///   2: semantic message kinds and tool-call IDs are populated by the provider parsers.
///   3: codex `<turn_aborted>` harness-control records are excluded from user messages; the
///      post-reindex archive purge also removes them when their source transcript is unavailable.
///   4: exact/regex message substring acceleration uses SQLite FTS5 word+trigram indexes.
///   5: message authorship, mixed-content part ranges, and source-authoritative mirror
///      correlations are persisted for SQL-first behavioral analysis. Existing rows remain
///      `unknown` until their available provider source is reparsed; unavailable archive rows are
///      never guessed.
pub const SCHEMA_VERSION: i64 = 5;
const PARSER_SCHEMA_VERSION: i64 = 5;
const PRE_FTS_PARSER_SCHEMA_VERSION: i64 = 3;
/// Oldest on-disk generation that has every table and column required for correct reads. A
/// readable older generation can be served while `auto` upgrades parser-derived rows in a
/// background process; older and future-unknown generations require synchronous preparation.
pub const MIN_READABLE_SCHEMA_VERSION: i64 = 2;

/// Closed result of inspecting the on-disk schema before choosing query or maintenance authority.
/// `Missing` and `RecoveryRequired` are produced by the coordinator before `Db` is opened; an
/// ordinary opened connection can report only the version-derived states.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum SchemaState {
    Missing,
    Current,
    Older {
        current: i64,
        required: i64,
    },
    Newer {
        current: i64,
        supported: i64,
    },
    /// Current version stamp, but `sessions.provider` holds a value this build cannot decode. A
    /// provider variant can ship without a schema-generation bump (Prime Agent did, at generation
    /// 5), so this is how an index a newer aise wrote looks to an older aise. It is treated like
    /// [`SchemaState::Newer`]: refused once at open with the upgrade advice, instead of failing
    /// deep inside whichever query first reads such a row with advice to run the very reindex
    /// that fails the same way.
    UnknownProviders {
        providers: Vec<String>,
    },
    /// Current version stamp, but the derived message-search layout is hybrid/incomplete while every
    /// base table (including `messages`) is intact. The derived FTS5 objects can be rebuilt online
    /// from the intact base rows — no transcript re-read, no data loss — so a writable command can
    /// self-heal in place instead of demanding an offline `reindex --full`.
    RepairableLayout {
        reason: String,
    },
    RecoveryRequired {
        reason: String,
    },
}

impl SchemaState {
    pub(crate) fn from_version(current: i64) -> Self {
        match current.cmp(&SCHEMA_VERSION) {
            std::cmp::Ordering::Less => Self::Older {
                current,
                required: SCHEMA_VERSION,
            },
            std::cmp::Ordering::Equal => Self::Current,
            std::cmp::Ordering::Greater => Self::Newer {
                current,
                supported: SCHEMA_VERSION,
            },
        }
    }

    /// The single sentence every open path prints for [`SchemaState::UnknownProviders`]: the
    /// provider values, this build's version so the reader can compare, and the one fix.
    pub(crate) fn unknown_providers_message(path: &Path, providers: &[String]) -> String {
        format!(
            "index {} contains sessions from provider(s) {} that this aise {} does not recognize, \
             so a newer aise wrote it; upgrade aise (`aise package update`) before opening it",
            path.display(),
            providers.join(", "),
            env!("CARGO_PKG_VERSION")
        )
    }
}

/// Distinct `sessions.provider` values this build cannot decode, in index order. Empty when every
/// provider is known or when the `sessions` table does not exist yet. `O(S)` sessions once per
/// open; the column is short and the table is small next to `messages`.
pub(crate) fn unknown_index_providers(conn: &Connection) -> Result<Vec<String>> {
    let table_exists: bool = conn.query_row(
        "select exists(select 1 from sqlite_schema where type = 'table' and name = 'sessions')",
        [],
        |row| row.get(0),
    )?;
    if !table_exists {
        return Ok(Vec::new());
    }
    let mut statement = conn.prepare("select distinct provider from sessions order by provider")?;
    let providers = statement
        .query_map([], |row| row.get::<_, String>(0))?
        .collect::<rusqlite::Result<Vec<_>>>()?;
    Ok(providers
        .into_iter()
        .filter(|provider| Provider::from_db_str(provider).is_err())
        .collect())
}

#[derive(Debug, Clone, Copy, Eq, PartialEq)]
pub enum MessageOrder {
    OldestFirst,
    NewestFirst,
}

#[derive(Debug, Clone, Copy, Eq, PartialEq)]
pub(crate) enum MessageBatchControl {
    Continue,
    Stop,
}

#[derive(Debug)]
pub(crate) struct MessageBatchVisitOutcome {
    pub(crate) rows_visited: usize,
    pub(crate) exhausted: bool,
    pub(crate) explain: Option<SearchExplain>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum SourceFileRefreshState {
    Current,
    ChangedSameParser,
    ChangedParser,
    New,
}

struct PreparedMessageQuery {
    sql: String,
    args: Vec<rusqlite::types::Value>,
    /// The receipt this statement's plan produced, complete at prepare time; the rows a caller
    /// then reads never change it (a `limit + 1` look-ahead used to be reported as the corpus).
    explain: Option<SearchExplain>,
}

/// Corpus-size threshold below which a regex `messages search` skips the trigram prefilter and
/// scans the structurally-filtered rows directly. The prefilter's win is amortized over a large
/// corpus; once a role/session/time/tool filter narrows the scan to a small slice, a direct regex
/// pass over that slice can beat intersecting it against the whole-corpus trigram index. See
/// [`Db::search_messages`].
const TRIGRAM_PREFILTER_MIN_CORPUS: i64 = 50_000;

/// How many newer-than-base messages may accumulate before the custom trigram base index is
/// rebuilt (in parallel). Below this, messages with `id > base_max` form the "delta" and are
/// regex-verified by a direct scan rather than via the index — bounded by the SAME magnitude as
/// [`TRIGRAM_PREFILTER_MIN_CORPUS`] so the un-indexed delta a query may direct-scan stays in the
/// range a direct scan already handles cheaply. See [`Db::ensure_trigram_base`].
const TRIGRAM_BASE_REBUILD_DELTA: i64 = TRIGRAM_PREFILTER_MIN_CORPUS;

/// Maximum message rows retained for one parallel fuzzy-scoring batch. Global ranking keeps only
/// `offset + limit` scored rows between batches, so retained row count is independent of corpus
/// size. Byte memory still includes full content for the current batch and top window plus each
/// worker's UTF-32/lowercase scratch for its largest processed row.
const FUZZY_SCORE_BATCH_SIZE: usize = 512;
/// Bound rows and ordinary transcript bytes retained between serial SQLite traversal and parallel
/// session scoring. One individually oversized record is processed alone, so batching adds at most
/// this byte budget beyond the largest record rather than multiplying that record by the row cap.
const SESSION_SCORE_BATCH_SIZE: usize = 128;
const SESSION_SCORE_BATCH_BYTES: usize = 8 * 1024 * 1024;
/// Bound the message bytes retained by one fuzzy scoring batch. Rows alone do not bound memory:
/// 512 tool results of a megabyte each are half a gigabyte held before the batch scores.
const FUZZY_BATCH_BYTES: usize = 8 * 1024 * 1024;

/// One rule for every fuzzy batch: score when the row cap or the byte cap is reached, so peak
/// retained input is `min(FUZZY_SCORE_BATCH_SIZE rows, FUZZY_BATCH_BYTES + one row)`.
const fn fuzzy_batch_is_full(rows: usize, bytes: usize) -> bool {
    rows >= FUZZY_SCORE_BATCH_SIZE || bytes >= FUZZY_BATCH_BYTES
}

/// Default SQLite busy timeout for normal CLI/MCP use. This is intentionally a short wait, not
/// an indefinite block: concurrent agent sessions should ride out brief write bursts, while real
/// stuck maintenance still surfaces as an actionable error.
pub const DEFAULT_BUSY_TIMEOUT_MS: u64 = 5_000;

/// Automatic read-command refreshes use a separate stale-read fallback timeout: wait long enough
/// for ordinary writer handoffs, then serve the existing index if another process is still writing.
pub const DEFAULT_AUTO_REINDEX_BUSY_TIMEOUT_MS: u64 = 10_000;

/// Shared cross-process window after a successful automatic refresh where later read commands skip
/// auto-reindex and stay read-only. This replaces the old MCP-only in-process throttle.
pub const DEFAULT_AUTO_REINDEX_INTERVAL_MS: u64 = 1_500;

/// Per-connection SQLite page-cache target. SQLite interprets a negative `cache_size` as KiB;
/// pages are allocated on demand, so an idle connection does not reserve this entire amount.
const SQLITE_PAGE_CACHE_KIB: i64 = 64 * 1_024;

/// Maximum database prefix eligible for SQLite memory-mapped reads. This is virtual address space,
/// not eagerly allocated resident memory, and SQLite/OS may choose a lower platform-safe value.
const SQLITE_MMAP_BYTES: i64 = 256 * 1_024 * 1_024;

/// Partial covering index over the classes the default search predicate can exclude
/// ([`crate::models::MessageKind::EXCLUDABLE_BY_DEFAULT`]). It exists for one statement: the
/// receipt's corpus denominator, `count(rows the structural filters admit)`, whose class clause
/// is `kind != 'harness_notice'`. No index answers a `!=` without visiting rows, and the message
/// rows carry the bodies, so that count read every page of a 22.6 GB table (117 s). Written as
/// `count(every class) - count(only the excluded classes)`, the first term is served by the
/// index that leads with the selected filter column and the second by this one: it leads with
/// `kind` and carries every column a structural filter tests, so both terms are index-only.
///
/// Partial, not whole-table, on purpose: an index leading with `kind` over every row is
/// attractive to the planner for `kind = 'tool_call'` and `--kind` selections, and on the real
/// schema and statistics it displaced the ordered `idx_messages_tool_calls`/`session_seq`
/// walks with a seek plus a temp B-tree sort (checked with `explain query plan` against a
/// replica of the production schema and `sqlite_stat1`). A partial index is usable only when the
/// query text implies its `where` clause, so no other statement can pick it, and it holds
/// 2 % of the rows. That implication is textual: [`excluded_kinds_predicate`] renders the one
/// clause both the DDL and the count use.
///
/// Built by [`Db::ensure_message_kind_index`]: at open only while the table is empty,
/// otherwise once by the elected refresh writer.
pub(crate) const MESSAGE_KIND_INDEX: &str = "idx_messages_excluded_kinds";
const MESSAGE_KIND_INDEX_COLUMNS: &str = "(kind, role, provider, session_id, ts, tool_name)";

/// `kind in ('compaction', 'harness_notice')`, the exact text of [`MESSAGE_KIND_INDEX`]'s partial
/// clause. SQLite proves partial-index usability by comparing expressions, and bound parameters
/// never qualify, so the count statement inlines this literal (enum spellings, no user input)
/// and narrows with a bound `kind in (?)` after it.
fn excluded_kinds_predicate() -> String {
    let classes = crate::models::MessageKind::EXCLUDABLE_BY_DEFAULT
        .iter()
        .map(|kind| format!("'{}'", kind.as_str()))
        .collect::<Vec<_>>()
        .join(", ");
    format!("kind in ({classes})")
}

/// Caller-injected sink for human-facing progress notices (see [`Db::set_progress_reporter`]).
type ProgressReporter = Box<dyn Fn(&str) + Send + Sync>;

/// Set once the unread `sessions_fts` copy an earlier build filled has been emptied; see `Db::init`.
const SESSIONS_FTS_RETIRED_KEY: &str = "sessions_fts_retired";
const AUTO_REINDEX_COMPLETED_MS_KEY: &str = "auto_reindex_completed_ms";
const AUTO_REINDEX_COMPLETED_NS_KEY: &str = "auto_reindex_completed_ns";
const AUTO_REINDEX_PARSER_CONTRACT_KEYS: [&str; 4] = [
    "auto_reindex_parser_contract_0",
    "auto_reindex_parser_contract_1",
    "auto_reindex_parser_contract_2",
    "auto_reindex_parser_contract_3",
];
const AUTO_REINDEX_FRESHNESS_SQL: &str =
    "select completed.value, word0.value, word1.value, word2.value, word3.value
     from index_metadata completed
     join index_metadata word0 on word0.key = ?2
     join index_metadata word1 on word1.key = ?3
     join index_metadata word2 on word2.key = ?4
     join index_metadata word3 on word3.key = ?5
     where completed.key = ?1";
const NANOSECONDS_PER_MILLISECOND: i64 = 1_000_000;
const NANOSECONDS_PER_SECOND: i64 = 1_000_000_000;
const CORRECTION_CANDIDATES_SQL: &str =
    "select m.id, m.session_id, m.seq, m.provider, m.ts, m.content, m.authorship
     from messages m
     where m.record_relation = 'original'
       and (
           m.authorship = 'human'
           or (
               m.authorship = 'mixed'
               and exists (
                   select 1
                   from message_content_parts p
                   where p.message_id = m.id and p.authorship = 'human'
               )
           )
       )";
const CORRECTION_HUMAN_PARTS_SQL: &str = "select m.id, p.start_char, p.end_char
     from messages m
     join message_content_parts p on p.message_id = m.id
     where m.authorship = 'mixed'
       and m.record_relation = 'original'
       and p.authorship = 'human'";

struct TrigramRebuild {
    base_max: i64,
    rebuilt: bool,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct StorageAllocation {
    pub total_bytes: u64,
    pub reclaimable_bytes: u64,
}

fn elapsed_ms(now_ms: i64, earlier_ms: i64) -> u64 {
    now_ms.saturating_sub(earlier_ms).max(0) as u64
}

pub struct Db {
    conn: Connection,
    runtime: Arc<ExecutionRuntime>,
    access_scope: crate::search_scope::EffectiveAccessScope,
    /// Fixed corpus-size threshold used only by the pre-v4 compatibility prefilter.
    prefilter_min_corpus: i64,
    /// Fixed un-indexed delta size before the pre-v4 compatibility base is rebuilt.
    trigram_rebuild_delta: i64,
    /// Whether read operations may perform persistent lazy index maintenance. Disabled by the
    /// `existing-only` refresh policy; searches then reuse any existing base and scan its delta.
    implicit_index_maintenance: bool,
    /// Optional sink for human-facing progress notices (e.g. the one-time lazy index build). The
    /// library NEVER writes to stderr/stdout itself — the caller injects how (or whether) to report:
    /// the CLI sets an `eprintln` sink, the MCP server leaves it unset (silent, so nothing can
    /// pollute its stdio JSON-RPC channel). Mirrors the indexer's `progress` callback.
    progress: Option<ProgressReporter>,
}

/// Same-snapshot population facts accumulated by [`Db::visit_analysis_sessions`].
pub(crate) struct AnalysisTraversalReceipt {
    pub(crate) selected_sessions: u64,
    pub(crate) messages_in_selected_sessions: u64,
    pub(crate) analyzed_user_messages: u64,
    pub(crate) has_more: bool,
    pub(crate) last_selected_session_id: Option<String>,
    pub(crate) max_selected_session_updated_at: Option<DateTime<Utc>>,
    pub(crate) corpus_digest: String,
}

const QUERY_PROGRESS_HANDLER_OPCODES: i32 = 10_000;

struct ProgressHandlerReset<'connection>(&'connection Connection);

impl Drop for ProgressHandlerReset<'_> {
    fn drop(&mut self) {
        // rusqlite 0.40 reports whether clearing the handler succeeded. Drop cannot propagate,
        // and leaving this query's expired deadline installed would stop the next query on the
        // same connection, so surface it where a caller can act: debug and test builds.
        let cleared = self.0.progress_handler(0, None::<fn() -> bool>);
        debug_assert!(
            cleared.is_ok(),
            "clearing the SQLite progress handler failed: {cleared:?}"
        );
    }
}

struct ReadSnapshotRollback<'connection> {
    connection: &'connection Connection,
    active: bool,
}

/// Snapshot cleanup failed, so callers must not downgrade the operation to expected cancellation.
///
/// The operation is rendered rather than exposed as an error source: if it was `SQLITE_INTERRUPT`,
/// allowing that source into an error chain would incorrectly classify the cleanup failure itself
/// as a successful cancellation.
#[derive(Debug)]
pub(crate) struct ReadSnapshotCleanupError {
    operation: Option<String>,
    cleanup: String,
}

impl ReadSnapshotCleanupError {
    pub(crate) fn new(operation: Option<anyhow::Error>, cleanup: anyhow::Error) -> Self {
        Self {
            operation: operation.map(|error| format!("{error:#}")),
            cleanup: format!("{cleanup:#}"),
        }
    }
}

impl std::fmt::Display for ReadSnapshotCleanupError {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self.operation.as_deref() {
            Some(operation) => write!(
                formatter,
                "message search failed ({operation}) and its read snapshot also failed to release: {}",
                self.cleanup
            ),
            None => write!(
                formatter,
                "failed to release message-search read snapshot: {}",
                self.cleanup
            ),
        }
    }
}

impl std::error::Error for ReadSnapshotCleanupError {}

impl<'connection> ReadSnapshotRollback<'connection> {
    fn begin(connection: &'connection Connection) -> Result<Self> {
        anyhow::ensure!(
            connection.is_autocommit(),
            "cannot start a read snapshot while another transaction is active"
        );
        connection.execute_batch("begin deferred")?;
        Ok(Self {
            connection,
            active: true,
        })
    }

    fn rollback(mut self) -> Result<()> {
        self.connection.execute_batch("rollback")?;
        self.active = false;
        Ok(())
    }
}

impl Drop for ReadSnapshotRollback<'_> {
    fn drop(&mut self) {
        if self.active {
            let _ = self.connection.execute_batch("rollback");
        }
    }
}

/// Request-owned cancellation shared by blocking Rust work and its current SQLite connection.
///
/// The atomic flag closes the cancel-before-statement race; `InterruptHandle` preempts an active
/// statement without waiting for the progress callback's fixed opcode interval. Registration and
/// cancellation are `O(1)` time and memory, and the mutex is never held while SQLite executes.
#[derive(Debug)]
pub(crate) struct QueryCancelled;

impl std::fmt::Display for QueryCancelled {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter.write_str("query cancelled")
    }
}

impl std::error::Error for QueryCancelled {}

pub(crate) struct QueryCancellation {
    cancelled: Arc<AtomicBool>,
    interrupt: Mutex<Option<rusqlite::InterruptHandle>>,
}

impl QueryCancellation {
    pub(crate) fn new() -> Self {
        Self {
            cancelled: Arc::new(AtomicBool::new(false)),
            interrupt: Mutex::new(None),
        }
    }

    pub(crate) fn cancel(&self) {
        self.cancelled.store(true, Ordering::Release);
        let interrupt = self
            .interrupt
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        if let Some(interrupt) = interrupt.as_ref() {
            interrupt.interrupt();
        }
    }

    pub(crate) fn is_cancelled(&self) -> bool {
        self.cancelled.load(Ordering::Acquire)
    }

    pub(crate) fn ensure_active(&self) -> Result<()> {
        if self.is_cancelled() {
            return Err(QueryCancelled.into());
        }
        Ok(())
    }

    pub(crate) fn flag(&self) -> &AtomicBool {
        self.cancelled.as_ref()
    }

    pub(crate) fn flag_arc(&self) -> Arc<AtomicBool> {
        Arc::clone(&self.cancelled)
    }

    pub(crate) fn register(&self, connection: &Connection) {
        let mut interrupt = self
            .interrupt
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        *interrupt = Some(connection.get_interrupt_handle());
        if self.is_cancelled() {
            interrupt
                .as_ref()
                .expect("interrupt handle was installed above")
                .interrupt();
        }
    }
}

#[cfg(test)]
pub(crate) fn with_sqlite_query_timeout<T>(
    connection: &Connection,
    timeout_ms: Option<NonZeroU64>,
    operation: &str,
    recovery: &str,
    run: impl FnOnce() -> Result<T>,
) -> Result<T> {
    with_sqlite_query_control(connection, timeout_ms, None, operation, recovery, run)
}

pub(crate) fn with_sqlite_query_control<T>(
    connection: &Connection,
    timeout_ms: Option<NonZeroU64>,
    cancellation: Option<Arc<AtomicBool>>,
    operation: &str,
    recovery: &str,
    run: impl FnOnce() -> Result<T>,
) -> Result<T> {
    // One progress callback composes the two independent stop conditions. Installing competing
    // handlers would make the last caller silently disable the earlier deadline or cancellation.
    if timeout_ms.is_none() && cancellation.is_none() {
        return run();
    }
    let deadline = timeout_ms
        .map(|timeout_ms| {
            Instant::now()
                .checked_add(Duration::from_millis(timeout_ms.get()))
                .ok_or_else(|| anyhow!("{operation} timeout_ms is too large for this platform"))
        })
        .transpose()?;
    let progress_cancellation = cancellation.clone();
    // Propagated rather than ignored: a handler that failed to install leaves the query with
    // neither its deadline nor its cancellation, so it would run to completion while the caller
    // believes both are armed.
    connection
        .progress_handler(
            QUERY_PROGRESS_HANDLER_OPCODES,
            Some(move || {
                progress_cancellation
                    .as_ref()
                    .is_some_and(|flag| flag.load(Ordering::Acquire))
                    || deadline.is_some_and(|deadline| Instant::now() >= deadline)
            }),
        )
        .with_context(|| format!("{operation} could not arm its query stop conditions"))?;
    let reset = ProgressHandlerReset(connection);
    let result = run();
    drop(reset);
    result.map_err(|error| {
        if error.chain().any(|cause| {
            matches!(
                cause.downcast_ref::<rusqlite::Error>(),
                Some(rusqlite::Error::SqliteFailure(inner, _))
                    if inner.code == rusqlite::ErrorCode::OperationInterrupted
            )
        }) {
            if cancellation
                .as_ref()
                .is_some_and(|flag| flag.load(Ordering::Acquire))
            {
                anyhow!("{operation} was cancelled")
            } else if let Some(timeout_ms) = timeout_ms {
                anyhow!(
                    "{operation} timed out after {} ms; {recovery}",
                    timeout_ms.get()
                )
            } else {
                error
            }
        } else {
            error
        }
    })
}

macro_rules! session_record_columns {
    () => {
        "s.id, s.provider, s.provider_session_id, s.title, s.summary, s.cwd, s.repo_root, \
         s.created_at, s.updated_at, s.last_message_at, s.preview_text, s.source_path, \
         s.message_count, s.parse_version, s.raw_metadata_json, s.parse_warning, s.discovery_source, \
         s.parent_session_id, s.agent_label"
    };
}

impl Db {
    pub fn open(path: &Path) -> Result<Self> {
        Self::open_with_busy_timeout(path, DEFAULT_BUSY_TIMEOUT_MS)
    }

    pub fn open_with_busy_timeout(path: &Path, busy_timeout_ms: u64) -> Result<Self> {
        let worker_threads = std::thread::available_parallelism().unwrap_or(NonZeroUsize::MIN);
        Self::open_with_threads(path, busy_timeout_ms, worker_threads)
    }

    /// Open a database with an application-owned fixed-size worker runtime.
    pub fn open_with_threads(
        path: &Path,
        busy_timeout_ms: u64,
        worker_threads: NonZeroUsize,
    ) -> Result<Self> {
        if let Some(parent) = path.parent() {
            fs::create_dir_all(parent)
                .with_context(|| format!("failed to create {}", parent.display()))?;
        }
        let conn = Connection::open(path)?;
        conn.busy_timeout(Duration::from_millis(busy_timeout_ms))?;
        crate::sql_functions::register(&conn)?;
        let db = Self {
            conn,
            runtime: Arc::new(ExecutionRuntime::new(worker_threads)),
            access_scope: crate::search_scope::EffectiveAccessScope::All,
            prefilter_min_corpus: TRIGRAM_PREFILTER_MIN_CORPUS,
            trigram_rebuild_delta: TRIGRAM_BASE_REBUILD_DELTA,
            implicit_index_maintenance: true,
            progress: None,
        };
        db.init()?;
        Ok(db)
    }

    /// Open an existing index with SQLite-enforced read-only/query-only authority. This path
    /// deliberately skips [`Db::init`]: it never creates directories, tables, triggers, indexes,
    /// or compatibility objects and never changes durable database contents. SQLite itself may
    /// create or update empty `-wal`/`-shm` coordination sidecars when they are absent. UDF
    /// registration and cache/temp/mmap pragmas affect
    /// only this connection and are required by the shared query implementation.
    pub(crate) fn open_existing_read_only_with_threads(
        path: &Path,
        busy_timeout_ms: u64,
        worker_threads: NonZeroUsize,
    ) -> Result<Self> {
        Self::open_existing_read_only_with_runtime(
            path,
            busy_timeout_ms,
            Arc::new(ExecutionRuntime::new(worker_threads)),
        )
    }

    /// Open a read-only SQLite connection that shares one fixed data-parallel worker budget.
    ///
    /// Opening `B` concurrent readers with the same runtime keeps Rayon worker memory and thread
    /// count `O(T)`, where `T` is the configured worker count, instead of `O(B * T)`. Each reader
    /// still owns independent SQLite connection state so WAL reads may proceed simultaneously.
    pub(crate) fn open_existing_read_only_with_runtime(
        path: &Path,
        busy_timeout_ms: u64,
        runtime: Arc<ExecutionRuntime>,
    ) -> Result<Self> {
        let flags = rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY
            | rusqlite::OpenFlags::SQLITE_OPEN_URI
            | rusqlite::OpenFlags::SQLITE_OPEN_PRIVATE_CACHE;
        // Callers only reach this open after IndexCoordinator::inspect_schema confirmed the
        // index exists and is readable (service.rs bails out earlier, before ever calling this,
        // when the schema state is Missing). So a failure here is NOT "it doesn't exist yet" —
        // either file permissions changed, or another process removed/relocated it in the
        // brief window between that check and this open.
        let conn = Connection::open_with_flags(path, flags).with_context(|| {
            format!(
                "failed to open existing index {} read-only even though it was just verified to \
                 exist; check file permissions, or another process may have removed or \
                 relocated it in the meantime",
                path.display()
            )
        })?;
        conn.busy_timeout(Duration::from_millis(busy_timeout_ms))?;
        crate::sql_functions::register(&conn)?;
        conn.pragma_update(None, "query_only", true)?;
        conn.pragma_update(None, "foreign_keys", true)?;
        conn.pragma_update(None, "temp_store", 2_i64)?;
        conn.pragma_update(None, "cache_size", -SQLITE_PAGE_CACHE_KIB)?;
        conn.pragma_update(None, "mmap_size", SQLITE_MMAP_BYTES)?;
        Ok(Self {
            conn,
            runtime,
            access_scope: crate::search_scope::EffectiveAccessScope::All,
            prefilter_min_corpus: TRIGRAM_PREFILTER_MIN_CORPUS,
            trigram_rebuild_delta: TRIGRAM_BASE_REBUILD_DELTA,
            implicit_index_maintenance: false,
            progress: None,
        })
    }

    /// Clone the application-owned data-parallel runtime for another read-only connection.
    /// Sharing keeps the configured worker budget process-wide instead of multiplying it per
    /// reader; each connection still owns independent SQLite/WAL state.
    pub(crate) fn execution_runtime(&self) -> Arc<ExecutionRuntime> {
        Arc::clone(&self.runtime)
    }

    /// Number of data-parallel workers owned by this database lifecycle.
    pub fn worker_threads(&self) -> usize {
        self.runtime.worker_threads()
    }

    #[cfg(test)]
    fn worker_pool_build_count(&self) -> usize {
        self.runtime.pool_build_count()
    }

    pub(crate) fn interrupt_handle(&self) -> rusqlite::InterruptHandle {
        self.conn.get_interrupt_handle()
    }

    /// Arm this connection so a raised `cancellation` flag stops the running query.
    ///
    /// Returns the failure instead of swallowing it: a caller that believes cancellation is
    /// armed, on a connection where it is not, waits for a query it can no longer stop.
    pub(crate) fn interrupt_while(&self, cancellation: Arc<AtomicBool>) -> Result<()> {
        self.conn
            .progress_handler(
                QUERY_PROGRESS_HANDLER_OPCODES,
                Some(move || cancellation.load(Ordering::Acquire)),
            )
            .context("could not arm query cancellation on this connection")
    }

    pub(crate) fn install_query_cancellation(
        &self,
        cancellation: &QueryCancellation,
    ) -> Result<()> {
        self.interrupt_while(cancellation.flag_arc())?;
        cancellation.register(&self.conn);
        Ok(())
    }

    pub(crate) fn with_read_snapshot<T>(&self, run: impl FnOnce() -> Result<T>) -> Result<T> {
        if !self.conn.is_autocommit() {
            return run();
        }
        let snapshot = ReadSnapshotRollback::begin(&self.conn)?;
        let result = run();
        let cleanup = snapshot.rollback();
        match (result, cleanup) {
            (Ok(value), Ok(())) => Ok(value),
            (Err(error), Ok(())) => Err(error),
            (Ok(_), Err(cleanup_error)) => {
                Err(ReadSnapshotCleanupError::new(None, cleanup_error).into())
            }
            (Err(error), Err(cleanup_error)) => {
                Err(ReadSnapshotCleanupError::new(Some(error), cleanup_error).into())
            }
        }
    }

    pub(crate) fn set_access_scope(
        &mut self,
        access_scope: crate::search_scope::EffectiveAccessScope,
    ) {
        self.access_scope = access_scope;
    }

    pub(crate) const fn access_scope(&self) -> &crate::search_scope::EffectiveAccessScope {
        &self.access_scope
    }

    fn validate_access_scope(&self) -> Result<()> {
        self.access_scope.validate_stable()
    }

    pub fn set_busy_timeout_ms(&self, busy_timeout_ms: u64) -> Result<()> {
        self.conn
            .busy_timeout(Duration::from_millis(busy_timeout_ms))?;
        Ok(())
    }

    pub fn busy_timeout_ms(&self) -> Result<u64> {
        let timeout: i64 = self
            .conn
            .query_row("pragma busy_timeout", [], |row| row.get(0))?;
        Ok(timeout.max(0) as u64)
    }

    /// Return main-database allocation from SQLite metadata without scanning rows or pages.
    pub(crate) fn storage_allocation(&self) -> Result<StorageAllocation> {
        let (page_size, page_count, freelist_count): (i64, i64, i64) = self.conn.query_row(
            "select (select page_size from pragma_page_size),
                    (select page_count from pragma_page_count),
                    (select freelist_count from pragma_freelist_count)",
            [],
            |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)),
        )?;
        if page_size < 0 || page_count < 0 || freelist_count < 0 {
            return Err(anyhow::anyhow!(
                "SQLite returned negative allocation metadata: page_size={page_size}, page_count={page_count}, freelist_count={freelist_count}"
            ));
        }
        let page_size = page_size as u64;
        let total_bytes = page_size.checked_mul(page_count as u64).ok_or_else(|| {
            anyhow::anyhow!(
                "SQLite allocation size overflow: page_size={page_size}, page_count={page_count}"
            )
        })?;
        let reclaimable_bytes = page_size
            .checked_mul(freelist_count as u64)
            .ok_or_else(|| {
                anyhow::anyhow!(
                    "SQLite reclaimable size overflow: page_size={page_size}, freelist_count={freelist_count}"
                )
            })?;
        Ok(StorageAllocation {
            total_bytes,
            reclaimable_bytes,
        })
    }

    pub fn with_busy_timeout_ms<T>(
        &self,
        busy_timeout_ms: u64,
        f: impl FnOnce() -> Result<T>,
    ) -> Result<T> {
        let original = self.busy_timeout_ms()?;
        self.set_busy_timeout_ms(busy_timeout_ms)?;
        let result = f();
        let restore = self.set_busy_timeout_ms(original);
        match (result, restore) {
            (Ok(value), Ok(())) => Ok(value),
            (Err(err), Ok(())) => Err(err),
            (Ok(_), Err(err)) => Err(err),
            // Both failed: chain the restore failure onto the original error instead of
            // discarding it, since the busy_timeout pragma may now be left at
            // `busy_timeout_ms` rather than restored to `original`.
            (Err(err), Err(restore_err)) => Err(err.context(format!(
                "also failed to restore busy_timeout to its prior value ({original}ms): {restore_err:#}"
            ))),
        }
    }

    fn with_immediate_transaction<T>(&self, f: impl FnOnce() -> Result<T>) -> Result<T> {
        self.conn.execute_batch("begin immediate")?;
        let result = f();
        match result {
            Ok(value) => {
                self.conn.execute_batch("commit")?;
                Ok(value)
            }
            Err(err) => {
                let _ = self.conn.execute_batch("rollback");
                Err(err)
            }
        }
    }

    pub fn is_sqlite_busy_error(err: &anyhow::Error) -> bool {
        err.chain().any(|source| {
            source
                .downcast_ref::<rusqlite::Error>()
                .and_then(rusqlite::Error::sqlite_error_code)
                .is_some_and(|code| {
                    matches!(code, ErrorCode::DatabaseBusy | ErrorCode::DatabaseLocked)
                })
        })
    }

    pub fn auto_reindex_is_fresh(&self, interval_ms: u64) -> Result<bool> {
        self.auto_reindex_is_fresh_at(Utc::now().timestamp_millis(), interval_ms)
    }

    fn auto_reindex_is_fresh_at(&self, now_ms: i64, interval_ms: u64) -> Result<bool> {
        let Some((completed_ms, parser_contract)) = self.auto_reindex_freshness_metadata()? else {
            return Ok(false);
        };
        Ok(elapsed_ms(now_ms, completed_ms) < interval_ms
            && parser_contract == crate::source::provider_parse_contract_fingerprint())
    }

    pub fn mark_auto_reindex_complete(&self) -> Result<()> {
        self.mark_auto_reindex_complete_at(Utc::now())
    }

    pub fn auto_reindex_completed_at(&self) -> Result<Option<DateTime<Utc>>> {
        if let Some(value) = self.index_metadata_i64(AUTO_REINDEX_COMPLETED_NS_KEY)? {
            return Ok(DateTime::from_timestamp(
                value.div_euclid(NANOSECONDS_PER_SECOND),
                value.rem_euclid(NANOSECONDS_PER_SECOND) as u32,
            ));
        }
        Ok(self
            .index_metadata_i64(AUTO_REINDEX_COMPLETED_MS_KEY)?
            .and_then(|value| Utc.timestamp_millis_opt(value).single()))
    }

    pub(crate) fn mark_auto_reindex_complete_at(&self, completed_at: DateTime<Utc>) -> Result<()> {
        let completed_ms = completed_at.timestamp_millis();
        let completed_ns = completed_at
            .timestamp_nanos_opt()
            .unwrap_or_else(|| completed_ms.saturating_mul(NANOSECONDS_PER_MILLISECOND));
        let parser_contract = crate::source::provider_parse_contract_fingerprint();
        self.conn.execute(
            "insert into index_metadata (key, value) values
                 (?1, ?2), (?3, ?4), (?5, ?6), (?7, ?8), (?9, ?10), (?11, ?12)
             on conflict(key) do update set value = excluded.value",
            params![
                AUTO_REINDEX_COMPLETED_MS_KEY,
                completed_ms,
                AUTO_REINDEX_COMPLETED_NS_KEY,
                completed_ns,
                AUTO_REINDEX_PARSER_CONTRACT_KEYS[0],
                parser_contract[0],
                AUTO_REINDEX_PARSER_CONTRACT_KEYS[1],
                parser_contract[1],
                AUTO_REINDEX_PARSER_CONTRACT_KEYS[2],
                parser_contract[2],
                AUTO_REINDEX_PARSER_CONTRACT_KEYS[3],
                parser_contract[3],
            ],
        )?;
        Ok(())
    }

    /// Read the timestamp and full parser-contract fingerprint in one bounded SQLite statement.
    ///
    /// Five primary-key probes are independent of corpus size: time is `O(log K)` and retained
    /// memory is `O(1)` for the tiny metadata table of `K` keys. A missing word denotes a legacy
    /// completion marker and deliberately invalidates freshness once after an executable upgrade.
    fn auto_reindex_freshness_metadata(&self) -> Result<Option<(i64, [i64; 4])>> {
        self.conn
            .query_row(
                AUTO_REINDEX_FRESHNESS_SQL,
                params![
                    AUTO_REINDEX_COMPLETED_MS_KEY,
                    AUTO_REINDEX_PARSER_CONTRACT_KEYS[0],
                    AUTO_REINDEX_PARSER_CONTRACT_KEYS[1],
                    AUTO_REINDEX_PARSER_CONTRACT_KEYS[2],
                    AUTO_REINDEX_PARSER_CONTRACT_KEYS[3],
                ],
                |row| {
                    Ok((
                        row.get(0)?,
                        [row.get(1)?, row.get(2)?, row.get(3)?, row.get(4)?],
                    ))
                },
            )
            .optional()
            .map_err(Into::into)
    }

    fn index_metadata_i64(&self, key: &str) -> Result<Option<i64>> {
        self.conn
            .query_row(
                "select value from index_metadata where key = ?1",
                [key],
                |row| row.get(0),
            )
            .optional()
            .map_err(Into::into)
    }

    /// Control whether reads may build persistent derived indexes lazily.
    pub(crate) fn set_implicit_index_maintenance(&mut self, enabled: bool) {
        self.implicit_index_maintenance = enabled;
    }

    /// Inject a sink for human-facing progress notices (e.g. the one-time lazy trigram-index build).
    /// Lets a terminal frontend report progress without the library hardcoding stderr; leave it unset
    /// for silent operation (the MCP server, tests). Call once after [`Db::open`].
    pub fn set_progress_reporter(&mut self, reporter: impl Fn(&str) + Send + Sync + 'static) {
        self.progress = Some(Box::new(reporter));
    }

    /// Emit a progress notice to the injected sink, if any (no-op otherwise).
    fn report_progress(&self, message: &str) {
        if let Some(reporter) = &self.progress {
            reporter(message);
        }
    }

    fn init(&self) -> Result<()> {
        self.conn.execute_batch(
            "
            pragma journal_mode = wal;
            pragma foreign_keys = on;
            -- Read-perf tuning for the analytics/search workload over a multi-GB index:
            -- queries like `corrections` fetch thousands of message rows by rowid (the
            -- role/ts index doesn't cover `content`), which is random I/O across the file.
            -- A larger page cache + memory-mapped reads + in-memory temp store cut that
            -- cost; synchronous=normal is the documented-safe durability level under WAL.
            pragma synchronous = normal;
            pragma temp_store = memory;
            create table if not exists sessions (
                id text primary key,
                provider text not null,
                provider_session_id text not null,
                title text,
                summary text,
                cwd text,
                repo_root text,
                created_at text,
                updated_at text,
                last_message_at text,
                preview_text text not null,
                source_path text not null,
                message_count integer,
                parse_version text not null,
                raw_metadata_json text,
                parse_warning text,
                discovery_source text not null,
                parent_session_id text,
                agent_label text
            );
            create table if not exists transcripts (
                session_id text primary key references sessions(id) on delete cascade,
                transcript_text text not null
            );
            create table if not exists files_seen (
                provider text not null,
                source_path text not null,
                mtime_ns integer not null,
                size_bytes integer not null,
                last_indexed_at text not null,
                content_hash text,
                parse_version text not null default '',
                -- Incremental tail-parse checkpoint (§7): byte offset (at a newline boundary)
                -- up to which the file is parsed, and a fingerprint of the file's leading bytes
                -- used to detect rewrite/rotation. NULL = no checkpoint → always a full parse.
                tail_byte_offset integer,
                prefix_fingerprint text,
                primary key(provider, source_path)
            );
            create table if not exists index_metadata (
                key text primary key,
                value integer not null
            );
            create index if not exists idx_sessions_provider on sessions(provider);
            create index if not exists idx_sessions_updated_at on sessions(updated_at desc);
            create index if not exists idx_sessions_provider_id on sessions(provider_session_id);
            create table if not exists messages (
                id integer primary key,
                session_id text not null references sessions(id) on delete cascade,
                provider text not null,
                seq integer not null,
                role text not null,
                ts text,
                tool_name text,
                kind text not null default 'unknown',
                tool_call_id text,
                is_compaction integer not null default 0,
                content text not null,
                authorship text not null default 'unknown',
                correlation_authority text,
                correlation_scope text,
                correlation_id text,
                record_relation text not null default 'unknown'
                    check (record_relation in ('original', 'mirror', 'unknown')),
                check (
                    (correlation_authority is null and correlation_scope is null and correlation_id is null)
                    or
                    (correlation_authority is not null and correlation_scope is not null and correlation_id is not null)
                )
            );
            -- Bare ts index for date-range message filters that span all roles; the
            -- composites below lead with role/session_id and so cannot serve a bare
            -- `ts between ? and ?` scan.
            create index if not exists idx_messages_ts on messages(ts);
            -- Composite indexes serve the hot filter + ORDER BY combinations straight from
            -- the index (no temp B-tree sort) and, by leftmost-prefix, subsume a bare
            -- (session_id) or (role) index: (session_id, seq) covers `where session_id=?`
            -- [+ `order by seq`] (message search / get / context); (role, ts) covers
            -- `where role=?` [+ `order by ts`] (corrections / planning / stats). Older
            -- branch builds created standalone (session_id) and (role) indexes before these
            -- composites existed — drop them so every index converges on this final shape;
            -- they were pure write-amplification (an upstream index never had them).
            drop index if exists idx_messages_session;
            drop index if exists idx_messages_role;
            create index if not exists idx_messages_session_seq on messages(session_id, seq);
            create index if not exists idx_messages_provider_session_seq
                on messages(provider, session_id, seq);
            create index if not exists idx_messages_role_ts on messages(role, ts);
            create index if not exists idx_messages_tool_name
                on messages(tool_name) where tool_name is not null;
            create table if not exists file_edits (
                id integer primary key,
                session_id text not null references sessions(id) on delete cascade,
                provider text not null,
                seq integer not null,
                ts text,
                tool text not null,
                file_path text not null,
                file_name text not null,
                new_content text,
                edits_json text
            );
            create index if not exists idx_file_edits_session on file_edits(session_id);
            create index if not exists idx_file_edits_provider on file_edits(provider);
            create index if not exists idx_file_edits_path on file_edits(file_path);
            create index if not exists idx_file_edits_name on file_edits(file_name);
            ",
        )?;
        self.conn
            .pragma_update(None, "cache_size", -SQLITE_PAGE_CACHE_KIB)?;
        self.conn
            .pragma_update(None, "mmap_size", SQLITE_MMAP_BYTES)?;
        // `create table if not exists` does not add columns to a version-1 index. Additive
        // migration keeps legacy rows readable; `user_version < SCHEMA_VERSION` then requests
        // the full parser backfill that replaces their `unknown` kinds with provider evidence.
        for (name, definition) in [
            ("kind", "kind text not null default 'unknown'"),
            ("tool_call_id", "tool_call_id text"),
            ("authorship", "authorship text not null default 'unknown'"),
            ("correlation_authority", "correlation_authority text"),
            ("correlation_scope", "correlation_scope text"),
            ("correlation_id", "correlation_id text"),
            (
                "record_relation",
                "record_relation text not null default 'unknown'",
            ),
        ] {
            let exists: bool = self.conn.query_row(
                "select exists(select 1 from pragma_table_info('messages') where name = ?1)",
                params![name],
                |row| row.get(0),
            )?;
            if !exists {
                self.conn
                    .execute_batch(&format!("alter table messages add column {definition}"))?;
            }
        }
        self.conn.execute_batch(
            "drop index if exists idx_messages_authorship_role_provider_ts;
             create index if not exists idx_messages_tool_calls
                 on messages(session_id, seq) where kind = 'tool_call';
             create index if not exists idx_messages_provider_session_seq
                 on messages(provider, session_id, seq);
             create index if not exists idx_messages_session_authorship_relation_seq
                 on messages(session_id, authorship, record_relation, seq);
             create index if not exists idx_messages_authorship_relation_ts
                 on messages(authorship, record_relation, ts desc, session_id, seq);
             create index if not exists idx_messages_correlation
                 on messages(correlation_authority, correlation_scope, correlation_id)
                 where correlation_id is not null;
             create table if not exists message_content_parts (
                 message_id integer not null references messages(id) on delete cascade,
                 ordinal integer not null check (ordinal >= 0),
                 start_char integer not null check (start_char >= 0),
                 end_char integer not null check (end_char > start_char),
                 authorship text not null,
                 origin text not null,
                 primary key(message_id, ordinal)
             ) without rowid;
             create trigger if not exists messages_correlation_all_or_none_insert
             before insert on messages
             when ((new.correlation_authority is not null)
                   + (new.correlation_scope is not null)
                   + (new.correlation_id is not null)) not in (0, 3)
             begin
                 select raise(abort, 'message correlation authority, scope, and id must be all null or all non-null');
             end;
             create trigger if not exists messages_correlation_all_or_none_update
             before update of correlation_authority, correlation_scope, correlation_id on messages
             when ((new.correlation_authority is not null)
                   + (new.correlation_scope is not null)
                   + (new.correlation_id is not null)) not in (0, 3)
             begin
                 select raise(abort, 'message correlation authority, scope, and id must be all null or all non-null');
             end;",
        )?;
        // `sessions_fts` (an FTS5 copy of every title, summary, preview, and transcript) stopped
        // being read on 2026-07-22, when session search moved to scoring the complete corpus, and
        // stayed maintained: on one real index it held 464 MB (a second copy of every transcript
        // plus its tokens) and every session upsert re-tokenized the whole transcript into it. This
        // build writes nothing into it. It is retired in place rather than removed: an aise before
        // 1.0.0rc2 on the same machine (a pinned MCP registration, a second package manager)
        // requires the table in its layout check, refuses existing-only reads without it, and on a
        // writable open rebuilds every derived message-search index to restore it, after which
        // this build would remove it again. So the copy an earlier build filled is emptied once
        // (`SESSIONS_FTS_RETIRED_KEY`, the pages return to the freelist and `aise compact` gives
        // them back), an empty table is kept for that older layout check, and an older writer that
        // refills it is left alone.
        let retired: bool = self.conn.query_row(
            "select exists(select 1 from index_metadata where key = ?1)",
            params![SESSIONS_FTS_RETIRED_KEY],
            |row| row.get(0),
        )?;
        if !retired {
            self.conn
                .execute_batch("drop table if exists sessions_fts")?;
            self.conn.execute(
                "insert into index_metadata (key, value) values (?1, 1)
                 on conflict(key) do update set value = excluded.value",
                params![SESSIONS_FTS_RETIRED_KEY],
            )?;
        }
        self.conn.execute_batch(
            "create virtual table if not exists sessions_fts using fts5(
                title, summary, preview_text, transcript_text
            )",
        )?;
        // External-content FTS over message bodies. Message search no longer lets FTS tokenization
        // define literal semantics, but this index is still kept current for vocabulary,
        // compatibility, and any future explicit word-search surface. The insert/delete/update
        // triggers are the full canonical FTS5 external-content set, written in the
        // `'delete'`-command form that AFTER triggers require (it passes the OLD content so
        // the right tokens are removed; a plain `delete from` here risks index corruption).
        // So every mutation path stays in sync: the delete+reinsert reindex path
        // (upsert_session) and any future in-place `update messages set content = ...`.
        crate::fts::install_released_message_word_index(&self.conn)?;
        // Backfill messages_fts if messages exist but its index is empty — e.g. an index
        // file from before messages_fts existed, or one whose FTS shadow was cleared. FTS5
        // triggers only maintain the index for mutations made AFTER they exist, so the
        // `'rebuild'` command is the canonical way to (re)populate an external-content index
        // from its content table. Without this, message search (which queries messages_fts)
        // would silently return nothing for such an index.
        //
        // NOTE: `count(*) from messages_fts` reflects the external CONTENT table (messages),
        // not the index, so it can't detect an empty index. The `_docsize` shadow holds one
        // row per INDEXED document, so its count is the true index population.
        // Initialization needs only empty/non-empty state. EXISTS stops after the first row;
        // COUNT(*) scanned 1.49M rows plus both FTS populations on every CLI/MCP/Python open.
        let messages_exist: bool =
            self.conn
                .query_row("select exists(select 1 from messages)", [], |row| {
                    row.get(0)
                })?;
        // The class index is free while the table is empty. On a populated index that lacks it
        // (written by an older aise) the build is one full scan under the write lock, so it is
        // left to the elected refresh writer rather than paid inside every query process's open.
        if !messages_exist {
            self.ensure_message_kind_index()?;
        }
        // A brand-new empty database has no incompatible data to migrate. Install the current
        // layout immediately so its first indexing pass maintains both FTS indexes atomically.
        // Existing schema-0 databases with messages still take the parser-backfill/v3 path first.
        if self.schema_version()? == 0 && !messages_exist {
            // Install the target layout and stamp the version ATOMICALLY. `user_version` is a
            // transactional header field, so a single transaction makes "create the FTS5 message
            // objects" and "declare this database current" all-or-nothing: a crash can never commit
            // the current stamp over a partially-built layout — the exact v4-stamped-but-missing-
            // trigram hybrid that the self-heal path (see `SchemaState::RepairableLayout`) exists to
            // repair. Ordering alone previously kept this safe; the transaction also protects any
            // future reordering.
            let tx = self.conn.unchecked_transaction()?;
            crate::fts::install_target_message_search_indexes(&tx)?;
            tx.execute_batch(&format!("pragma user_version = {SCHEMA_VERSION}"))?;
            tx.commit()?;
        }
        let indexed_messages_exist: bool = self.conn.query_row(
            "select exists(select 1 from messages_fts_docsize)",
            [],
            |row| row.get(0),
        )?;
        if messages_exist && !indexed_messages_exist {
            self.conn
                .execute_batch("insert into messages_fts(messages_fts) values('rebuild')")?;
        }
        // Literal/regex PREFILTER over message content (the Google Code Search trigram technique):
        // turns substring and regex-literal anchors into indexed candidate queries that exact
        // literal or Rust regex verification checks afterward. This is the custom, parallel-built
        // [`crate::trigram_index`] — NOT an FTS5 virtual table — because FTS5's trigram tokenizer
        // builds single-threaded inside the one SQLite writer, which is ~80% of a cold build
        // (measured ~145 s for 1.8 GB of content). The custom index tokenizes with Rayon and
        // bulk-loads compact delta-varint postings: ~5x faster build, same on-disk size, sub-3 ms
        // candidate queries. It is built LAZILY on first eligible message content search
        // ([`Db::ensure_trigram_base`]), so `reindex` does NO trigram work and
        // `list`/`show`/`paths`/`resume` never pay for it.
        if self.schema_version()? < 4 {
            crate::trigram_index::ensure_schema(&self.conn)?;
            // No released schema before v4 owns an FTS5 messages_trigram table. Remove abandoned
            // development copies so the v3 custom index remains the sole compatibility path.
            self.conn.execute_batch(
                "drop trigger if exists messages_tri_ai;
                 drop trigger if exists messages_tri_ad;
                 drop trigger if exists messages_tri_au;
                 drop table if exists messages_trigram_terms;
                 drop table if exists messages_trigram_vocab;
                 drop table if exists messages_trigram;",
            )?;
        }
        // Zero-storage word-term-frequency view (fts5vocab 'row' → term,doc,cnt) for `vocab`.
        // (Trigram vocab is served from the custom index's `trigram_postings.df` column instead.)
        self.conn.execute_batch(
            "create virtual table if not exists messages_vocab
                 using fts5vocab('messages_fts', 'row');",
        )?;
        // Self-enforce the v4 message-search layout on this writable open. `install_released_message_
        // word_index` above uses `create trigger if not exists`, so on a database stamped current
        // whose dual `messages_fts`+`messages_trigram` triggers were dropped (or whose FTS5 trigram
        // tables are missing) it would otherwise silently leave word-only triggers and stop
        // maintaining `messages_trigram`, making substring/fuzzy search return incomplete results
        // with no error. Rebuilding from the intact `messages` rows here means a direct `Db::open`
        // (embedder path) — not just `SessionSearch::open`'s coordinator — cannot leave a v4 index
        // half-maintained. Only fires when the base rows a rebuild would read are present; the
        // rebuild is idempotent, so a consistent layout costs one schema scan and no rebuild.
        let schema_version = self.schema_version()?;
        let message_search_layout_problem = match schema_version {
            4 => crate::indexer::message_search_layout_problem(&self.conn)?,
            SCHEMA_VERSION => crate::indexer::current_schema_layout_problem(&self.conn)?,
            _ => None,
        };
        if message_search_layout_problem.is_some() && crate::indexer::base_data_intact(&self.conn)?
        {
            self.migrate_message_search_schema_exclusive()?;
        }
        // Evolve an existing `files_seen` (a rebuildable cache) to carry the tail-parse
        // checkpoint columns. `create table if not exists` won't add columns to a table that
        // already exists, so add them idempotently; NULL on existing rows means "no checkpoint"
        // which the indexer treats as a full parse — always safe.
        self.ensure_column("files_seen", "tail_byte_offset", "tail_byte_offset integer")?;
        self.ensure_column(
            "files_seen",
            "prefix_fingerprint",
            "prefix_fingerprint text",
        )?;
        let parse_version_added = self.ensure_column(
            "files_seen",
            "parse_version",
            "parse_version text not null default ''",
        )?;
        if parse_version_added {
            self.backfill_source_parse_versions()?;
        }
        // Same reasoning for the subagent-origin columns on an existing `sessions` table. NULL
        // on existing rows means "not known to be a subagent run", which is what every row
        // indexed before these columns existed truthfully was. Rows gain real values on the
        // next reindex, so no backfill is possible or needed: the fact lives in the transcript.
        self.ensure_column("sessions", "parent_session_id", "parent_session_id text")?;
        self.ensure_column("sessions", "agent_label", "agent_label text")?;
        Ok(())
    }

    /// Add `column_decl` to `table` if the column is not already present (idempotent
    /// schema evolution). Used for the `files_seen` cache columns; a no-op once the
    /// column exists, so it is safe to call on every `open`.
    fn ensure_column(&self, table: &str, column: &str, column_decl: &str) -> Result<bool> {
        let present = self
            .conn
            .prepare(&format!("pragma table_info({table})"))?
            .query_map([], |row| row.get::<_, String>(1))?
            .filter_map(Result::ok)
            .any(|name| name == column);
        if !present {
            self.conn
                .execute_batch(&format!("alter table {table} add column {column_decl}"))?;
        }
        Ok(!present)
    }

    fn backfill_source_parse_versions(&self) -> Result<()> {
        self.conn.execute_batch(
            "with source_versions as (
                 select provider, source_path, min(parse_version) as parse_version
                 from sessions
                 group by provider, source_path
                 having count(distinct parse_version) = 1
             )
             update files_seen
             set parse_version = coalesce((
                 select source_versions.parse_version
                 from source_versions
                 where source_versions.provider = files_seen.provider
                   and source_versions.source_path = files_seen.source_path
             ), '')
             where parse_version = ''",
        )?;
        Ok(())
    }

    /// Ensure the custom [`crate::trigram_index`] base is built and current enough to serve as the
    /// regex/substring prefilter, returning its `base_max_id`. Builds (in parallel) when the base
    /// is empty or the un-indexed delta (`max(id) - base_max`) exceeds
    /// `TRIGRAM_BASE_REBUILD_DELTA`; otherwise the recent delta is left for the caller to
    /// direct-scan (`id > base_max`). This makes the one-time parallel build lazy — paid on first
    /// regex use, never by `list`/`show`/`paths`/`resume` — and keeps incremental reindex free of
    /// trigram work (no triggers): new messages just accumulate in the delta until a rebuild.
    pub(crate) fn ensure_trigram_base(&self) -> Result<i64> {
        anyhow::ensure!(
            self.schema_version()? < 4,
            "custom trigram maintenance is unavailable on schema v4; SQLite FTS5 maintains messages_trigram incrementally"
        );
        if !crate::trigram_index::schema_is_compatible(&self.conn)? {
            // trigram_postings/trigram_meta are entirely derived from `messages` (like the
            // FTS5 prefilter they replace on schema v4+), so an incompatible derived-table shape
            // is safe to rebuild. Do not infer corruption from an arbitrary base_max_id error:
            // lock, I/O, and database-level failures must propagate without dropping anything.
            anyhow::ensure!(
                self.implicit_index_maintenance,
                "substring/regex search index has an incompatible schema and automatic \
                 maintenance is disabled; rerun without --index-refresh existing-only to rebuild it"
            );
            return self
                .rebuild_trigram_base_with_writer_lock()
                .map(|rebuild| rebuild.base_max);
        }
        let base_max = crate::trigram_index::base_max_id(&self.conn)?;
        if !self.implicit_index_maintenance {
            return Ok(base_max);
        }
        let max_id: i64 =
            self.conn
                .query_row("select coalesce(max(id), 0) from messages", [], |row| {
                    row.get(0)
                })?;
        if (base_max == 0 && max_id > 0) || (max_id - base_max) > self.trigram_rebuild_delta {
            return match self.rebuild_trigram_base_with_writer_lock() {
                Ok(rebuild) => Ok(rebuild.base_max),
                Err(err) if Self::is_sqlite_busy_error(&err) => {
                    self.report_progress(
                        "substring/regex search index is already being updated; scanning the unindexed delta directly",
                    );
                    Ok(base_max)
                }
                Err(err) => Err(err),
            };
        }
        Ok(base_max)
    }

    fn rebuild_trigram_base_with_writer_lock(&self) -> Result<TrigramRebuild> {
        self.with_immediate_transaction(|| {
            let schema_compatible = crate::trigram_index::schema_is_compatible(&self.conn)?;
            if !schema_compatible {
                self.report_progress(
                    "substring/regex search index had an incompatible schema; rebuilding it from the message table",
                );
                self.conn.execute_batch(
                    "drop table if exists trigram_postings; drop table if exists trigram_meta;",
                )?;
                crate::trigram_index::ensure_schema(&self.conn)?;
            }
            let base_max = crate::trigram_index::base_max_id(&self.conn)?;
            let max_id: i64 =
                self.conn
                    .query_row("select coalesce(max(id), 0) from messages", [], |row| {
                        row.get(0)
                    })?;
            if schema_compatible
                && !((base_max == 0 && max_id > 0)
                    || (max_id - base_max) > self.trigram_rebuild_delta)
            {
                return Ok(TrigramRebuild {
                    base_max,
                    rebuilt: false,
                });
            }

            // The one-time parallel build can take tens of seconds on a large corpus; notify via
            // the injected progress sink (the CLI prints it; the MCP server stays silent) so a first
            // regex/substring search isn't an unexplained pause. Holding BEGIN IMMEDIATE here is a
            // deliberate maintenance lock: readers keep working in WAL mode, while competing
            // writers/builders wait or fall back according to their configured busy timeout.
            let count: i64 = self
                .conn
                .query_row("select count(*) from messages", [], |row| row.get(0))?;
            self.report_progress(&format!(
                "building substring/regex search index in parallel (one-time over {count} messages)…"
            ));
            let base_max = crate::trigram_index::build_in_current_transaction(
                &self.conn,
                &self.runtime,
            )?;
            Ok(TrigramRebuild {
                base_max,
                rebuilt: true,
            })
        })
        .and_then(|rebuild| {
            if rebuild.rebuilt {
                // Fold the large build out of the WAL so the -wal file doesn't retain the index size.
                self.checkpoint_truncate()?;
            }
            Ok(rebuild)
        })
    }

    /// Stage a regex prefilter's candidate row ids into the per-connection temp table
    /// `_trigram_cand`: the base candidates (`id <= base_max`) PLUS the un-indexed delta
    /// (`id > base_max`), which the caller's Rust regex then re-verifies. The caller joins
    /// `_trigram_cand` to restrict the scan. Temp tables are per-connection, so this is safe for
    /// the one-connection-per-command CLI and the single-connection MCP server.
    fn stage_candidates(
        &self,
        base_max: i64,
        candidates: &std::collections::HashSet<i64>,
    ) -> Result<()> {
        self.conn.execute_batch(
            "create temp table if not exists _trigram_cand (id integer primary key);
             delete from _trigram_cand;",
        )?;
        // Insert all candidates in ONE transaction: an unselective pattern can yield tens of
        // thousands of ids, and per-statement auto-commits would add needless overhead. The temp
        // table lives in memory (temp_store=memory), so this is a single in-memory batch.
        let tx = self.conn.unchecked_transaction()?;
        {
            let mut stmt = tx.prepare("insert or ignore into _trigram_cand(id) values (?1)")?;
            for id in candidates {
                stmt.execute([id])?;
            }
        }
        tx.execute(
            "insert or ignore into _trigram_cand(id) select id from messages where id > ?1",
            [base_max],
        )?;
        tx.commit()?;
        Ok(())
    }

    /// Run a TRUNCATE WAL checkpoint: fold the write-ahead log back into the main database file
    /// and shrink `-wal` to zero. Cheap when the WAL is small (a no-op-ish), worth calling after
    /// large writes (the trigram rebuild, a big reindex) so the `-wal` file does not accumulate
    /// gigabytes. Best-effort: a concurrent reader can leave it partial, which is harmless.
    pub fn checkpoint_truncate(&self) -> Result<()> {
        // `wal_checkpoint` returns a row (busy, log, checkpointed); ignore it.
        self.conn
            .query_row("pragma wal_checkpoint(truncate)", [], |_| Ok(()))
            .or_else(|err| match err {
                rusqlite::Error::QueryReturnedNoRows => Ok(()),
                other => Err(other),
            })?;
        Ok(())
    }

    #[cfg(test)]
    pub(crate) fn execute_batch_for_test(&self, sql: &str) -> Result<()> {
        self.conn.execute_batch(sql)?;
        Ok(())
    }

    #[cfg(test)]
    pub(crate) fn wal_checkpoint_busy_for_test(&self) -> Result<i64> {
        self.conn
            .query_row("pragma wal_checkpoint(passive)", [], |row| row.get(0))
            .map_err(Into::into)
    }

    /// Merge each FTS5 index's b-tree segments into one (the `'optimize'` command). A full reindex
    /// deletes and reinserts every message, which leaves `messages_fts` with many unmerged segments
    /// — measured to roughly DOUBLE its on-disk size (≈1.0 GB → ≈2.0 GB on a 637k-message corpus)
    /// and to slow queries. `'optimize'` merges them, freeing the redundant pages (reused by later
    /// writes, or returned to the OS by a one-time `VACUUM`). Call ONLY after a full reindex: it
    /// rewrites the whole index, so it must never run on the per-command incremental path. The cost
    /// is in `messages_fts`, amortized over a rare full rebuild.
    pub fn optimize_fts(&self) -> Result<()> {
        self.conn
            .execute_batch("insert into messages_fts(messages_fts) values('optimize');")?;
        if self.schema_version()? >= 4 {
            self.conn.execute_batch(
                "insert into messages_trigram(messages_trigram) values('optimize');",
            )?;
        }
        Ok(())
    }

    /// Reclaim free pages to the OS by rewriting the database file (`VACUUM`). Run AFTER
    /// [`Db::optimize_fts`]: VACUUM repacks page bytes but does NOT merge FTS5 segments, so optimize
    /// must logically compact the index first (the documented OPTIMIZE → VACUUM order). VACUUM takes
    /// an exclusive lock and needs up to ~2x the database size in free disk while it runs, and cannot
    /// run inside a transaction — `execute_batch` runs it in autocommit.
    pub fn vacuum(&self) -> Result<()> {
        self.conn.execute_batch("vacuum")?;
        Ok(())
    }

    /// True when the on-disk `user_version` is behind [`SCHEMA_VERSION`], i.e. a new
    /// schema generation has shipped and a one-time full reindex is needed to backfill
    /// new tables/columns (the old rows were skipped by incremental indexing).
    pub fn needs_backfill(&self) -> Result<bool> {
        Ok(self.schema_version()? < PARSER_SCHEMA_VERSION)
    }

    /// True when the current binary can query this schema correctly before parser-derived rows
    /// are refreshed. Future schema generations fail closed because compatibility is unknown.
    pub fn schema_is_readable(&self) -> Result<bool> {
        Ok(match self.schema_state()? {
            SchemaState::Current => true,
            SchemaState::Older { current, .. } => current >= MIN_READABLE_SCHEMA_VERSION,
            SchemaState::Missing
            | SchemaState::Newer { .. }
            | SchemaState::UnknownProviders { .. }
            | SchemaState::RepairableLayout { .. }
            | SchemaState::RecoveryRequired { .. } => false,
        })
    }

    pub(crate) fn schema_state(&self) -> Result<SchemaState> {
        match SchemaState::from_version(self.schema_version()?) {
            SchemaState::Current => {
                let providers = unknown_index_providers(&self.conn)?;
                Ok(if providers.is_empty() {
                    SchemaState::Current
                } else {
                    SchemaState::UnknownProviders { providers }
                })
            }
            other => Ok(other),
        }
    }

    pub fn schema_version(&self) -> Result<i64> {
        self.conn
            .query_row("pragma user_version", [], |row| row.get(0))
            .map_err(Into::into)
    }

    /// Promote the message-search layout on this already-elected writer connection. The caller
    /// must hold the cross-process maintenance permit for the complete full-reindex + migration
    /// operation; SQLite independently requires an exclusive journal transition and restores WAL.
    pub(crate) fn migrate_message_search_schema_exclusive(&self) -> Result<()> {
        let schema_version = self.schema_version()?;
        // Idempotent: if the database already owns the current layout there is nothing to rebuild.
        // This lets `init()` self-enforce a broken v4 open while a caller that ALSO requests the heal
        // (SessionSearch::open's coordinator) becomes a cheap no-op instead of a second full rebuild.
        if schema_version == SCHEMA_VERSION
            && crate::indexer::current_schema_layout_problem(&self.conn)?.is_none()
        {
            return Ok(());
        }
        if schema_version == 4
            && crate::indexer::message_search_layout_problem(&self.conn)?.is_none()
        {
            return Ok(());
        }
        // Notify via the injected progress sink (the CLI prints it; the MCP server and tests stay
        // silent) so a one-time in-place rebuild of the message-search indexes isn't an unexplained
        // pause. Mirrors the lazy trigram-base rebuild notice in
        // [`Db::rebuild_trigram_base_with_writer_lock`].
        let count: i64 = self
            .conn
            .query_row("select count(*) from messages", [], |row| row.get(0))?;
        self.report_progress(&format!(
            "rebuilding message-search indexes in place (one-time over {count} messages)…"
        ));
        // Repairing a v4 hybrid rebuilds only its derived FTS objects and preserves the v4 stamp:
        // source rows have not yet been reparsed, so promoting them would falsely claim schema-5
        // provenance. A full reindex first calls `mark_schema_current`, making this target 5.
        let target_version = if schema_version == 4 {
            4
        } else {
            SCHEMA_VERSION
        };
        crate::fts::migrate_message_search_schema_offline(&self.conn, target_version)
    }

    /// Stamp parser-derived rows after a full reindex without bypassing the schema-4 FTS gate.
    ///
    /// A database already at v4 owns the released FTS layout, so reparsing can safely promote it
    /// to schema 5. A pre-v4 database stops at parser generation 3; the caller must then run
    /// `Self::migrate_message_search_schema_exclusive`, which atomically builds the derived FTS
    /// objects and stamps schema 5. This two-stage rule prevents a current stamp over missing
    /// trigram objects.
    pub fn mark_schema_current(&self) -> Result<()> {
        let target = if self.schema_version()? >= 4 {
            PARSER_SCHEMA_VERSION
        } else {
            PRE_FTS_PARSER_SCHEMA_VERSION
        };
        self.conn
            .execute_batch(&format!("pragma user_version = {target}"))?;
        Ok(())
    }

    /// Explicit, total wipe of all indexed data. NOT used by [`crate::indexer::reindex`],
    /// which is a durable archive (it never deletes sessions whose source files were
    /// removed). This is the deliberate "start over" reset for embedders / corruption
    /// recovery; the user-facing equivalent is deleting the index file.
    pub fn clear_all(&self) -> Result<()> {
        // One transaction so an interruption (or a failing statement) leaves the index either fully
        // cleared or fully intact — never a logically inconsistent mix such as sessions carrying a
        // stale message_count while their messages have already been deleted.
        self.with_immediate_transaction(|| {
            self.conn.execute_batch(
                "
                delete from transcripts;
                delete from messages;
                delete from file_edits;
                delete from sessions;
                delete from files_seen;
                ",
            )?;
            Ok(())
        })
    }

    pub(crate) fn clear_trigram_base(&self) -> Result<()> {
        if self.schema_version()? >= 4 {
            return Ok(());
        }
        self.conn.execute_batch(
            "
            delete from trigram_postings;
            delete from trigram_meta;
            ",
        )?;
        Ok(())
    }

    pub fn is_file_current(
        &self,
        provider: Provider,
        path: &str,
        mtime_ns: i64,
        size: i64,
        parse_version: &str,
    ) -> Result<bool> {
        Ok(
            self.source_file_refresh_state(provider, path, mtime_ns, size, parse_version)?
                == SourceFileRefreshState::Current,
        )
    }

    /// Resolve freshness and parser compatibility from one indexed row read.
    ///
    /// A changed parser must replace the stored prefix even if a grown file otherwise satisfies
    /// the append-only boundary check. One typed result drives both the skip and replacement
    /// decisions, avoiding a time-of-check/time-of-use seam between two database reads. Lookup is
    /// `O(log F)` through the `files_seen` primary key and retains one row.
    pub(crate) fn source_file_refresh_state(
        &self,
        provider: Provider,
        path: &str,
        mtime_ns: i64,
        size: i64,
        parse_version: &str,
    ) -> Result<SourceFileRefreshState> {
        Ok(match self.file_seen_state(provider, path)? {
            None => SourceFileRefreshState::New,
            Some((_, _, stored_version)) if stored_version != parse_version => {
                SourceFileRefreshState::ChangedParser
            }
            Some((stored_mtime, stored_size, _))
                if stored_mtime == mtime_ns && stored_size == size =>
            {
                SourceFileRefreshState::Current
            }
            Some(_) => SourceFileRefreshState::ChangedSameParser,
        })
    }

    fn file_seen_state(
        &self,
        provider: Provider,
        path: &str,
    ) -> Result<Option<(i64, i64, String)>> {
        self.conn
            .query_row(
                "select mtime_ns, size_bytes, parse_version from files_seen
                 where provider = ?1 and source_path = ?2",
                params![provider.as_str(), path],
                |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)),
            )
            .optional()
            .map_err(Into::into)
    }

    pub(crate) fn indexed_source_identities(
        &self,
    ) -> Result<Vec<(Provider, String, usize, String)>> {
        let mut stmt = self.conn.prepare(
            "select provider, source_path, count(*), min(id) from sessions
             group by provider, source_path",
        )?;
        let rows = stmt
            .query_map([], |row| {
                Ok((
                    decode_db_enum(
                        row.get::<_, String>(0)?,
                        0,
                        "sessions.provider",
                        Provider::from_db_str,
                    )?,
                    row.get::<_, String>(1)?,
                    row.get::<_, i64>(2)? as usize,
                    row.get::<_, String>(3)?,
                ))
            })?
            .collect::<rusqlite::Result<Vec<_>>>()?;
        Ok(rows)
    }

    pub(crate) fn exact_session_source_path(&self, id: &str) -> Result<Option<String>> {
        self.conn
            .query_row(
                "select source_path from sessions where id = ?1",
                params![id],
                |row| row.get(0),
            )
            .optional()
            .map_err(Into::into)
    }

    pub fn upsert_session(
        &self,
        parsed: &ParsedSession,
        mtime_ns: i64,
        size_bytes: i64,
    ) -> Result<()> {
        self.upsert_session_with_mode(parsed, mtime_ns, size_bytes, true, &[])
    }

    /// Persist a fully re-parsed session and force message/file rows to be replaced, even
    /// when the new parse appears to be an append-only growth of the old rows. Use this
    /// for explicit full reindex/backfill paths so parser/schema fixes repair existing
    /// rows instead of preserving a stale prefix for performance.
    pub fn replace_session(
        &self,
        parsed: &ParsedSession,
        mtime_ns: i64,
        size_bytes: i64,
    ) -> Result<()> {
        self.upsert_session_with_mode(parsed, mtime_ns, size_bytes, false, &[])
    }

    pub(crate) fn upsert_session_reconciling_sources(
        &self,
        parsed: &ParsedSession,
        mtime_ns: i64,
        size_bytes: i64,
        source_aliases: &[String],
        allow_append_optimization: bool,
    ) -> Result<()> {
        self.upsert_session_with_mode(
            parsed,
            mtime_ns,
            size_bytes,
            allow_append_optimization,
            source_aliases,
        )
    }

    fn upsert_session_with_mode(
        &self,
        parsed: &ParsedSession,
        mtime_ns: i64,
        size_bytes: i64,
        allow_append_optimization: bool,
        source_aliases: &[String],
    ) -> Result<()> {
        let tx = self.conn.unchecked_transaction()?;
        let session = &parsed.session;
        // A complete source parse represents one canonical session. Parser improvements or
        // mutable sidecar metadata can change the provider session ID; remove prior identities
        // for this provider/source in the same transaction before publishing the replacement.
        // Preserve unrelated providers even if they happen to name the same filesystem path.
        for alias in source_aliases
            .iter()
            .filter(|alias| alias.as_str() != session.source_path)
        {
            tx.execute(
                "delete from sessions where provider = ?1 and source_path = ?2",
                params![session.provider.as_str(), alias],
            )?;
            tx.execute(
                "delete from files_seen where provider = ?1 and source_path = ?2",
                params![session.provider.as_str(), alias],
            )?;
        }
        tx.execute(
            "delete from sessions
             where provider = ?1 and source_path = ?2 and id != ?3",
            params![session.provider.as_str(), session.source_path, session.id],
        )?;
        tx.execute(
            "
            insert into sessions (
                id, provider, provider_session_id, title, summary, cwd, repo_root, created_at,
                updated_at, last_message_at, preview_text, source_path, message_count, parse_version,
                raw_metadata_json, parse_warning, discovery_source, parent_session_id, agent_label
            ) values (
                ?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8,
                ?9, ?10, ?11, ?12, ?13, ?14,
                ?15, ?16, ?17, ?18, ?19
            )
            on conflict(id) do update set
                provider = excluded.provider,
                provider_session_id = excluded.provider_session_id,
                title = excluded.title,
                summary = excluded.summary,
                cwd = excluded.cwd,
                repo_root = excluded.repo_root,
                created_at = excluded.created_at,
                updated_at = excluded.updated_at,
                last_message_at = excluded.last_message_at,
                preview_text = excluded.preview_text,
                source_path = excluded.source_path,
                message_count = excluded.message_count,
                parse_version = excluded.parse_version,
                raw_metadata_json = excluded.raw_metadata_json,
                parse_warning = excluded.parse_warning,
                discovery_source = excluded.discovery_source,
                parent_session_id = excluded.parent_session_id,
                agent_label = excluded.agent_label
            ",
            params![
                session.id,
                session.provider.as_str(),
                session.provider_session_id,
                session.title,
                session.summary,
                session.cwd,
                session.repo_root,
                session.created_at.map(|value| value.to_rfc3339()),
                session.updated_at.map(|value| value.to_rfc3339()),
                session.last_message_at.map(|value| value.to_rfc3339()),
                session.preview_text,
                session.source_path,
                session.message_count,
                session.parse_version,
                session.raw_metadata_json,
                session.parse_warning,
                session.discovery_source,
                session.parent_session_id,
                session.agent_label,
            ],
        )?;
        tx.execute(
            "
            insert into transcripts (session_id, transcript_text)
            values (?1, ?2)
            on conflict(session_id) do update set transcript_text = excluded.transcript_text
            ",
            params![session.id, parsed.transcript_text],
        )?;
        tx.execute(
            "
            insert into files_seen (
                provider, source_path, mtime_ns, size_bytes, last_indexed_at,
                content_hash, parse_version
            )
            values (?1, ?2, ?3, ?4, ?5, null, ?6)
            on conflict(provider, source_path) do update set
                mtime_ns = excluded.mtime_ns,
                size_bytes = excluded.size_bytes,
                last_indexed_at = excluded.last_indexed_at,
                parse_version = excluded.parse_version
            ",
            params![
                session.provider.as_str(),
                session.source_path,
                mtime_ns,
                size_bytes,
                Utc::now().to_rfc3339(),
                session.parse_version,
            ],
        )?;
        // Re-sync per-message rows. Session logs are APPEND-ONLY, so when a re-parse only GREW
        // the message list and the existing rows are an unchanged prefix, insert just the new
        // tail instead of deleting and re-inserting the whole session. Re-inserting every message
        // also re-runs the messages_fts triggers over the entire session, so a
        // delete+insert re-indexed multi-hundred-MB sessions on EVERY incremental reindex — the
        // dominant reindex cost. The boundary check (the last existing message still matches the
        // parse at that seq) guards against in-place rewrites; on any mismatch or shrink we fall
        // back to a full replace. Messages carry seq = parse index, so the appended tail's seqs
        // never collide with the retained prefix.
        let existing_count: i64 = tx.query_row(
            "select count(*) from messages where session_id = ?1",
            params![session.id],
            |row| row.get(0),
        )?;
        let parsed_count = parsed.messages.len() as i64;
        let append_from: Option<usize> =
            if allow_append_optimization && existing_count > 0 && parsed_count > existing_count {
                let boundary = &parsed.messages[(existing_count - 1) as usize];
                let existing_boundary: Option<String> = tx
                    .query_row(
                        "select content from messages where session_id = ?1 and seq = ?2",
                        params![session.id, boundary.seq],
                        |row| row.get(0),
                    )
                    .optional()?;
                (existing_boundary.as_deref() == Some(boundary.content.as_str()))
                    .then_some(existing_count as usize)
            } else {
                None
            };
        let new_messages = match append_from {
            Some(start) => &parsed.messages[start..],
            None => {
                tx.execute(
                    "delete from messages where session_id = ?1",
                    params![session.id],
                )?;
                &parsed.messages[..]
            }
        };
        // Persist messages with their parse-order seq (0..N).
        insert_messages(&tx, session, new_messages.iter().map(|m| (m.seq, m)))?;
        // Re-sync file-edit rows (idempotent, same as messages). `edits` are stored as a
        // JSON array of [old, new] pairs; `new_content` holds full content for Write only.
        tx.execute(
            "delete from file_edits where session_id = ?1",
            params![session.id],
        )?;
        insert_file_edits(&tx, session, parsed.file_edits.iter().map(|e| (e.seq, e)))?;
        tx.commit()?;
        Ok(())
    }

    /// Delete `user`-role messages that are harness-injected output, not prompts — content
    /// leading with `<local-command-stdout>` / `-stderr` / `-caveat` (claude) or
    /// `<environment_context>` / `<turn_aborted>` (codex). The current parser already excludes
    /// these from re-parsed files, but sessions whose source file was deleted are never re-visited
    /// (durable archive), so their already-indexed injected rows persist; this one-time data purge
    /// reaches them. Returns the number of rows deleted. The `messages_fts` delete trigger keeps the
    /// word index in sync; the custom trigram base is rebuilt lazily on next use. Run during the
    /// schema migration (see indexer.rs).
    pub fn purge_injected_messages(&self) -> Result<usize> {
        let deleted = self.conn.execute(
            "delete from messages where role = 'user' and (\
                 content like '<local-command-stdout>%' \
              or content like '<local-command-stderr>%' \
              or content like '<local-command-caveat>%' \
              or content like '<environment_context>%' \
              or content like '<turn_aborted>%')",
            [],
        )?;
        Ok(deleted)
    }

    /// The stored incremental tail-parse checkpoint for a file, only when its parser version
    /// exactly matches `required_parse_version`.
    ///
    /// Returning `None` for an older parser generation forces a full replacement rather than
    /// appending newly classified rows to a stale prefix. Lookup is `O(log F)` through the
    /// `files_seen` primary key and retains only the two checkpoint fields.
    pub fn file_checkpoint(
        &self,
        provider: Provider,
        source_path: &str,
        required_parse_version: &str,
    ) -> Result<Option<(i64, String)>> {
        let row = self
            .conn
            .query_row(
                "select tail_byte_offset, prefix_fingerprint from files_seen
                 where provider = ?1 and source_path = ?2 and parse_version = ?3",
                params![provider.as_str(), source_path, required_parse_version],
                |row| {
                    Ok((
                        row.get::<_, Option<i64>>(0)?,
                        row.get::<_, Option<String>>(1)?,
                    ))
                },
            )
            .optional()?;
        Ok(match row {
            Some((Some(offset), Some(fingerprint))) => Some((offset, fingerprint)),
            _ => None,
        })
    }

    /// Record/refresh a file's tail-parse checkpoint after a FULL parse, so the next reindex of
    /// the grown file can incrementally append from here. Must run after the `files_seen` row
    /// exists (i.e. after [`Db::upsert_session`]). Updating it on every full parse is what keeps a
    /// stale offset from causing the next tail parse to re-append already-indexed rows.
    pub fn set_file_checkpoint(
        &self,
        provider: Provider,
        source_path: &str,
        tail_byte_offset: i64,
        prefix_fingerprint: &str,
    ) -> Result<()> {
        self.conn.execute(
            "update files_seen set tail_byte_offset = ?3, prefix_fingerprint = ?4
             where provider = ?1 and source_path = ?2",
            params![
                provider.as_str(),
                source_path,
                tail_byte_offset,
                prefix_fingerprint
            ],
        )?;
        Ok(())
    }

    /// Append ONLY the new rows from an incremental tail parse to an already-indexed session, in
    /// one transaction (SQLite makes the checkpoint update atomic with the data). New messages /
    /// file-edits are re-sequenced to continue after the rows already stored, so their seqs match
    /// what a full parse would assign. Immutable session fields (created_at, summary/first-user)
    /// are preserved; updated_at/last_message_at advance only forward; title/preview refresh from
    /// the tail's latest view; cwd fills in if it was NULL; message_count becomes the true count.
    /// The new conversation text is appended to the transcript blob and the session FTS is rebuilt
    /// from the now-current row. The messages_fts/trigram triggers index the new message rows
    /// automatically. See [`crate::tail`] and plan §7.
    pub fn append_tail(
        &self,
        tail: &crate::tail::TailParse,
        mtime_ns: i64,
        size_bytes: i64,
    ) -> Result<()> {
        let session = &tail.session;
        let tx = self.conn.unchecked_transaction()?;

        // New messages, re-sequenced after the existing rows (seqs are 0..N parse-order).
        let existing_count: i64 = tx.query_row(
            "select count(*) from messages where session_id = ?1",
            params![session.id],
            |row| row.get(0),
        )?;
        // Append messages re-sequenced after the existing rows (seqs are 0..N parse-order).
        insert_messages(
            &tx,
            session,
            tail.new_messages
                .iter()
                .enumerate()
                .map(|(i, m)| (existing_count + i as i64, m)),
        )?;

        // New file edits, re-sequenced after the existing ones.
        let existing_edit_seq: i64 = tx.query_row(
            "select coalesce(max(seq), -1) from file_edits where session_id = ?1",
            params![session.id],
            |row| row.get(0),
        )?;
        insert_file_edits(
            &tx,
            session,
            tail.new_file_edits
                .iter()
                .enumerate()
                .map(|(i, e)| (existing_edit_seq + 1 + i as i64, e)),
        )?;

        // Advance volatile session metadata; updated_at/last_message_at only move forward (RFC3339
        // sorts lexically), title/preview take the tail's newest view, cwd fills if it was NULL.
        let new_count = existing_count + tail.new_messages.len() as i64;
        tx.execute(
            "update sessions set
                updated_at = case when ?2 is not null and ?2 > coalesce(updated_at, '') then ?2
                                  else updated_at end,
                last_message_at = case when ?3 is not null and ?3 > coalesce(last_message_at, '') then ?3
                                       else last_message_at end,
                title = ?4,
                preview_text = ?5,
                cwd = coalesce(cwd, ?6),
                message_count = ?7
             where id = ?1",
            params![
                session.id,
                session.updated_at.map(|value| value.to_rfc3339()),
                session.last_message_at.map(|value| value.to_rfc3339()),
                session.title,
                session.preview_text,
                session.cwd,
                new_count,
            ],
        )?;

        // Append the new conversation text to the transcript blob, then rebuild this session's FTS
        // row from the now-current sessions + transcripts rows (no drift from the live values).
        if !tail.new_transcript.is_empty() {
            tx.execute(
                "update transcripts set transcript_text =
                    case when transcript_text = '' then ?2
                         else transcript_text || char(10) || char(10) || ?2 end
                 where session_id = ?1",
                params![session.id, tail.new_transcript],
            )?;
        }
        // Persist the checkpoint + refresh files_seen mtime/size in the same transaction.
        tx.execute(
            "update files_seen set
                mtime_ns = ?3, size_bytes = ?4, last_indexed_at = ?5,
                tail_byte_offset = ?6, prefix_fingerprint = ?7, parse_version = ?8
             where provider = ?1 and source_path = ?2",
            params![
                session.provider.as_str(),
                session.source_path,
                mtime_ns,
                size_bytes,
                Utc::now().to_rfc3339(),
                tail.new_tail_offset,
                tail.new_fingerprint,
                session.parse_version,
            ],
        )?;
        tx.commit()?;
        Ok(())
    }

    /// Total persisted message rows. Basis for migration detection (empty → reindex) and tests.
    pub fn message_count(&self) -> Result<i64> {
        Ok(self
            .conn
            .query_row("select count(*) from messages", [], |row| row.get(0))?)
    }

    /// Whether at least one session has been indexed, without counting the full table.
    pub fn has_sessions(&self) -> Result<bool> {
        Ok(self
            .conn
            .query_row("select exists(select 1 from sessions limit 1)", [], |row| {
                row.get(0)
            })?)
    }

    /// Indexed document rows in the message FTS index. For external-content FTS5,
    /// `count(*) from messages_fts` reflects the `messages` content table even when
    /// the token index is empty; `_docsize` holds one row per indexed document and is
    /// the value that can actually assert trigger/rebuild sync (== `message_count`).
    pub fn messages_fts_count(&self) -> Result<i64> {
        Ok(self
            .conn
            .query_row("select count(*) from messages_fts_docsize", [], |row| {
                row.get(0)
            })?)
    }

    /// Messages grouped by role, ordered by role, honoring the session/date filters.
    /// Basis for `stats` and tests. `MessageFilters::default()` counts everything.
    pub fn message_role_counts(&self, filters: &MessageFilters) -> Result<Vec<(String, i64)>> {
        use rusqlite::types::Value;

        self.validate_access_scope()?;

        let mut sql = String::from("select m.role, count(*) from messages m where 1 = 1");
        let mut args: Vec<Value> = Vec::new();
        append_message_filters(&mut sql, &mut args, filters, &self.access_scope);
        sql.push_str(" group by m.role order by m.role");

        let mut stmt = self.conn.prepare(&sql)?;
        let rows = stmt
            .query_map(rusqlite::params_from_iter(args.iter()), |row| {
                Ok((row.get::<_, String>(0)?, row.get::<_, i64>(1)?))
            })?
            .collect::<rusqlite::Result<Vec<_>>>()?;
        Ok(rows)
    }

    /// Term-frequency vocabulary over the message indexes. Returns
    /// `(term, doc_count, total_count)` ordered by total occurrences descending, then term.
    /// `trigram=false` reads the word-token `messages_vocab` view and reports true occurrence
    /// counts. `trigram=true` reads schema-v4's row-level `messages_trigram_terms` view. Because the
    /// compact trigram index uses `detail=none`, it records term/document membership rather than
    /// per-position occurrence counts; doc and total count therefore both mean document frequency.
    /// Schema versions older than v4 retain the custom-index compatibility source until migration.
    /// `limit == 0` returns all terms.
    ///
    /// `prefix` keeps only terms starting with it, as a term-range comparison SQLite answers from
    /// the index order rather than a scan; `None` and `Some("")` both mean every term. The limit
    /// applies to the terms the prefix kept, so a matching prefix never returns an empty page
    /// because commoner terms filled the limit first. Matching is case-insensitive because both
    /// sources case-fold as they tokenize and neither stores an uppercase term, so the prefix is
    /// folded here rather than left to report nothing for `Cargo`. The fold is the caseless rule
    /// every needle in search shares, which is the one FTS5 tokenizes with: it brings `Σ`, `σ`,
    /// and `ς` together the way the stored terms already are, where [`str::to_lowercase`] writes a
    /// word-final `Σ` as `ς` and asks for a term neither source stores.
    pub fn vocabulary(
        &self,
        trigram: bool,
        limit: usize,
        prefix: Option<&str>,
    ) -> Result<Vec<(String, i64, i64)>> {
        use rusqlite::types::Value;

        let lim: i64 = if limit == 0 { -1 } else { limit as i64 };
        let schema_version = self.schema_version()?;
        // Every source names its term, document-frequency, and total-occurrence columns
        // differently, so the query is one template over those three names.
        let (source, term, doc, total) = if trigram && schema_version >= 4 {
            // The row vocabulary makes SQLite aggregate postings once inside FTS5. Reading the
            // instance vocabulary here would emit one row per term/document and then re-aggregate
            // millions of postings for even a five-row result.
            ("messages_trigram_terms", "term", "doc", "doc")
        } else if trigram {
            self.ensure_trigram_base()?;
            ("trigram_postings", "tg", "df", "df")
        } else {
            ("messages_vocab", "term", "doc", "cnt")
        };

        let folded = prefix
            .map(fold_caseless)
            .filter(|prefix| !prefix.is_empty());
        let mut args: Vec<Value> = vec![Value::Integer(lim)];
        let mut filter = String::new();
        if let Some(prefix) = folded {
            filter = format!(" where {term} >= ?{}", args.len() + 1);
            if let Some(upper) = prefix_upper_bound(&prefix) {
                args.push(Value::Text(prefix));
                args.push(Value::Text(upper));
                filter.push_str(&format!(" and {term} < ?{}", args.len()));
            } else {
                args.push(Value::Text(prefix));
            }
        }

        let sql = format!(
            "select {term}, {doc}, {total} from {source}{filter} \
             order by {total} desc, {term} limit ?1"
        );
        let mut stmt = self.conn.prepare(&sql)?;
        let rows = stmt
            .query_map(rusqlite::params_from_iter(args.iter()), |row| {
                Ok((
                    row.get::<_, String>(0)?,
                    row.get::<_, i64>(1)?,
                    row.get::<_, i64>(2)?,
                ))
            })?
            .collect::<rusqlite::Result<Vec<_>>>()?;
        Ok(rows)
    }

    /// Message-level search. A literal `query` is an exact case-insensitive substring match:
    /// punctuation and infix text are significant (`/goal`, `C++`, `--path`, and `handled` inside
    /// `mishandled` all match literally). Schema v4 uses SQLite word/trigram indexes to admit
    /// candidates; exact literal or Rust regex verification remains authoritative. Fuzzy mode
    /// uses bounded-memory Nucleo sequence scoring across every structurally eligible row, then
    /// applies `offset` and `limit`. It is sequence matching rather than edit distance.
    /// Literal/regex `limit == 0` is unlimited. Fuzzy requires a query of at least three characters
    /// and a positive limit.
    pub fn search_messages(
        &self,
        query: &str,
        filters: &MessageFilters,
    ) -> Result<Vec<MessageHit>> {
        Ok(self.search_messages_with_explain(query, filters, false)?.0)
    }

    pub(crate) fn search_message_plan(
        &self,
        plan: &crate::message_search::MessageRetrievalPlan,
        include_explain: bool,
    ) -> Result<(Vec<MessageHit>, Option<SearchExplain>)> {
        let (query, filters, order) = Self::message_plan_execution(plan)?;
        self.search_messages_with_explain_order(query, &filters, include_explain, order)
    }

    pub(crate) fn visit_message_plan_batches(
        &self,
        plan: &crate::message_search::MessageRetrievalPlan,
        include_explain: bool,
        batch_rows: NonZeroUsize,
        visitor: impl FnMut(Vec<MessageHit>) -> Result<MessageBatchControl>,
    ) -> Result<MessageBatchVisitOutcome> {
        let (query, filters, order) = Self::message_plan_execution(plan)?;
        self.visit_messages_in_batches(query, &filters, include_explain, order, batch_rows, visitor)
    }

    fn message_plan_execution(
        plan: &crate::message_search::MessageRetrievalPlan,
    ) -> Result<(&str, MessageFilters, MessageOrder)> {
        use crate::message_search::{MatchWindow, MessageQuery, ResolvedExtent};

        let query = plan.query.text().unwrap_or("");
        let match_mode = match &plan.query {
            MessageQuery::All | MessageQuery::Literal(_) => MessageSearchMode::Literal,
            MessageQuery::Regex(_) => MessageSearchMode::Regex,
            MessageQuery::Fuzzy(_) => MessageSearchMode::Fuzzy,
        };
        let (limit, offset) = match plan.extent {
            ResolvedExtent::Page { limit, offset } => (
                limit
                    .get()
                    .checked_add(1)
                    .ok_or_else(|| anyhow!("message page limit plus look-ahead overflows"))?,
                offset,
            ),
            ResolvedExtent::AllResults { offset } => (0, offset),
        };
        let filters = MessageFilters {
            role: plan.predicates.role,
            kinds: plan.predicates.kinds.clone(),
            field: Some(plan.target.field()),
            argument_path: plan
                .target
                .argument_path()
                .map(|pointer| pointer.as_str().to_string()),
            providers: plan.predicates.providers.clone(),
            session_id: plan.predicates.session_id.clone(),
            workspace_path_prefix: plan.predicates.workspace_path_prefix.clone(),
            transcript_path_prefix: plan.predicates.transcript_path_prefix.clone(),
            exclude_workspace_path_prefixes: plan
                .predicates
                .exclude_workspace_path_prefixes
                .clone(),
            exclude_transcript_path_prefixes: plan
                .predicates
                .exclude_transcript_path_prefixes
                .clone(),
            exclude_session_ids: plan.predicates.exclude_session_ids.clone(),
            since: plan.predicates.time.since(),
            until: plan.predicates.time.until(),
            seq_from: plan.predicates.sequence.and_then(|range| range.from()),
            seq_to: plan.predicates.sequence.and_then(|range| range.to()),
            match_mode,
            tool: plan.predicates.tool_name_contains.clone(),
            no_compaction: !plan.predicates.include_compaction,
            limit,
            offset,
            ..Default::default()
        };
        let order = if plan.match_window == Some(MatchWindow::Latest) {
            MessageOrder::NewestFirst
        } else {
            MessageOrder::OldestFirst
        };
        Ok((query, filters, order))
    }

    pub(crate) fn search_messages_ordered(
        &self,
        query: &str,
        filters: &MessageFilters,
        order: MessageOrder,
    ) -> Result<Vec<MessageHit>> {
        anyhow::ensure!(
            order == MessageOrder::OldestFirst || filters.session_id.is_some(),
            "newest-first message order requires session_id because sequence numbers are session-local"
        );
        Ok(self
            .search_messages_with_explain_order(query, filters, false, order)?
            .0)
    }

    /// Read one session's messages, selecting the first (oldest) or last (newest)
    /// `filters.limit` by `order`, and ALWAYS returning them in chronological (seq-ascending)
    /// order so the caller reads oldest→newest regardless of the selection direction.
    ///
    /// `order` decides WHICH messages are kept, not just their display order (so
    /// `NewestFirst` + `limit = 75` is the last 75, not the first 75 shown backwards — this
    /// avoids the `git log --reverse` trap where reverse applies after the limit). It is the
    /// clean equivalent of a hand-written `ORDER BY seq DESC LIMIT N`.
    ///
    /// Scope, role, dates, `limit` (unsigned; 0 = all), `offset`, and `seq_from`/`seq_to` come
    /// from `filters`. `filters.session_id` is required because sequence numbers are
    /// session-local, so a newest-first window is otherwise undefined. `seq_from`/`seq_to`
    /// bound the set before the window applies, giving non-overlapping chunked reads; `offset`
    /// skips from the leading edge of the chosen direction.
    pub fn read_session_messages(
        &self,
        filters: &MessageFilters,
        order: MessageOrder,
    ) -> Result<Vec<MessageHit>> {
        anyhow::ensure!(
            filters.session_id.is_some(),
            "read_session_messages requires filters.session_id because sequence numbers are session-local"
        );
        let mut hits = self.search_messages_ordered("", filters, order)?;
        if order == MessageOrder::NewestFirst {
            // A newest-first fetch returns seq-descending rows; restore chronological order.
            hits.reverse();
        }
        Ok(hits)
    }

    /// Like [`Db::search_messages`], optionally returning the exact planner diagnostics used by
    /// this search. This keeps the MCP `receipt_level`, CLI `--receipt-level`, and the search path
    /// on one shared FTS/trigram decision instead of running the planner twice. In every receipt
    /// `corpus` is the structural denominator, the rows the filters admit for the searched field,
    /// read from indexes; `candidates` is the prefilter output still to be verified (content and
    /// tool-argument trigram candidates) or the rows fuzzy scoring matched (content, tool name,
    /// tool argument), and absent when the field was verified in SQLite with no prefilter (tool
    /// name, literal or regex).
    pub fn search_messages_with_explain(
        &self,
        query: &str,
        filters: &MessageFilters,
        include_explain: bool,
    ) -> Result<(Vec<MessageHit>, Option<SearchExplain>)> {
        self.search_messages_with_explain_order(
            query,
            filters,
            include_explain,
            MessageOrder::OldestFirst,
        )
    }

    /// Build the one authoritative non-fuzzy SQL statement used by materialized and batched
    /// traversal. Keeping filtering, acceleration, ordering, offset, and diagnostics here avoids
    /// semantic drift between output surfaces.
    fn prepare_non_fuzzy_message_query(
        &self,
        query: &str,
        filters: &MessageFilters,
        include_explain: bool,
        order: MessageOrder,
    ) -> Result<PreparedMessageQuery> {
        use rusqlite::types::Value;

        debug_assert_ne!(filters.match_mode, MessageSearchMode::Fuzzy);
        let field = filters.field.unwrap_or(SearchField::Content);
        let mut sql = String::from(
            "select m.session_id, m.provider, m.seq, m.role, m.ts, m.tool_name, m.kind, m.tool_call_id, m.content \
             from messages m where 1 = 1",
        );
        let mut args = Vec::new();
        append_message_filters(&mut sql, &mut args, filters, &self.access_scope);

        let explain = if field == SearchField::Content {
            let literal_query =
                filters.match_mode == MessageSearchMode::Literal && !query.is_empty();
            if literal_query {
                sql.push_str(" and unicode_lower_contains(m.content, ?)");
                args.push(Value::Text(fold_caseless(query)));
            }
            if filters.match_mode == MessageSearchMode::Regex {
                regex::Regex::new(query).map_err(|error| anyhow!("invalid regex: {error}"))?;
                sql.push_str(" and rust_regexp(?, m.content)");
                args.push(Value::Text(query.to_string()));
            }
            let prefilter_pattern = if filters.match_mode == MessageSearchMode::Regex {
                Some(query.to_string())
            } else if literal_query {
                Some(regex::escape(query))
            } else {
                None
            };
            if self.schema_version()? >= 4 {
                let prefilter = prefilter_pattern
                    .as_deref()
                    .and_then(crate::trigram::trigram_prefilter);
                if let Some(fts_query) = &prefilter {
                    sql.push_str(
                        " and m.id in (
                             select rowid from messages_trigram
                              where messages_trigram match ?
                         )",
                    );
                    args.push(Value::Text(fts_query.clone()));
                }
                if include_explain {
                    Some(SearchExplain {
                        prefilter: prefilter.clone(),
                        candidates: prefilter
                            .as_deref()
                            .map(|fts_query| self.fts5_candidate_count(filters, fts_query))
                            .transpose()?,
                        prefilter_skipped: prefilter
                            .is_none()
                            .then(|| "no required literal of at least three characters".into()),
                        corpus: self.filtered_corpus_count(filters)?,
                    })
                } else {
                    None
                }
            } else {
                let (use_trigram_candidates, explain) = self.prepare_content_prefilter(
                    prefilter_pattern.as_deref(),
                    filters,
                    include_explain,
                )?;
                if use_trigram_candidates {
                    sql.push_str(" and m.id in (select id from _trigram_cand)");
                }
                explain
            }
        } else {
            let mut derived_explain = None;
            match (field, filters.match_mode) {
                (SearchField::ToolName, MessageSearchMode::Literal) => {
                    sql.push_str(" and unicode_lower_contains(m.tool_name, ?)");
                    args.push(Value::Text(fold_caseless(query)));
                }
                (SearchField::ToolName, MessageSearchMode::Regex) => {
                    regex::Regex::new(query).map_err(|error| anyhow!("invalid regex: {error}"))?;
                    sql.push_str(" and rust_regexp(?, m.tool_name)");
                    args.push(Value::Text(query.to_string()));
                }
                (SearchField::ToolArgument, mode) => {
                    // Let F be structurally eligible tool-call rows, C the raw-JSON trigram
                    // candidates (C <= F), B_C their total JSON bytes, Q the query length, P_Q the
                    // postings entries read for its required grams, and H the returned page. The
                    // previous path parsed/projected every row: O(F + B_F + H) application work.
                    // This path does O(Q + P_Q + C + B_C + H), including authoritative projection
                    // and matching. Worst case remains O(F + B_F + H) when every row is candidate;
                    // selective anchors reduce JSON parsing from B_F to B_C. Peak owned Rust
                    // result memory remains O(H + bytes(H)); SQLite's execution/postings state is
                    // implementation-owned and conservatively bounded by O(P_Q + C). No second
                    // candidate Vec is materialized here. Query latency is
                    // the same serial critical path as the work above—this branch does not claim
                    // a /worker_threads speedup. The existing incrementally maintained raw-content
                    // index adds no new storage or write-maintenance asymptotic cost.
                    if mode == MessageSearchMode::Regex {
                        regex::Regex::new(query)
                            .map_err(|error| anyhow!("invalid regex: {error}"))?;
                    }
                    let prefilter_pattern = match mode {
                        MessageSearchMode::Literal if !query.is_empty() => {
                            Some(regex::escape(query))
                        }
                        MessageSearchMode::Regex => Some(query.to_string()),
                        MessageSearchMode::Literal => None,
                        MessageSearchMode::Fuzzy => unreachable!("fuzzy query rejected above"),
                    };
                    let prefilter = (self.schema_version()? >= 4)
                        .then(|| {
                            prefilter_pattern
                                .as_deref()
                                .and_then(json_projection_prefilter_groups)
                                .map(|groups| crate::trigram::render_prefilter_groups(&groups))
                        })
                        .flatten();
                    if let Some(fts_query) = &prefilter {
                        sql.push_str(
                            " and m.id in (
                                 select rowid from messages_trigram
                                  where messages_trigram match ?
                             )",
                        );
                        args.push(Value::Text(fts_query.clone()));
                    }
                    sql.push_str(" and m.kind = 'tool_call'");
                    match mode {
                        MessageSearchMode::Literal => {
                            sql.push_str(
                                " and unicode_lower_contains(rust_json_pointer(?, m.content), ?)",
                            );
                            args.push(Value::Text(
                                filters.argument_path.clone().unwrap_or_default(),
                            ));
                            args.push(Value::Text(fold_caseless(query)));
                        }
                        MessageSearchMode::Regex => {
                            sql.push_str(" and rust_regexp(?, rust_json_pointer(?, m.content))");
                            args.push(Value::Text(query.to_string()));
                            args.push(Value::Text(
                                filters.argument_path.clone().unwrap_or_default(),
                            ));
                        }
                        MessageSearchMode::Fuzzy => unreachable!("fuzzy query rejected above"),
                    }
                    if include_explain {
                        // The receipt keeps its published meaning: `corpus` is the structural
                        // denominator (tool-call rows the filters admit, counted from the
                        // partial tool-call index) and `candidates` the raw-JSON prefilter
                        // output the projected predicate still verifies, a superset of the hits.
                        // Ordinary retrieval pays neither count.
                        let corpus =
                            self.corpus_count_with_base("m.kind = 'tool_call'", filters)?;
                        let candidates = prefilter
                            .as_deref()
                            .map(|fts_query| {
                                self.fts5_candidate_count_with_base(
                                    "m.kind = 'tool_call'",
                                    filters,
                                    fts_query,
                                )
                            })
                            .transpose()?;
                        derived_explain = Some(SearchExplain {
                            prefilter: prefilter.clone(),
                            candidates,
                            prefilter_skipped: prefilter.is_none().then(|| {
                                "no JSON-stable required literal of at least three characters"
                                    .to_string()
                            }),
                            corpus,
                        });
                    }
                }
                (_, MessageSearchMode::Fuzzy) => unreachable!("fuzzy query rejected above"),
                (SearchField::Content, _) => unreachable!("content handled above"),
            }
            if include_explain {
                match derived_explain {
                    Some(explain) => Some(explain),
                    // A literal or regex tool-name search verifies the name in SQLite with no
                    // prefilter; the denominator is every named-tool row the filters admit,
                    // read from the partial tool-name index.
                    None => Some(SearchExplain {
                        prefilter: None,
                        candidates: None,
                        prefilter_skipped: Some(
                            "tool name verified in SQLite without a prefilter".to_string(),
                        ),
                        corpus: self.corpus_count_with_base("m.tool_name is not null", filters)?,
                    }),
                }
            } else {
                None
            }
        };

        sql.push_str(if order == MessageOrder::NewestFirst {
            " order by m.session_id, m.seq desc"
        } else {
            " order by m.session_id, m.seq"
        });
        if filters.limit > 0 {
            sql.push_str(" limit ?");
            args.push(Value::Integer(filters.limit as i64));
            if filters.offset > 0 {
                sql.push_str(" offset ?");
                args.push(Value::Integer(filters.offset as i64));
            }
        } else if filters.offset > 0 {
            sql.push_str(" limit -1 offset ?");
            args.push(Value::Integer(filters.offset as i64));
        }
        Ok(PreparedMessageQuery { sql, args, explain })
    }

    fn search_messages_with_explain_order(
        &self,
        query: &str,
        filters: &MessageFilters,
        include_explain: bool,
        order: MessageOrder,
    ) -> Result<(Vec<MessageHit>, Option<SearchExplain>)> {
        self.validate_access_scope()?;
        filters.validate(query)?;
        let field = filters.field.unwrap_or(SearchField::Content);
        if filters.match_mode != MessageSearchMode::Fuzzy {
            let prepared =
                self.prepare_non_fuzzy_message_query(query, filters, include_explain, order)?;
            let hits = self.query_message_hits(&prepared.sql, &prepared.args)?;
            let explain = prepared.explain.clone();
            return Ok((hits, explain));
        }
        // Every statement of one fuzzy search reads one snapshot, whichever surface asked for it.
        //
        // A fuzzy search runs several: the ranking window's corpus count, the tool-name
        // vocabulary, the row scan, and the receipt's own counts. Each on its own would see
        // whatever the indexer had committed by the time it ran, so a refresh landing mid-search
        // could have the receipt describe a corpus the returned rows never came from, or leave a
        // row counted but never scored. `MessageService` already opens a snapshot around its own
        // path and `with_read_snapshot` then runs inline, so this is the guarantee for callers
        // holding `Db` directly — the Rust library API, and the tools and tests that use it.
        //
        // Only the fuzzy branch is wrapped. The non-fuzzy prefilter can build the legacy custom
        // trigram base ([`Db::ensure_trigram_base`]), which takes a write transaction and cannot
        // nest inside a read snapshot; fuzzy scoring performs no index maintenance.
        self.with_read_snapshot(|| {
            self.fuzzy_search_in_snapshot(query, filters, field, include_explain, order)
        })
    }

    fn fuzzy_search_in_snapshot(
        &self,
        query: &str,
        filters: &MessageFilters,
        field: SearchField,
        include_explain: bool,
        order: MessageOrder,
    ) -> Result<(Vec<MessageHit>, Option<SearchExplain>)> {
        use rusqlite::types::Value;

        debug_assert!(
            !self.conn.is_autocommit(),
            "every statement of one fuzzy search must share one read snapshot"
        );
        if field != SearchField::Content {
            return self.search_derived_message_field(
                query,
                filters,
                field,
                include_explain,
                order,
            );
        }

        let mut sql = String::from(
            "select m.session_id, m.provider, m.seq, m.role, m.ts, m.tool_name, m.kind, m.tool_call_id, m.content \
             from messages m where 1 = 1",
        );
        let mut args: Vec<Value> = Vec::new();
        append_message_filters(&mut sql, &mut args, filters, &self.access_scope);
        sql.push_str(if order == MessageOrder::NewestFirst {
            " order by m.session_id, m.seq desc"
        } else {
            " order by m.session_id, m.seq"
        });
        let ranked_limit = match self.fuzzy_ranking_window("1 = 1", filters)? {
            FuzzyRankingWindow::Rank { limit, .. } => limit,
            FuzzyRankingWindow::PastCorpus { corpus } => {
                return Ok((
                    Vec::new(),
                    include_explain.then(|| empty_past_corpus(corpus)),
                ))
            }
        };
        let pattern = Pattern::new(
            query,
            CaseMatching::Ignore,
            Normalization::Smart,
            AtomKind::Fuzzy,
        );
        let query_lower = fold_caseless(query);
        let mut stmt = self.conn.prepare(&sql)?;
        let rows = stmt.query_map(rusqlite::params_from_iter(args.iter()), row_to_message_hit)?;
        let mut batch = Vec::with_capacity(FUZZY_SCORE_BATCH_SIZE);
        let mut batch_bytes = 0_usize;
        let mut top = Vec::new();
        let mut corpus = 0_i64;
        let mut matched = 0_i64;
        for row in rows {
            let hit = row?;
            corpus += 1;
            batch_bytes = batch_bytes.saturating_add(hit.content.len());
            batch.push(hit);
            if fuzzy_batch_is_full(batch.len(), batch_bytes) {
                batch_bytes = 0;
                let scored = self.runtime.install(|| {
                    score_fuzzy_message_hits(&pattern, &query_lower, std::mem::take(&mut batch))
                })?;
                matched += scored.len() as i64;
                top.extend(scored);
                if top.len() >= top_k_compaction_threshold(ranked_limit) {
                    retain_top_fuzzy_hits(&mut top, ranked_limit);
                }
            }
        }
        if !batch.is_empty() {
            let scored = self
                .runtime
                .install(|| score_fuzzy_message_hits(&pattern, &query_lower, batch))?;
            matched += scored.len() as i64;
            top.extend(scored);
        }
        let hits = finish_fuzzy_hits(top, ranked_limit, filters.offset);
        let explain = include_explain.then(|| scored_whole_corpus(matched, corpus));
        Ok((hits, explain))
    }

    /// Visit one non-fuzzy query in bounded owned batches under a single SQLite snapshot.
    ///
    /// The query statement is prepared once and stepped once, so traversal is `O(C + H)` for
    /// candidate work `C` and returned rows `H`; it does not repeat numeric OFFSET scans. At most
    /// `batch_rows` message rows and their selected-field bytes are retained by this layer.
    /// Returning [`MessageBatchControl::Stop`] or an error drops the active row iterator and read
    /// transaction immediately without draining unread results.
    pub(crate) fn visit_messages_in_batches(
        &self,
        query: &str,
        filters: &MessageFilters,
        include_explain: bool,
        order: MessageOrder,
        batch_rows: NonZeroUsize,
        mut visitor: impl FnMut(Vec<MessageHit>) -> Result<MessageBatchControl>,
    ) -> Result<MessageBatchVisitOutcome> {
        self.validate_access_scope()?;
        filters.validate(query)?;
        anyhow::ensure!(
            filters.match_mode != MessageSearchMode::Fuzzy,
            "batched exhaustive traversal supports literal, regex, and queryless searches; pass a finite limit to the bounded fuzzy search"
        );
        anyhow::ensure!(
            order == MessageOrder::OldestFirst || filters.session_id.is_some(),
            "newest-first message order requires session_id because sequence numbers are session-local"
        );

        // Pre-v4 compatibility may lazily rebuild and stage its custom trigram candidates using
        // an internal write transaction. Finish that maintenance before opening the read snapshot;
        // schema v4 uses incrementally maintained FTS5 and prepares entirely inside the snapshot.
        // A legacy explanation is rejected because its corpus/candidate counts would otherwise be
        // computed before the snapshot and could describe different rows under concurrent ingest.
        let legacy_prepared = if self.schema_version()? < 4 {
            anyhow::ensure!(
                !include_explain,
                "batched message-search receipts require database schema 4 so planner counts and results share one snapshot; run `aise reindex --full` before requesting a receipt"
            );
            Some(self.prepare_non_fuzzy_message_query(query, filters, false, order)?)
        } else {
            None
        };

        // A caller-owned snapshot lets request planning and row traversal observe the same index
        // state. Otherwise this method owns an explicit read transaction. The rollback guard
        // releases it on early stop, visitor error, or panic without draining unread rows.
        let owned_snapshot = self
            .conn
            .is_autocommit()
            .then(|| ReadSnapshotRollback::begin(&self.conn))
            .transpose()?;
        let initial_prepared = match legacy_prepared {
            Some(prepared) => prepared,
            None => self.prepare_non_fuzzy_message_query(query, filters, include_explain, order)?,
        };
        let prepared = if order == MessageOrder::NewestFirst {
            // `NewestFirst` selects from the newest edge but public results remain chronological.
            // Find the first included match after the caller's newest-edge offset, then run the
            // authoritative predicate oldest-first through that sequence boundary. Reversing each
            // emitted batch would produce globally incorrect order, while retaining every row
            // merely to reverse once would make memory grow with the result count.
            let boundary = {
                let mut statement = self.conn.prepare(&initial_prepared.sql)?;
                let mut rows = statement.query_map(
                    rusqlite::params_from_iter(initial_prepared.args.iter()),
                    row_to_message_hit,
                )?;
                let boundary = rows.next().transpose()?;
                drop(rows);
                drop(statement);
                boundary
            };
            let Some(boundary) = boundary else {
                let explain = initial_prepared.explain.clone();
                if let Some(snapshot) = owned_snapshot {
                    snapshot.rollback()?;
                }
                return Ok(MessageBatchVisitOutcome {
                    rows_visited: 0,
                    exhausted: true,
                    explain,
                });
            };
            let mut chronological_filters = filters.clone();
            chronological_filters.limit = 0;
            chronological_filters.offset = 0;
            chronological_filters.seq_to = Some(
                chronological_filters
                    .seq_to
                    .map_or(boundary.seq, |current| current.min(boundary.seq)),
            );
            let mut chronological = self.prepare_non_fuzzy_message_query(
                query,
                &chronological_filters,
                false,
                MessageOrder::OldestFirst,
            )?;
            chronological.explain = initial_prepared.explain;
            chronological
        } else {
            initial_prepared
        };
        let mut statement = self.conn.prepare(&prepared.sql)?;
        let mut rows = statement.query_map(
            rusqlite::params_from_iter(prepared.args.iter()),
            row_to_message_hit,
        )?;
        let mut batch = Vec::new();
        batch.try_reserve_exact(batch_rows.get()).map_err(|error| {
            anyhow!(
                "batch_rows {} cannot be allocated: {error}; pass a smaller positive row count",
                batch_rows
            )
        })?;
        let mut rows_visited = 0_usize;
        let mut exhausted = false;

        loop {
            match rows.next() {
                Some(row) => {
                    batch.push(row?);
                    rows_visited = rows_visited
                        .checked_add(1)
                        .ok_or_else(|| anyhow!("batched message row count overflow"))?;
                    if batch.len() == batch_rows.get()
                        && visitor(std::mem::take(&mut batch))? == MessageBatchControl::Stop
                    {
                        break;
                    }
                    if batch.capacity() < batch_rows.get() {
                        batch
                            .try_reserve_exact(batch_rows.get() - batch.capacity())
                            .map_err(|error| {
                                anyhow!(
                                    "batch_rows {} cannot be allocated: {error}; pass a smaller positive row count",
                                    batch_rows
                                )
                            })?;
                    }
                }
                None => {
                    exhausted = true;
                    if !batch.is_empty() {
                        let _ = visitor(batch)?;
                    }
                    break;
                }
            }
        }

        drop(rows);
        drop(statement);
        if let Some(snapshot) = owned_snapshot {
            snapshot.rollback()?;
        }
        Ok(MessageBatchVisitOutcome {
            rows_visited,
            exhausted,
            explain: exhausted.then(|| prepared.explain.clone()).flatten(),
        })
    }

    fn fts5_candidate_count(&self, filters: &MessageFilters, fts_query: &str) -> Result<i64> {
        self.fts5_candidate_count_with_base("1 = 1", filters, fts_query)
    }

    /// [`Db::fts5_candidate_count`] over the rows that also satisfy `base_predicate`, an SQL
    /// fragment over alias `m` (`"m.kind = 'tool_call'"` for tool-argument search).
    fn fts5_candidate_count_with_base(
        &self,
        base_predicate: &str,
        filters: &MessageFilters,
        fts_query: &str,
    ) -> Result<i64> {
        use rusqlite::types::Value;
        let mut sql = format!("select count(*) from messages m where {base_predicate}");
        let mut args = Vec::new();
        append_message_filters(&mut sql, &mut args, filters, &self.access_scope);
        sql.push_str(
            " and m.id in (
                 select rowid from messages_trigram where messages_trigram match ?
             )",
        );
        args.push(Value::Text(fts_query.to_string()));
        Ok(self
            .conn
            .query_row(&sql, rusqlite::params_from_iter(args.iter()), |row| {
                row.get(0)
            })?)
    }

    fn search_derived_message_field(
        &self,
        query: &str,
        filters: &MessageFilters,
        field: SearchField,
        include_explain: bool,
        order: MessageOrder,
    ) -> Result<(Vec<MessageHit>, Option<SearchExplain>)> {
        if field == SearchField::ToolName
            && filters.match_mode == MessageSearchMode::Fuzzy
            && self.schema_version()? >= 4
        {
            // Vocabulary, per-tier rows, and the explain counts are separate statements; the
            // snapshot `search_messages_with_explain_order` opens keeps them on the same data.
            return self.search_tool_name_fuzzy_indexed(query, filters, include_explain);
        }
        let mut sql = String::from(
            "select m.session_id, m.provider, m.seq, m.role, m.ts, m.tool_name, m.kind, m.tool_call_id, m.content \
             from messages m where 1 = 1",
        );
        let mut args = Vec::new();
        append_message_filters(&mut sql, &mut args, filters, &self.access_scope);
        // The dispatcher sends only fuzzy derived-field searches here. Literal and regex have one
        // owner in prepare_non_fuzzy_message_query(), including tool-argument trigram planning.
        debug_assert_eq!(filters.match_mode, MessageSearchMode::Fuzzy);
        // One predicate owns both the scan and the bound measured against it. Writing the
        // restriction here and passing a different one to `fuzzy_ranking_window` sized the
        // retention window and the receipt's `corpus` by rows this statement never visits.
        let base_predicate = fuzzy_derived_scan_predicate(field);
        sql.push_str(" and ");
        sql.push_str(base_predicate);
        sql.push_str(if order == MessageOrder::NewestFirst {
            " order by m.session_id, m.seq desc"
        } else {
            " order by m.session_id, m.seq"
        });
        let pattern = Pattern::new(
            query,
            CaseMatching::Ignore,
            Normalization::Smart,
            AtomKind::Fuzzy,
        );
        let query_lower = fold_caseless(query);
        let ranked_limit = match self.fuzzy_ranking_window(base_predicate, filters)? {
            FuzzyRankingWindow::Rank { limit, .. } => limit,
            FuzzyRankingWindow::PastCorpus { corpus } => {
                return Ok((
                    Vec::new(),
                    include_explain.then(|| empty_past_corpus(corpus)),
                ))
            }
        };
        let mut top = Vec::new();
        let mut corpus = 0_i64;
        let mut matched = 0_i64;
        let mut stmt = self.conn.prepare(&sql)?;
        let rows = stmt.query_map(rusqlite::params_from_iter(args.iter()), row_to_message_hit)?;
        let mut batch = Vec::with_capacity(FUZZY_SCORE_BATCH_SIZE);
        let mut batch_bytes = 0_usize;
        for row in rows {
            let hit = row?;
            corpus += 1;
            batch_bytes = batch_bytes.saturating_add(hit.content.len());
            batch.push(hit);
            if fuzzy_batch_is_full(batch.len(), batch_bytes) {
                let scored = self.runtime.install(|| {
                    score_fuzzy_derived_hits(
                        &pattern,
                        &query_lower,
                        field,
                        filters.argument_path.as_deref(),
                        std::mem::take(&mut batch),
                    )
                })?;
                batch_bytes = 0;
                matched += scored.len() as i64;
                top.extend(scored);
                if top.len() >= top_k_compaction_threshold(ranked_limit) {
                    retain_top_fuzzy_hits(&mut top, ranked_limit);
                }
            }
        }
        if !batch.is_empty() {
            let scored = self.runtime.install(|| {
                score_fuzzy_derived_hits(
                    &pattern,
                    &query_lower,
                    field,
                    filters.argument_path.as_deref(),
                    batch,
                )
            })?;
            matched += scored.len() as i64;
            top.extend(scored);
        }
        let hits = finish_fuzzy_hits(top, ranked_limit, filters.offset);
        let explain = include_explain.then(|| scored_whole_corpus(matched, corpus));
        Ok((hits, explain))
    }

    /// Enumerate the global tool-name superset with one B-tree successor seek per distinct name.
    /// Every structurally eligible name is necessarily present globally; scoring extras is safe and
    /// row loading still applies all filters. For N named rows and V distinct names this performs
    /// O(V log N) indexed seeks and retains O(V) short strings, instead of scanning O(N) index
    /// entries through SELECT DISTINCT. SQLite rejects this recursive CTE on the public SQL surface,
    /// but it is a fixed internal statement over the trusted schema.
    fn global_tool_name_vocabulary(&self) -> Result<Vec<String>> {
        let mut stmt = self.conn.prepare(
            "with recursive names(name) as (
                 select min(tool_name) from messages where tool_name is not null
                 union all
                 select (select min(tool_name) from messages where tool_name > names.name)
                   from names where name is not null
             )
             select name from names where name is not null",
        )?;
        let rows = stmt.query_map([], |row| row.get::<_, String>(0))?;
        rows.collect::<rusqlite::Result<Vec<_>>>()
            .map_err(Into::into)
    }

    #[cfg(test)]
    fn search_tool_name_fuzzy_direct_for_test(
        &self,
        query: &str,
        filters: &MessageFilters,
    ) -> Result<Vec<MessageHit>> {
        let mut sql = String::from(
            "select m.session_id, m.provider, m.seq, m.role, m.ts, m.tool_name,
                    m.kind, m.tool_call_id, m.content
               from messages m
              where m.tool_name is not null",
        );
        let mut args = Vec::new();
        append_message_filters(&mut sql, &mut args, filters, &self.access_scope);
        sql.push_str(" order by m.session_id, m.seq");
        let rows = self.query_message_hits(&sql, &args)?;
        let pattern = Pattern::new(
            query,
            CaseMatching::Ignore,
            Normalization::Smart,
            AtomKind::Fuzzy,
        );
        let scored = score_fuzzy_derived_hits(
            &pattern,
            &fold_caseless(query),
            SearchField::ToolName,
            None,
            rows,
        );
        Ok(finish_fuzzy_hits(
            scored,
            fuzzy_ranked_limit(filters)?,
            filters.offset,
        ))
    }

    fn search_tool_name_fuzzy_indexed(
        &self,
        query: &str,
        filters: &MessageFilters,
        include_explain: bool,
    ) -> Result<(Vec<MessageHit>, Option<SearchExplain>)> {
        use rusqlite::types::Value;

        // Tool-name score depends only on the name, not the row. Let N be globally named rows, V
        // global distinct names, and W=offset+limit. The old path read O(N + B_N) bytes and scored
        // O(V) names. This path discovers/scored the complete global vocabulary with O(V log N)
        // index seeks, then applies structural filters while materializing at most W ranked rows
        // and O(B_W) content bytes. Explain adds one matching-row count. The vocabulary/score map
        // retains O(V) short strings; result state is O(W + bytes(W)). SQLite traversal is serial
        // and no schema/write cost is added. A JSON virtual table carries bounded score tiers.
        // Inside SQLite each processed tier is still visited in full: `idx_messages_tool_name`
        // seeks the tier's names, every matching row's sort key is read, and `order by session_id,
        // seq limit ?` keeps W of them (O(R_tier log W)); the W bound above is what crosses into
        // Rust, not what the engine touches.
        debug_assert!(
            !self.conn.is_autocommit(),
            "the fuzzy tool-name statements must share one read snapshot"
        );
        let (ranked_limit, counted_corpus) =
            match self.fuzzy_ranking_window("m.tool_name is not null", filters)? {
                FuzzyRankingWindow::Rank { limit, corpus } => (limit, corpus),
                FuzzyRankingWindow::PastCorpus { corpus } => {
                    return Ok((
                        Vec::new(),
                        include_explain.then(|| empty_past_corpus(corpus)),
                    ))
                }
            };
        let names = self.global_tool_name_vocabulary()?;

        let pattern = Pattern::new(
            query,
            CaseMatching::Ignore,
            Normalization::Smart,
            AtomKind::Fuzzy,
        );
        let query_lower = fold_caseless(query);
        let query_needle = UnicodeLowerNeedle::from_lowered(&query_lower);
        let mut matcher = NucleoMatcher::new(NucleoConfig::DEFAULT);
        let mut utf32_buf = Vec::new();
        let mut matching_names = HashMap::new();
        for name in names {
            utf32_buf.clear();
            if let Some(score) = pattern.score(Utf32Str::new(&name, &mut utf32_buf), &mut matcher) {
                let exact_phrase = query_needle.contains(&name);
                matching_names.insert(name, (score, exact_phrase));
            }
        }

        let explained_matching_rows = if include_explain && !matching_names.is_empty() {
            let selected_names = serde_json::to_string(&matching_names.keys().collect::<Vec<_>>())?;
            let mut sql = String::from(
                "select count(*) from json_each(?) selected
                   join messages m on m.tool_name = selected.value
                  where m.tool_name is not null",
            );
            let mut args = vec![Value::Text(selected_names)];
            append_message_filters(&mut sql, &mut args, filters, &self.access_scope);
            Some(
                self.conn
                    .query_row(&sql, rusqlite::params_from_iter(args.iter()), |row| {
                        row.get::<_, i64>(0)
                    })?,
            )
        } else {
            None
        };

        // Names in one score/exactness tier can interleave only by session/seq, while every lower
        // tier ranks after every row in this tier. Read at most the still-missing W rows from each
        // tier and stop once W is full; this is equivalent to global row scoring without loading
        // content that cannot reach the requested window.
        let mut scored_names = matching_names.into_iter().collect::<Vec<_>>();
        scored_names.sort_by(|(left_name, left), (right_name, right)| {
            right
                .0
                .cmp(&left.0)
                .then_with(|| right.1.cmp(&left.1))
                .then_with(|| left_name.cmp(right_name))
        });
        // Sized by rows found, never by the request: reserving `ranked_limit` up front asked for
        // ~150 GB at offset 1e9 and overflowed at 1e17. `ranked_limit` is itself bounded by the
        // eligible corpus (see `Db::fuzzy_ranking_window`), so growth stops at the rows that exist.
        let mut top = Vec::new();
        let mut matched = 0_i64;
        for tier in scored_names.chunk_by(|left, right| left.1 == right.1) {
            if top.len() == ranked_limit {
                break;
            }
            let selected_names =
                serde_json::to_string(&tier.iter().map(|(name, _)| name).collect::<Vec<_>>())?;
            let remaining = ranked_limit - top.len();
            let mut sql = String::from(
                "select m.session_id, m.provider, m.seq, m.role, m.ts, m.tool_name,
                        m.kind, m.tool_call_id, m.content
                   from json_each(?) selected
                   join messages m on m.tool_name = selected.value
                  where m.tool_name is not null",
            );
            let mut args = vec![Value::Text(selected_names)];
            append_message_filters(&mut sql, &mut args, filters, &self.access_scope);
            sql.push_str(" order by m.session_id, m.seq limit ?");
            args.push(Value::Integer(remaining as i64));
            let mut stmt = self.conn.prepare(&sql)?;
            let rows =
                stmt.query_map(rusqlite::params_from_iter(args.iter()), row_to_message_hit)?;
            for row in rows {
                let mut hit = row?;
                hit.fuzzy_score = Some(tier[0].1 .0);
                top.push((hit, tier[0].1 .1));
                matched += 1;
            }
        }
        let hits = top
            .into_iter()
            .skip(filters.offset)
            .map(|(hit, _)| hit)
            .collect();
        let explain = include_explain
            .then(|| {
                // Reuse the count the ranking window already took, when it took one.
                let corpus = match counted_corpus {
                    Some(corpus) => corpus,
                    None => self.corpus_count_with_base("m.tool_name is not null", filters)?,
                };
                Ok::<_, anyhow::Error>(SearchExplain {
                    prefilter: None,
                    candidates: Some(explained_matching_rows.unwrap_or(matched)),
                    prefilter_skipped: Some(
                        "complete filtered tool-name vocabulary scored before matching rows are loaded"
                            .to_string(),
                    ),
                    corpus,
                })
            })
            .transpose()?;
        Ok((hits, explain))
    }

    /// Collect every row the prepared statement returns.
    ///
    /// Retained memory is `O(R)` in the returned rows and their content bytes, because the caller
    /// is handed the whole page at once. `R` is bounded by whatever `LIMIT` the request carried, and
    /// an omitted limit means all results on the Rust, Python, and CLI surfaces, so a query matching
    /// the corpus retains the corpus. That is the contract those surfaces promise rather than an
    /// unbounded accident: MCP supplies a finite page instead, and Rust aborts on allocation failure,
    /// so a stated bound is the only defense a caller has. Work scanned is independent of `R` — the
    /// verification cost belongs to the statement, which is why a small `LIMIT` returns sooner
    /// without finishing sooner.
    fn query_message_hits(
        &self,
        sql: &str,
        args: &[rusqlite::types::Value],
    ) -> Result<Vec<MessageHit>> {
        let mut stmt = self.conn.prepare(sql)?;
        let rows = stmt.query_map(rusqlite::params_from_iter(args.iter()), row_to_message_hit)?;
        rows.collect::<rusqlite::Result<Vec<_>>>()
            .map_err(Into::into)
    }

    /// Count the messages matching the structural filters (role / provider / session / path / time /
    /// tool / class) — the corpus that literal or regex content matching then scans, and the
    /// denominator every receipt reports. Only receipts and the fuzzy tool-name planner call
    /// this; the search hot path probes [`Db::filtered_corpus_reaches`] instead.
    ///
    /// Cost: index-only. The class predicate defaults to `kind != 'harness_notice'`, and no
    /// index answers a `!=` without visiting rows, so this is computed as
    /// `count(every class) - count(only the excluded classes)`. The first term is served by the
    /// index that leads with the selected filter column (`role`, `provider`, `session_id`, `ts`,
    /// or SQLite's smallest index for `count(*)`); the second by [`MESSAGE_KIND_INDEX`], which
    /// leads with `kind` and carries every column a structural filter tests. Time is
    /// `O(F + E)` index entries for `F` rows matching the structural filters and `E` rows of the
    /// excluded classes (2 % of a real index), never `O(N)` message-row page reads. Measured on
    /// a 22.6 GB / 2.69 M-row index: the previous single `!=` statement scanned every row in
    /// 117 s; the decomposition reads ~80 MB of index pages in ≈5 s cold and well under a
    /// second warm. When [`MESSAGE_KIND_INDEX`] is absent (an index an older aise wrote, before
    /// its elected writer's next refresh builds it), the second term falls back to the row scan
    /// with the same result. See [`Db::corpus_count_statements`] for the exact statements.
    fn filtered_corpus_count(&self, filters: &MessageFilters) -> Result<i64> {
        self.corpus_count_with_base("1 = 1", filters)
    }

    /// Whether a fuzzy page has any row to rank, and how many scored candidates it may retain.
    ///
    /// `offset + limit` is what the caller asked to rank, and both are theirs to choose: paging
    /// deep into a large result set is legitimate, which is why there is no arbitrary window cap.
    /// Ranking further than there are rows to rank never is. An offset past the last eligible row
    /// used to score the whole corpus anyway: [`retain_top_fuzzy_hits`] truncates only above the
    /// retention target, an unreachable target never truncated, so the vector of scored rows — each
    /// carrying its message content — grew to every matching row and `skip(offset)` then discarded
    /// all of it. Answering that page from the count is what removes the cost.
    ///
    /// The `min` on the returned limit is a clamp, not that repair. Retention was always at most
    /// the matching rows, which are at most the rows scanned, which are at most the corpus, so
    /// taking the minimum cannot lower a peak; it only keeps `ranked_limit` from being a number no
    /// run could reach. A deep page that does land inside the corpus still retains up to every
    /// matching row, because scoring the complete corpus and keeping a top-K larger than it has no
    /// smaller answer.
    ///
    /// The count reads covering indexes rather than message rows (see
    /// [`Db::filtered_corpus_count`]) and is taken only when the requested window exceeds one
    /// scoring batch, so an ordinary page pays nothing for it and is told `None` back so it counts
    /// on its own terms if a receipt needs one. `base_predicate` is the same fragment
    /// [`Db::corpus_count_with_base`] takes, so each caller measures the rows it actually scans; an
    /// over-estimate would only leave the window wider than needed, never truncate a real page.
    fn fuzzy_ranking_window(
        &self,
        base_predicate: &str,
        filters: &MessageFilters,
    ) -> Result<FuzzyRankingWindow> {
        let requested = fuzzy_ranked_limit(filters)?;
        if requested <= FUZZY_SCORE_BATCH_SIZE {
            return Ok(FuzzyRankingWindow::Rank {
                limit: requested,
                corpus: None,
            });
        }
        let corpus = self.corpus_count_with_base(base_predicate, filters)?;
        let corpus_rows = usize::try_from(corpus).unwrap_or(usize::MAX);
        // A zero offset never skips anything, so it never lands past the last eligible row. The
        // comparison alone would say otherwise for an empty corpus, where `0 >= 0` holds, and the
        // receipt would blame an offset that is zero and drop `candidates` — a filter matching no
        // rows would then describe itself one way under a small limit and another under a large
        // one. An empty corpus scores nothing on the ordinary path anyway.
        if filters.offset > 0 && filters.offset >= corpus_rows {
            return Ok(FuzzyRankingWindow::PastCorpus { corpus });
        }
        Ok(FuzzyRankingWindow::Rank {
            limit: requested.min(corpus_rows),
            corpus: Some(corpus),
        })
    }

    /// [`Db::filtered_corpus_count`] over the rows that also satisfy `base_predicate`, an SQL
    /// fragment over alias `m` (`"m.tool_name is not null"` for the fuzzy tool-name planner).
    fn corpus_count_with_base(
        &self,
        base_predicate: &str,
        filters: &MessageFilters,
    ) -> Result<i64> {
        let mut corpus = 0_i64;
        for (sql, args, sign) in self.corpus_count_statements(base_predicate, filters) {
            let count: i64 =
                self.conn
                    .query_row(&sql, rusqlite::params_from_iter(args.iter()), |row| {
                        row.get(0)
                    })?;
            corpus += sign * count;
        }
        Ok(corpus)
    }

    /// The signed count statements whose sum is the filtered corpus (see
    /// [`Db::filtered_corpus_count`]). Public to tests, which assert every statement plans as
    /// an index-only read.
    fn corpus_count_statements(
        &self,
        base_predicate: &str,
        filters: &MessageFilters,
    ) -> Vec<(String, Vec<rusqlite::types::Value>, i64)> {
        let build = |class: ClassSelection<'_>| {
            let mut sql = format!("select count(*) from messages m where {base_predicate}");
            if matches!(class, ClassSelection::Only(_)) {
                // The literal clause that lets SQLite use the partial index; the bound
                // `m.kind in (?)` the class selection appends narrows to the excluded set.
                sql.push_str(&format!(" and m.{}", excluded_kinds_predicate()));
            }
            let mut args = Vec::new();
            append_message_filters_with_class(
                &mut sql,
                &mut args,
                filters,
                &self.access_scope,
                class,
            );
            if filters.tool.is_some() {
                // `unicode_lower_contains(m.tool_name, ?)` is already false on NULL, so this adds
                // no rows; it states the partial index's condition so `idx_messages_tool_name`
                // (covering) can answer the count instead of a row scan.
                sql.push_str(" and m.tool_name is not null");
            }
            (sql, args)
        };
        let excludable = crate::models::MessageKind::EXCLUDABLE_BY_DEFAULT;
        match filters.kind_predicate() {
            crate::models::KindPredicate::AllExcept(excluded) => {
                debug_assert!(excluded.iter().all(|kind| excludable.contains(kind)));
                let (total_sql, total_args) = build(ClassSelection::Unrestricted);
                let (excluded_sql, excluded_args) = build(ClassSelection::Only(&excluded));
                vec![
                    (total_sql, total_args, 1),
                    (excluded_sql, excluded_args, -1),
                ]
            }
            // An explicit selection inside the excludable set (`--kinds harness-notice`) is the
            // partial index's own population. Any other explicit set names classes no index
            // carries, so it counts by reading rows: `O(N)` row pages, the bound the receipt
            // description states for explicit class selections.
            crate::models::KindPredicate::Only(kinds)
                if !kinds.is_empty() && kinds.iter().all(|kind| excludable.contains(kind)) =>
            {
                let (sql, args) = build(ClassSelection::Only(&kinds));
                vec![(sql, args, 1)]
            }
            crate::models::KindPredicate::Only(_) => {
                let (sql, args) = build(ClassSelection::FromFilters);
                vec![(sql, args, 1)]
            }
        }
    }

    /// Whether [`MESSAGE_KIND_INDEX`] exists.
    pub(crate) fn message_kind_index_exists(&self) -> Result<bool> {
        Ok(self.conn.query_row(
            "select exists(select 1 from sqlite_schema where type = 'index' and name = ?1)",
            params![MESSAGE_KIND_INDEX],
            |row| row.get(0),
        )?)
    }

    /// Build [`MESSAGE_KIND_INDEX`] if it is missing; returns whether it was built.
    ///
    /// The build is one full scan of `messages` (minutes on a multi-gigabyte index) inside one
    /// write transaction, so it runs only where a long write is already expected: [`Db::init`]
    /// calls it while the table is still empty (free), and the elected writer calls it at the
    /// start of every refresh ([`crate::indexer::reindex_until`]) so an index written by an
    /// older aise gains it once, under the cross-process writer election, while WAL readers keep
    /// serving. Until then every count that needs it degrades to the row scan, never to an error.
    pub(crate) fn ensure_message_kind_index(&self) -> Result<bool> {
        if self.message_kind_index_exists()? {
            return Ok(false);
        }
        self.report_progress(
            "building the message-class index once (one scan of every indexed message) so \
             receipts and class-filtered counts read the index instead of every message row",
        );
        let started = std::time::Instant::now();
        self.conn.execute_batch(&format!(
            "create index if not exists {MESSAGE_KIND_INDEX} on messages{MESSAGE_KIND_INDEX_COLUMNS} \
             where {}",
            excluded_kinds_predicate()
        ))?;
        self.report_progress(&format!(
            "built the message-class index in {:.1?}",
            started.elapsed()
        ));
        Ok(true)
    }

    /// Determine whether the structurally filtered corpus reaches `threshold` without counting
    /// beyond the planner decision boundary. Unlike [`Db::filtered_corpus_count`], this is safe on
    /// the normal hot path because SQLite stops the inner relation after `threshold` rows.
    fn filtered_corpus_reaches(&self, filters: &MessageFilters, threshold: i64) -> Result<bool> {
        use rusqlite::types::Value;
        anyhow::ensure!(threshold > 0, "corpus probe threshold must be positive");
        let mut inner = String::from("select 1 from messages m where 1 = 1");
        let mut args: Vec<Value> = Vec::new();
        append_message_filters(&mut inner, &mut args, filters, &self.access_scope);
        inner.push_str(" limit 1 offset ?");
        args.push(Value::Integer(threshold - 1));
        let sql = format!("select exists({inner})");
        Ok(self
            .conn
            .query_row(&sql, rusqlite::params_from_iter(args.iter()), |row| {
                row.get(0)
            })?)
    }

    fn corpus_count(&self, filters: &MessageFilters, cached: Option<i64>) -> Result<i64> {
        cached.map_or_else(|| self.filtered_corpus_count(filters), Ok)
    }

    fn staged_candidate_count(&self, filters: &MessageFilters) -> Result<i64> {
        use rusqlite::types::Value;
        let mut sql = String::from("select count(*) from messages m where 1 = 1");
        let mut args: Vec<Value> = Vec::new();
        append_message_filters(&mut sql, &mut args, filters, &self.access_scope);
        sql.push_str(" and m.id in (select id from _trigram_cand)");
        Ok(self
            .conn
            .query_row(&sql, rusqlite::params_from_iter(args.iter()), |row| {
                row.get(0)
            })?)
    }

    /// Prepare the trigram acceleration path and, when requested, return diagnostics for the
    /// same decision. The prefilter is a superset: it may include false positives, but the
    /// caller's literal/regex verifier remains authoritative. Returning `(false, explain)` is
    /// still correct: it means either no usable anchor exists or the structured filters already
    /// made a direct scan cheaper than intersecting the whole-corpus trigram index.
    fn prepare_content_prefilter(
        &self,
        pattern: Option<&str>,
        filters: &MessageFilters,
        include_explain: bool,
    ) -> Result<(bool, Option<SearchExplain>)> {
        let Some(pattern) = pattern else {
            let explain = include_explain
                .then(|| {
                    self.filtered_corpus_count(filters)
                        .map(|corpus| SearchExplain {
                            prefilter: None,
                            candidates: None,
                            prefilter_skipped: None,
                            corpus,
                        })
                })
                .transpose()?;
            return Ok((false, explain));
        };

        let corpus = if include_explain {
            Some(self.filtered_corpus_count(filters)?)
        } else {
            None
        };
        // The custom index tokenizes documents with `str::to_lowercase`, whose word-final `Σ`
        // becomes `ς`, while the verifier folds every sigma onto `σ`
        // (`crate::util::fold_caseless`). One sigma spelling therefore asks for trigrams the other
        // spelling never stored, so a row the verifier accepts can be missing from the candidate
        // set — a prefilter narrowing the result instead of widening it. Scan directly for those
        // patterns and let the verifier decide. FTS5 folds all three sigmas onto one form, so the
        // schema-v4 path above keeps its indexed candidates.
        if pattern.contains(SIGMAS) {
            let explain = if include_explain {
                Some(SearchExplain {
                    prefilter: None,
                    candidates: None,
                    prefilter_skipped: Some(
                        "the pre-v4 compatibility index spells sigma by position, so this query scans directly"
                            .into(),
                    ),
                    corpus: self.corpus_count(filters, corpus)?,
                })
            } else {
                None
            };
            return Ok((false, explain));
        }
        let Some(groups) = crate::trigram::trigram_prefilter_groups(pattern) else {
            let explain = if include_explain {
                Some(SearchExplain {
                    prefilter: None,
                    candidates: None,
                    prefilter_skipped: None,
                    corpus: self.corpus_count(filters, corpus)?,
                })
            } else {
                None
            };
            return Ok((false, explain));
        };

        // Corpus-size gate: only query the trigram index when the structurally-filtered corpus is
        // large enough to benefit. A role/session/path/ts/tool filter can restrict the scan to a
        // small slice, where a direct literal/regex scan beats intersecting it against the
        // whole-corpus trigram index. Regression-free: the prefilter is a superset and the final
        // literal/regex verifier remains authoritative.
        let use_prefilter = !filters.narrows_corpus()
            || if let Some(corpus) = corpus {
                corpus >= self.prefilter_min_corpus
            } else {
                self.filtered_corpus_reaches(filters, self.prefilter_min_corpus)?
            };
        let prefilter = include_explain.then(|| crate::trigram::render_prefilter_groups(&groups));
        if !use_prefilter {
            let explain = if include_explain {
                Some(SearchExplain {
                    prefilter,
                    candidates: None,
                    prefilter_skipped: Some(format!(
                        "structured filters reduced the corpus below the pre-v4 compatibility prefilter threshold ({})",
                        self.prefilter_min_corpus
                    )),
                    corpus: self.corpus_count(filters, corpus)?,
                })
            } else {
                None
            };
            return Ok((false, explain));
        }

        // Custom parallel-built trigram index (base) + un-indexed delta; the final literal/regex
        // verifier checks every candidate, so this is a SUPERSET filter.
        let base_max = self.ensure_trigram_base()?;
        let candidates = crate::trigram_index::candidates(&self.conn, &groups)?;
        self.stage_candidates(base_max, &candidates)?;
        let explain = if include_explain {
            Some(SearchExplain {
                prefilter,
                candidates: Some(self.staged_candidate_count(filters)?),
                prefilter_skipped: None,
                corpus: self.corpus_count(filters, corpus)?,
            })
        } else {
            None
        };
        Ok((true, explain))
    }

    /// Execute the actual message-search plan and return its diagnostics while discarding hits.
    /// Prefer [`Db::search_messages_with_explain`] when the caller also needs results so the query
    /// runs only once. This method deliberately shares every field/mode/schema branch with search;
    /// it never invokes a second legacy-only planner.
    pub fn explain_message_search(
        &self,
        query: &str,
        filters: &MessageFilters,
    ) -> Result<SearchExplain> {
        let (_, explain) = self.search_messages_with_explain(query, filters, true)?;
        explain.context("message search explanation was not produced")
    }

    /// Fetch the messages surrounding a `(session_id, seq)` anchor — `before` rows
    /// before and `after` rows after — for `messages search --context`. Ordered by
    /// seq; served directly by the `(session_id, seq)` index.
    pub fn message_context(
        &self,
        session_id: &str,
        seq: i64,
        before: i64,
        after: i64,
    ) -> Result<Vec<MessageHit>> {
        use rusqlite::types::Value;

        self.validate_access_scope()?;
        anyhow::ensure!(before >= 0, "context before must be non-negative");
        anyhow::ensure!(after >= 0, "context after must be non-negative");
        let mut sql = String::from(
            "select session_id, provider, seq, role, ts, tool_name, kind, tool_call_id, content from messages
             where session_id = ? and seq between ? and ?",
        );
        // Saturate instead of wrapping: a huge `context` request (e.g. i64::MAX) must widen
        // to the whole session, not overflow into a negative BETWEEN bound that silently
        // matches nothing (release) or panics (debug).
        let mut args = vec![
            Value::Text(session_id.to_string()),
            Value::Integer(seq.saturating_sub(before)),
            Value::Integer(seq.saturating_add(after)),
        ];
        push_access_scope(&mut sql, &mut args, "session_id", &self.access_scope);
        sql.push_str(" order by seq");
        let mut stmt = self.conn.prepare(&sql)?;
        let rows = stmt.query_map(rusqlite::params_from_iter(args.iter()), row_to_message_hit)?;
        rows.collect::<rusqlite::Result<Vec<_>>>()
            .map_err(Into::into)
    }

    /// Fetch context for multiple anchors in one SQLite statement. The returned windows preserve
    /// anchor order and include empty entries for anchors that have no visible rows.
    pub(crate) fn message_context_windows(
        &self,
        anchors: &[(String, i64)],
        before: i64,
        after: i64,
    ) -> Result<Vec<Vec<MessageHit>>> {
        use rusqlite::types::Value;

        self.validate_access_scope()?;
        anyhow::ensure!(before >= 0, "context before must be non-negative");
        anyhow::ensure!(after >= 0, "context after must be non-negative");
        let mut windows = vec![Vec::new(); anchors.len()];
        if anchors.is_empty() {
            return Ok(windows);
        }
        let bounds = anchors
            .iter()
            .map(|(session_id, seq)| {
                (
                    session_id,
                    seq.saturating_sub(before),
                    seq.saturating_add(after),
                )
            })
            .collect::<Vec<_>>();
        let mut sql = String::from(
            "with anchors(ord, session_id, lower_seq, upper_seq) as materialized (
                 select cast(key as integer),
                        json_extract(value, '$[0]'),
                        json_extract(value, '$[1]'),
                        json_extract(value, '$[2]')
                   from json_each(?)
             )
             select a.ord, m.session_id, m.provider, m.seq, m.role, m.ts, m.tool_name,
                    m.kind, m.tool_call_id, m.content
               from anchors a
               join messages m on m.session_id = a.session_id
                              and m.seq between a.lower_seq and a.upper_seq
              where 1 = 1",
        );
        let mut args = vec![Value::Text(serde_json::to_string(&bounds)?)];
        push_access_scope(&mut sql, &mut args, "m.session_id", &self.access_scope);
        sql.push_str(" order by a.ord, m.seq");
        let mut stmt = self.conn.prepare(&sql)?;
        let rows = stmt.query_map(rusqlite::params_from_iter(args.iter()), |row| {
            // `ord` is json_each's key over the bounds array, so it numbers the anchors from
            // zero and indexes `windows` directly. SQLite stores it as an i64 and rusqlite
            // stopped converting integers to usize in 0.38, so read the stored width and
            // narrow once here.
            Ok((row.get::<_, i64>(0)?, row_to_message_hit_at(row, 1)?))
        })?;
        for row in rows {
            let (ord, hit) = row?;
            // A negative or oversized ordinal would index outside `windows`. Indexing panics
            // there; naming the value and the bound reports which query produced it.
            let window = usize::try_from(ord)
                .ok()
                .and_then(|ordinal| windows.get_mut(ordinal))
                .with_context(|| {
                    format!(
                        "context window ordinal {ord} falls outside the {} anchors queried",
                        anchors.len()
                    )
                })?;
            window.push(hit);
        }
        Ok(windows)
    }

    /// Fetch compact session metadata for a set of canonical session IDs in one indexed query.
    ///
    /// The JSON table-valued parameter keeps SQLite bind usage constant as a result batch grows;
    /// joining it to `sessions.id` avoids an N+1 lookup and SQLite's host-parameter ceiling.
    /// Unknown IDs are absent from the returned map.
    pub fn session_metadata(
        &self,
        ids: &[String],
    ) -> Result<std::collections::HashMap<String, crate::models::SessionMeta>> {
        use crate::models::SessionMeta;
        use rusqlite::types::Value;
        use std::collections::HashMap;
        self.validate_access_scope()?;
        let mut map = HashMap::new();
        if ids.is_empty() {
            return Ok(map);
        }
        let mut sql = String::from(
            "select s.id, s.provider_session_id, s.cwd, s.repo_root, s.title, s.updated_at,
                    s.last_message_at, s.message_count, s.parse_warning, s.parent_session_id,
                    s.agent_label
               from json_each(?) requested
               join sessions s on s.id = requested.value
              where 1 = 1",
        );
        let mut args = vec![Value::Text(serde_json::to_string(ids)?)];
        push_access_scope(&mut sql, &mut args, "s.id", &self.access_scope);
        let mut stmt = self.conn.prepare(&sql)?;
        let rows = stmt.query_map(rusqlite::params_from_iter(args.iter()), |row| {
            Ok((
                row.get::<_, String>(0)?,
                SessionMeta {
                    provider_session_id: row.get(1)?,
                    cwd: row.get(2)?,
                    repo_root: row.get(3)?,
                    title: row.get(4)?,
                    updated_at: row
                        .get::<_, Option<String>>(5)?
                        .as_deref()
                        .and_then(crate::util::parse_datetime),
                    last_message_at: row
                        .get::<_, Option<String>>(6)?
                        .as_deref()
                        .and_then(crate::util::parse_datetime),
                    message_count: row.get(7)?,
                    parse_warning: row.get(8)?,
                    parent_session_id: row.get(9)?,
                    agent_label: row.get(10)?,
                },
            ))
        })?;
        for row in rows {
            let (id, meta) = row?;
            map.insert(id, meta);
        }
        Ok(map)
    }

    /// Load verbatim provider metadata only for explicitly requested canonical session IDs.
    ///
    /// Let `S` be the number of requested sessions and `B` the returned metadata bytes. One JSON
    /// table-valued parameter is joined to indexed `sessions.id`, so database work is
    /// `O(S log N + B)`, bind usage is `O(1)`, and output memory is `O(S + B)`. Ordinary searches
    /// do not call this method.
    pub fn session_raw_provider_metadata(
        &self,
        ids: &[String],
    ) -> Result<std::collections::BTreeMap<String, Box<serde_json::value::RawValue>>> {
        use rusqlite::types::Value;
        use std::collections::BTreeMap;

        self.validate_access_scope()?;
        let mut map = BTreeMap::new();
        if ids.is_empty() {
            return Ok(map);
        }
        let mut sql = String::from(
            "select s.id, s.raw_metadata_json
               from json_each(?) requested
               join sessions s on s.id = requested.value
              where s.raw_metadata_json is not null",
        );
        let mut args = vec![Value::Text(serde_json::to_string(ids)?)];
        push_access_scope(&mut sql, &mut args, "s.id", &self.access_scope);
        let mut statement = self.conn.prepare(&sql)?;
        let rows = statement.query_map(rusqlite::params_from_iter(args.iter()), |row| {
            Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
        })?;
        for row in rows {
            let (session_id, raw_json) = row?;
            let raw = serde_json::value::RawValue::from_string(raw_json).map_err(|error| {
                anyhow::anyhow!(
                    "session {session_id} contains invalid raw provider metadata JSON: {error}"
                )
            })?;
            map.insert(session_id, raw);
        }
        Ok(map)
    }

    /// Return only source-authoritative human text for prose analytics such as `repeats`.
    ///
    /// Whole human messages retain their original identity and content. Mixed messages concatenate
    /// source-ordered human parts, so generated or harness regions cannot become repeat evidence.
    /// Unknown authorship and mirror rows fail closed. Let `M` be structurally eligible messages,
    /// `P_h` human parts, and `B_h` emitted human bytes: work is `O(M + P_h + B_h)` plus the
    /// authoritative literal/regex predicate and output ordering; finite result memory is
    /// `O(K + bytes(K))`, while an explicit unlimited request retains all matches. SQLite owns the
    /// correlated part-scan state. This path deliberately does not use raw-content trigrams because
    /// a match may cross two human fragments after an intervening generated fragment is removed.
    pub(crate) fn search_attributable_human_messages(
        &self,
        query: &str,
        filters: &MessageFilters,
    ) -> Result<Vec<MessageHit>> {
        use rusqlite::types::Value;

        self.validate_access_scope()?;
        if filters.match_mode == MessageSearchMode::Fuzzy {
            bail!("attributable human-message analytics do not support fuzzy matching");
        }
        if filters.field.unwrap_or(SearchField::Content) != SearchField::Content {
            bail!("attributable human-message analytics search message content only");
        }
        if filters.match_mode == MessageSearchMode::Regex {
            regex::Regex::new(query).map_err(|error| anyhow!("invalid regex: {error}"))?;
        }

        let mut inner = String::from(
            "select m.session_id, m.provider, m.seq, m.role, m.ts, m.tool_name, m.kind,
                    m.tool_call_id,
                    case
                      when m.authorship = 'human' then m.content
                      else (
                        select group_concat(fragment, '')
                        from (
                          select substr(m.content, p.start_char + 1,
                                        p.end_char - p.start_char) as fragment
                          from message_content_parts p
                          where p.message_id = m.id and p.authorship = 'human'
                          order by p.ordinal
                        )
                      )
                    end as content
             from messages m
             where m.record_relation = 'original'
               and (
                 m.authorship = 'human'
                 or (
                   m.authorship = 'mixed'
                   and exists (
                     select 1 from message_content_parts p
                     where p.message_id = m.id and p.authorship = 'human'
                   )
                 )
               )",
        );
        let mut args: Vec<Value> = Vec::new();
        append_message_filters(&mut inner, &mut args, filters, &self.access_scope);
        let mut sql = format!("select * from ({inner}) attributable where 1 = 1");
        if !query.is_empty() {
            match filters.match_mode {
                MessageSearchMode::Literal => {
                    sql.push_str(" and unicode_lower_contains(attributable.content, ?)");
                    args.push(Value::Text(fold_caseless(query)));
                }
                MessageSearchMode::Regex => {
                    sql.push_str(" and rust_regexp(?, attributable.content)");
                    args.push(Value::Text(query.to_string()));
                }
                MessageSearchMode::Fuzzy => unreachable!("fuzzy rejected above"),
            }
        }
        sql.push_str(" order by attributable.session_id, attributable.seq");
        if filters.limit > 0 {
            sql.push_str(" limit ? offset ?");
            args.push(Value::Integer(filters.limit as i64));
            args.push(Value::Integer(filters.offset as i64));
        } else if filters.offset > 0 {
            sql.push_str(" limit -1 offset ?");
            args.push(Value::Integer(filters.offset as i64));
        }
        let mut stmt = self.conn.prepare(&sql)?;
        let rows = stmt.query_map(rusqlite::params_from_iter(args.iter()), row_to_message_hit)?;
        rows.collect::<rusqlite::Result<Vec<_>>>()
            .map_err(Into::into)
    }

    /// Scan user messages and tag each against `policies` (policies in selection order,
    /// categories in declaration order, first match wins — so `other` must be last).
    /// `filters.limit == 0` means unlimited.
    ///
    /// Corrections are intrinsically scoped to `role = 'user'` — the user's own prompts, a small
    /// slice of the corpus (≈7.7k rows / ~10 MB on the real index vs 628k total). A direct regex
    /// scan of that slice is milliseconds. We deliberately do NOT route this through the trigram
    /// prefilter: the correction keywords ("wrong", "stop", "actually", …) have very common
    /// trigrams, so a prefilter `MATCH` would scan a large fraction of the multi-GB trigram index
    /// (95% of which is tool output the `role='user'` filter then discards) AND trigger its lazy
    /// build — measured ~21 s, strictly slower than scanning the user rows outright. The structural
    /// `role='user'` filter is the selective one here, so we lean on it alone.
    pub(crate) fn find_corrections(
        &self,
        policies: &crate::corrections::ResolvedCorrectionPolicySet,
        filters: &MessageFilters,
    ) -> Result<Vec<MessageClassificationMatch>> {
        self.validate_access_scope()?;
        // An empty selection (`[skills].enabled = []`) defines no categories, so no row can match.
        // Returning here skips a full scan of the user slice whose only possible result is this
        // same empty vector. Placed AFTER the scope check so "no rules" cannot become a way to
        // query an index the caller is not allowed to touch.
        if policies.is_empty() {
            return Ok(Vec::new());
        }
        self.find_corrections_with_after_candidates(policies, filters, || {})
    }

    fn find_corrections_with_after_candidates(
        &self,
        policies: &crate::corrections::ResolvedCorrectionPolicySet,
        filters: &MessageFilters,
        after_candidates: impl FnOnce(),
    ) -> Result<Vec<MessageClassificationMatch>> {
        use rusqlite::types::Value;

        let mut filters = filters.clone();
        filters.role = Some(Role::User);
        // A correction is what a PERSON told the agent. In a subagent transcript the `role='user'`
        // rows are the SPAWNING AGENT's delegation prompt, not anything a human typed, and
        // subagents outnumber user-started sessions roughly five to one (models.rs SessionKind).
        // Leaving them in lets ordinary orchestrator instructions register as corrections --
        // `\bdon'?t forget\b` matches "don't forget to check the tests" exactly.
        //
        // Narrowed here, beside the forced role, because both are the same kind of claim about
        // what the operation intrinsically means rather than a caller preference.
        // `--session-kinds` can reopen subagent session scope, but it never overrides source
        // authorship: agent delegation prompts remain excluded while genuinely human content in
        // that scope remains reachable. The SET is the mechanism, never an
        // `include_subagents` boolean.
        filters
            .session_kinds
            .get_or_insert_with(|| vec![crate::models::SessionKind::User]);

        struct CorrectionCandidate {
            message_id: i64,
            session_id: String,
            message_seq: i64,
            provider: Provider,
            ts: Option<String>,
            content: String,
            // (absolute start character, start byte, end byte) into `content`.
            human_parts: Option<Vec<(usize, usize, usize)>>,
        }

        fn resolve_human_part_bytes(
            message_id: i64,
            content: &str,
            ranges: &[(usize, usize)],
        ) -> Result<Vec<(usize, usize, usize)>> {
            let mut resolved = Vec::with_capacity(ranges.len());
            let mut range_index = 0;
            let mut start_byte = None;
            for (char_index, byte_index) in content
                .char_indices()
                .map(|(byte_index, _)| byte_index)
                .chain(std::iter::once(content.len()))
                .enumerate()
            {
                while let Some(&(start_char, end_char)) = ranges.get(range_index) {
                    if start_byte.is_none() && char_index == start_char {
                        start_byte = Some(byte_index);
                    }
                    if char_index == end_char {
                        let start_byte = start_byte.take().ok_or_else(|| {
                            anyhow!(
                                "message {message_id} human content part starts beyond its content"
                            )
                        })?;
                        resolved.push((start_char, start_byte, byte_index));
                        range_index += 1;
                        continue;
                    }
                    break;
                }
            }
            if range_index != ranges.len() {
                bail!(
                    "message {message_id} human content part ends beyond its content; \
                     reindex the source transcript"
                );
            }
            Ok(resolved)
        }

        // Keep candidate rows and their content-part ranges in one SQLite read snapshot, then
        // release the transaction before CPU-bound parallel regex classification.
        let rows = self.with_read_snapshot(|| {
            // Select only source-authoritative human content. Unknown schema-5 authorship stays
            // excluded rather than being guessed; unavailable source transcripts retain their
            // index rows but cannot become evidence about what a person said.
            let mut sql = String::from(CORRECTION_CANDIDATES_SQL);
            let mut args: Vec<Value> = Vec::new();
            append_message_filters(&mut sql, &mut args, &filters, &self.access_scope);
            // Timestamp alone is not a total order: providers may omit it, and several messages
            // may share one timestamp. Stable tie-breakers make offset pages reproducible and
            // non-overlapping across the CLI, Rust, Python, and MCP adapters.
            sql.push_str(" order by m.ts desc, m.session_id asc, m.seq asc");

            let mut stmt = self.conn.prepare(&sql)?;
            // Materialize each candidate's full content exactly once before going parallel:
            // rusqlite's `Connection`/`Statement` are not `Sync`, while Rayon requires owned rows.
            let mut rows: Vec<CorrectionCandidate> = stmt
                .query_map(rusqlite::params_from_iter(args.iter()), |row| {
                    let authorship = row.get::<_, String>(6)?;
                    Ok(CorrectionCandidate {
                        message_id: row.get(0)?,
                        session_id: row.get(1)?,
                        message_seq: row.get(2)?,
                        provider: decode_db_enum(
                            row.get::<_, String>(3)?,
                            3,
                            "messages.provider",
                            Provider::from_db_str,
                        )?,
                        ts: row.get(4)?,
                        content: row.get(5)?,
                        human_parts: (authorship == "mixed").then(Vec::new),
                    })
                })?
                .collect::<rusqlite::Result<Vec<_>>>()?;
            drop(stmt);
            after_candidates();

            // Fetch every selected mixed-message range in one additional indexed query. Resolve
            // its Unicode-scalar coordinates to borrowed UTF-8 slices with one linear pass per
            // mixed message, avoiding both repeated SQLite `substr` prefix scans and copied
            // fragment text. This is two set-oriented queries total, never one query per message.
            if rows.iter().any(|row| row.human_parts.is_some()) {
                let mut parts_sql = String::from(CORRECTION_HUMAN_PARTS_SQL);
                let mut parts_args: Vec<Value> = Vec::new();
                append_message_filters(
                    &mut parts_sql,
                    &mut parts_args,
                    &filters,
                    &self.access_scope,
                );
                parts_sql.push_str(" order by m.id, p.ordinal");
                let mut human_parts_by_message: HashMap<i64, Vec<(usize, usize)>> = HashMap::new();
                let mut parts_stmt = self.conn.prepare(&parts_sql)?;
                let part_rows =
                    parts_stmt.query_map(rusqlite::params_from_iter(parts_args.iter()), |row| {
                        Ok((
                            row.get::<_, i64>(0)?,
                            row.get::<_, i64>(1)?,
                            row.get::<_, i64>(2)?,
                        ))
                    })?;
                for part in part_rows {
                    let (message_id, start_char, end_char) = part?;
                    let start_char = usize::try_from(start_char).with_context(|| {
                        format!(
                            "message {message_id} has a negative human content-part start coordinate"
                        )
                    })?;
                    let end_char = usize::try_from(end_char).with_context(|| {
                        format!(
                            "message {message_id} has a negative human content-part end coordinate"
                        )
                    })?;
                    human_parts_by_message
                        .entry(message_id)
                        .or_default()
                        .push((start_char, end_char));
                }
                for row in &mut rows {
                    if let Some(parts) = &mut row.human_parts {
                        let ranges = human_parts_by_message
                            .remove(&row.message_id)
                            .unwrap_or_default();
                        *parts =
                            resolve_human_part_bytes(row.message_id, &row.content, &ranges)?;
                    }
                }
            }
            Ok(rows)
        })?;

        // Classify one candidate against whole human messages or source-ordered human fragments.
        // Policies and categories remain the outer loops, so priority is unchanged; fragments are
        // independent regex inputs, so generated gaps cannot create an artificial cross-part hit.
        // Borrow content/fragments only during matching, then move the one owned full content into
        // the result without a per-match clone. Both sequential and parallel paths share this
        // closure and therefore the same provenance semantics.
        let classify = |row: CorrectionCandidate| -> Option<MessageClassificationMatch> {
            let CorrectionCandidate {
                session_id,
                message_seq,
                provider,
                ts,
                content,
                human_parts,
                ..
            } = row;
            let (identity, hit) = match &human_parts {
                Some(parts) => policies.classify_fragments(parts.iter().map(
                    |(start_char, start_byte, end_byte)| {
                        (*start_char, &content[*start_byte..*end_byte])
                    },
                )),
                None => policies.classify(&content),
            }?;
            let ts = ts.as_deref().and_then(|value| {
                chrono::DateTime::parse_from_rfc3339(value)
                    .ok()
                    .map(|dt| dt.with_timezone(&Utc))
            });
            Some(MessageClassificationMatch {
                session_id,
                message_seq,
                provider,
                ts,
                policy_name: identity.name.clone(),
                category: hit.category.to_string(),
                matched_text: hit.matched_text,
                match_start_char: hit.match_start_char,
                match_end_char_exclusive: hit.match_end_char_exclusive,
                content,
            })
        };

        // Let `R` be selected messages, `P_h` selected human parts, and `B` their content bytes.
        // Stable SQL ordering is O(R log R + P_h log P_h) in the worst case when SQLite cannot
        // satisfy it from an index; row/part projection plus classification is O(R + P_h + B)
        // before regex-engine costs. Retained memory is O(R + P_h + B). No N+1 query or per-part
        // full-content copy is introduced, and all rows/parts come from one read snapshot.
        // Run sequentially when the configured pool is single-threaded (threads=1) to avoid Rayon's
        // split/join overhead; otherwise classify in parallel. `regex::Regex` is `Sync`, so sharing
        // `patterns` read-only across workers is safe. Both paths preserve the SQL total order
        // (Rayon's `collect` is order-preserving), so output is identical — verified by
        // `find_corrections_parallel_matches_sequential`. `ResolvedCorrectionPolicySet` holds only
        // `Regex` and owned strings, so sharing it read-only across workers is safe.
        use rayon::prelude::*;
        let mut out: Vec<MessageClassificationMatch> = if self.runtime.worker_threads() <= 1 {
            rows.into_iter().filter_map(classify).collect()
        } else {
            self.runtime
                .install(|| rows.into_par_iter().filter_map(classify).collect())?
        };
        // `limit == 0` means unlimited; otherwise keep the first N in ts-desc order — identical to
        // the sequential early-break, which stopped after N matches in that same order.
        // Matches are newest-first with stable session/sequence tie-breakers, so `offset` skips
        // that many before `limit` takes: this is the page the caller asked for, not a different
        // sort. Honors `MessageFilters::offset`, which this function previously accepted and
        // silently ignored -- the failure mode that returns success.
        if filters.offset > 0 {
            out.drain(..filters.offset.min(out.len()));
        }
        if filters.limit > 0 {
            out.truncate(filters.limit);
        }
        Ok(out)
    }

    /// Aggregate slash-command frequency: count, distinct sessions, distinct projects
    /// (session repo_root, falling back to cwd). Sorted by count desc then command.
    /// Count slash-command usage. When `command_filters` is non-empty, only commands whose
    /// token matches one of the (already-compiled) patterns are counted; empty = count all.
    pub fn planning_usage(
        &self,
        filters: &MessageFilters,
        command_filters: &[regex::Regex],
    ) -> Result<Vec<PlanningCount>> {
        use rusqlite::types::Value;
        use std::collections::{HashMap, HashSet};

        self.validate_access_scope()?;
        let mut sql = String::from(
            "select m.session_id, s.repo_root, s.cwd, m.content from messages m \
             join sessions s on s.id = m.session_id where 1 = 1",
        );
        let mut args: Vec<Value> = Vec::new();
        let mut filters = filters.clone();
        filters.role = Some(Role::Slash);
        append_message_filters(&mut sql, &mut args, &filters, &self.access_scope);

        let mut stmt = self.conn.prepare(&sql)?;
        let raw = stmt.query_map(rusqlite::params_from_iter(args.iter()), |row| {
            Ok((
                row.get::<_, String>(0)?,
                row.get::<_, Option<String>>(1)?,
                row.get::<_, Option<String>>(2)?,
                row.get::<_, String>(3)?,
            ))
        })?;

        // command -> (count, distinct sessions, distinct projects)
        let mut agg: HashMap<String, (i64, HashSet<String>, HashSet<String>)> = HashMap::new();
        for row in raw {
            let (session_id, repo_root, cwd, content) = row?;
            if let Some(command) = crate::util::slash_command_token(&content) {
                if !command_filters.is_empty()
                    && !command_filters.iter().any(|re| re.is_match(&command))
                {
                    continue;
                }
                let project = repo_root.or(cwd).unwrap_or_default();
                let entry = agg.entry(command).or_default();
                entry.0 += 1;
                entry.1.insert(session_id);
                if !project.is_empty() {
                    entry.2.insert(project);
                }
            }
        }
        let mut counts: Vec<PlanningCount> = agg
            .into_iter()
            .map(|(command, (count, sessions, projects))| PlanningCount {
                command,
                count,
                unique_sessions: sessions.len() as i64,
                unique_projects: projects.len() as i64,
            })
            .collect();
        counts.sort_by(|a, b| {
            b.count
                .cmp(&a.count)
                .then_with(|| a.command.cmp(&b.command))
        });
        if filters.limit > 0 {
            counts.truncate(filters.limit);
        }
        Ok(counts)
    }

    /// Aggregate file-edit activity per file (`files search`). Honors an optional glob
    /// `pattern`, session scope, date window, and min/max edit-count thresholds.
    pub fn file_search(&self, query: &FileQuery) -> Result<Vec<FileEditSummary>> {
        use rusqlite::types::Value;

        self.validate_access_scope()?;
        let mut sql = String::from(
            "select file_path, file_name, count(*) as edits, \
             count(distinct session_id) as sessions, max(ts) as last_edited \
             from file_edits where 1 = 1",
        );
        let mut args: Vec<Value> = Vec::new();
        if let Some(pattern) = &query.pattern {
            let (col, like) = glob_clause(pattern);
            sql.push_str(&format!(" and {col} like ? escape '\\'"));
            args.push(Value::Text(like));
        }
        push_file_filters(&mut sql, &mut args, query, &self.access_scope);
        push_ts_window(&mut sql, &mut args, "ts", query.since, query.until);
        sql.push_str(" group by file_path");
        let mut having: Vec<&str> = Vec::new();
        if let Some(min) = query.min_edits {
            having.push("count(*) >= ?");
            args.push(Value::Integer(min));
        }
        if let Some(max) = query.max_edits {
            having.push("count(*) <= ?");
            args.push(Value::Integer(max));
        }
        if !having.is_empty() {
            sql.push_str(" having ");
            sql.push_str(&having.join(" and "));
        }
        sql.push_str(" order by edits desc, last_edited desc");
        if query.limit > 0 || query.offset > 0 {
            sql.push_str(" limit ? offset ?");
            args.push(Value::Integer(if query.limit == 0 {
                -1
            } else {
                query.limit as i64
            }));
            args.push(Value::Integer(query.offset as i64));
        }

        let mut stmt = self.conn.prepare(&sql)?;
        let rows = stmt
            .query_map(rusqlite::params_from_iter(args.iter()), |row| {
                Ok(FileEditSummary {
                    file_path: row.get(0)?,
                    file_name: row.get(1)?,
                    edits: row.get(2)?,
                    sessions: row.get(3)?,
                    last_edited: row
                        .get::<_, Option<String>>(4)?
                        .as_deref()
                        .and_then(crate::util::parse_datetime),
                })
            })?
            .collect::<rusqlite::Result<Vec<_>>>()?;
        Ok(rows)
    }

    /// File ↔ session linkage with per-pair edit counts (`files cross-ref`).
    pub fn file_cross_ref(&self, query: &FileQuery) -> Result<Vec<FileCrossRef>> {
        use rusqlite::types::Value;

        self.validate_access_scope()?;
        let mut sql = String::from(
            "select file_path, session_id, provider, count(*) as edits \
             from file_edits where 1 = 1",
        );
        let mut args: Vec<Value> = Vec::new();
        if let Some(pattern) = &query.pattern {
            let (col, like) = glob_clause(pattern);
            sql.push_str(&format!(" and {col} like ? escape '\\'"));
            args.push(Value::Text(like));
        }
        push_file_filters(&mut sql, &mut args, query, &self.access_scope);
        push_ts_window(&mut sql, &mut args, "ts", query.since, query.until);
        sql.push_str(" group by file_path, session_id order by file_path, edits desc");
        if query.limit > 0 || query.offset > 0 {
            sql.push_str(" limit ? offset ?");
            args.push(Value::Integer(if query.limit == 0 {
                -1
            } else {
                query.limit as i64
            }));
            args.push(Value::Integer(query.offset as i64));
        }

        let mut stmt = self.conn.prepare(&sql)?;
        let rows = stmt
            .query_map(rusqlite::params_from_iter(args.iter()), |row| {
                let provider: String = row.get(2)?;
                Ok(FileCrossRef {
                    file_path: row.get(0)?,
                    session_id: row.get(1)?,
                    provider: decode_db_enum(
                        provider,
                        2,
                        "file_edits.provider",
                        Provider::from_db_str,
                    )?,
                    edits: row.get(3)?,
                })
            })?
            .collect::<rusqlite::Result<Vec<_>>>()?;
        Ok(rows)
    }

    /// Ordered raw edits for one file (`files history`/`extract`). Matches by exact
    /// basename, exact path, or path suffix (`%/file`), optionally scoped to an exact session ID.
    /// Results are ordered by `(session_id, seq)` so callers can number versions per
    /// session and replay deltas deterministically.
    pub fn file_edits_for(
        &self,
        file: &str,
        session_id: Option<&str>,
    ) -> Result<Vec<(String, Provider, FileEdit)>> {
        let session_id = session_id
            .map(|id| self.resolve_session_record(id).map(|session| session.id))
            .transpose()?;
        self.file_edits_for_query(
            file,
            &FileQuery {
                session_id,
                ..Default::default()
            },
        )
    }

    pub fn file_edits_for_query(
        &self,
        file: &str,
        query: &FileQuery,
    ) -> Result<Vec<(String, Provider, FileEdit)>> {
        self.file_edits_for_scoped(file, query)
    }

    pub fn file_edits_for_session_id(
        &self,
        file: &str,
        session_id: &str,
    ) -> Result<Vec<(String, Provider, FileEdit)>> {
        self.file_edits_for_scoped(
            file,
            &FileQuery {
                session_id: Some(session_id.to_string()),
                ..Default::default()
            },
        )
    }

    fn file_edits_for_scoped(
        &self,
        file: &str,
        query: &FileQuery,
    ) -> Result<Vec<(String, Provider, FileEdit)>> {
        use rusqlite::types::Value;

        self.validate_access_scope()?;
        let mut sql = String::from(
            "select session_id, provider, seq, ts, tool, file_path, file_name, new_content, edits_json \
             from file_edits where (file_name = ? or file_path = ? or file_path like ?)",
        );
        let mut args: Vec<Value> = vec![
            Value::Text(file.to_string()),
            Value::Text(file.to_string()),
            Value::Text(format!("%/{file}")),
        ];
        push_file_filters(&mut sql, &mut args, query, &self.access_scope);
        sql.push_str(" order by session_id, seq");

        let mut stmt = self.conn.prepare(&sql)?;
        let raw = stmt.query_map(rusqlite::params_from_iter(args.iter()), |row| {
            Ok((
                row.get::<_, String>(0)?,
                row.get::<_, String>(1)?,
                row.get::<_, i64>(2)?,
                row.get::<_, Option<String>>(3)?,
                row.get::<_, String>(4)?,
                row.get::<_, String>(5)?,
                row.get::<_, String>(6)?,
                row.get::<_, Option<String>>(7)?,
                row.get::<_, Option<String>>(8)?,
            ))
        })?;

        let mut out = Vec::new();
        for row in raw {
            let (
                session_id,
                provider,
                seq,
                ts,
                tool,
                file_path,
                file_name,
                new_content,
                edits_json,
            ) = row?;
            // Surface a corrupt/truncated edits_json instead of silently yielding no edits (which
            // would make `files extract` show an edit row with no diffs and no signal).
            let edits: Vec<EditOp> = match edits_json.as_deref() {
                Some(json) => serde_json::from_str(json).with_context(|| {
                    format!("corrupt edits_json for {file_path} in session {session_id}")
                })?,
                None => Vec::new(),
            };
            out.push((
                session_id,
                decode_db_enum(provider, 1, "file_edits.provider", Provider::from_db_str)?,
                FileEdit {
                    seq,
                    ts: ts.as_deref().and_then(crate::util::parse_datetime),
                    tool,
                    file_path,
                    file_name,
                    new_content,
                    edits,
                },
            ));
        }
        Ok(out)
    }

    /// Total persisted file-edit rows. Basis for migration detection and tests.
    pub fn file_edit_count(&self) -> Result<i64> {
        Ok(self
            .conn
            .query_row("select count(*) from file_edits", [], |row| row.get(0))?)
    }

    pub fn list_recent(&self, filters: &SearchFilters) -> Result<Vec<SessionRecord>> {
        self.list_recent_page(filters, 0)
    }

    pub fn list_recent_page(
        &self,
        filters: &SearchFilters,
        offset: usize,
    ) -> Result<Vec<SessionRecord>> {
        self.validate_access_scope()?;
        let mut sql = format!(
            "select {} from sessions s where 1 = 1",
            session_record_columns!()
        );
        let mut params_vec = Vec::new();
        push_session_filters(&mut sql, &mut params_vec, filters, &self.access_scope);
        use std::fmt::Write as _;
        sql.push_str(" order by s.updated_at desc, s.id asc");
        if filters.limit != 0 {
            write!(sql, " limit {}", filters.limit)?;
            if offset != 0 {
                write!(sql, " offset {offset}")?;
            }
        } else if offset != 0 {
            write!(sql, " limit -1 offset {offset}")?;
        }

        let mut stmt = self.conn.prepare(&sql)?;
        let rows = stmt.query_map(
            rusqlite::params_from_iter(params_vec.iter()),
            row_to_session_record,
        )?;
        let mut results = Vec::new();
        for row in rows {
            results.push(row?);
        }
        Ok(results)
    }

    pub(crate) fn analysis_documents(
        &self,
        filters: &SearchFilters,
        cursor: Option<&crate::models::AnalysisCursor>,
    ) -> Result<crate::models::AnalysisDocumentPage> {
        self.validate_access_scope()?;
        if filters.limit == 0 {
            return Err(anyhow!(
                "analysis document page limit must be greater than zero"
            ));
        }
        // Keep session metadata and all per-session message reads on one SQLite snapshot.
        // The read-only transaction rolls back via RAII on every return/error path.
        let transaction = self.conn.unchecked_transaction()?;
        analysis_document_page(
            &transaction,
            filters,
            cursor,
            filters.limit,
            &self.access_scope,
        )
    }

    /// Visit each matching session's metadata and attributable human-authored original text as an
    /// ordered row stream, in bounded keyset pages under one read snapshot. Message text is never
    /// concatenated or retained here, so a single session's aggregate human text no longer bounds
    /// memory. [`AnalysisRequest`] owns population selection independently of the in-memory page
    /// size. A successful visitor may inspect only a prefix of a session's message stream; this
    /// owner drains the remainder so the returned corpus digest always covers every selected human
    /// message or human-authored region of a mixed message.
    pub(crate) fn visit_analysis_sessions(
        &self,
        request: &AnalysisRequest,
        session_batch_size: std::num::NonZeroUsize,
        mut visitor: impl FnMut(
            crate::models::SessionRecord,
            i64,
            i64,
            &mut dyn Iterator<Item = Result<(i64, String)>>,
        ) -> Result<()>,
    ) -> Result<AnalysisTraversalReceipt> {
        self.validate_access_scope()?;
        let transaction = self.conn.unchecked_transaction()?;
        let mut count_stmt = transaction.prepare(ANALYSIS_MESSAGE_COUNTS_SQL)?;
        let mut human_message_stmt =
            transaction.prepare(ANALYSIS_ATTRIBUTABLE_HUMAN_MESSAGES_SQL)?;
        let mut cursor = None;
        let mut selected_sessions = 0_u64;
        let mut messages_in_selected_sessions = 0_u64;
        let mut analyzed_user_messages = 0_u64;
        let mut has_more = false;
        let mut last_selected_session_id = None;
        let mut max_selected_session_updated_at = None;
        let mut corpus_digest = FramedSha256::new(b"aise-analysis-corpus-v1");
        loop {
            let remaining = match request.selection().max_sessions() {
                None => usize::MAX,
                Some(max_sessions) => max_sessions
                    .get()
                    .saturating_sub(selected_sessions.try_into().unwrap_or(usize::MAX)),
            };
            if remaining == 0 {
                break;
            }
            let limit = session_batch_size.get().min(remaining);
            let (sessions, next_cursor) = analysis_session_page(
                &transaction,
                request.scope(),
                cursor.as_ref(),
                limit,
                &self.access_scope,
            )?;
            if sessions.is_empty() {
                if next_cursor.is_some() {
                    // A pagination cursor with an empty page is a contradiction in
                    // analysis_session_page's own bookkeeping, not a data/environment problem —
                    // reindexing would not fix it. Point at filing a bug instead of a data-repair
                    // command that would not address the actual cause.
                    bail!(
                        "internal error: an analysis page returned a pagination cursor but no \
                         documents; this indicates a bug in aise's pagination logic — please \
                         file an issue at https://github.com/ahundt/ai-session-search/issues \
                         with the filters/query that triggered it, or send a pull request fixing \
                         analysis_session_page's cursor logic in db.rs"
                    );
                }
                break;
            }
            let page_len = sessions.len();
            for session in sessions {
                let (message_count, human_message_count) = count_stmt
                    .query_row([&session.id], |row| {
                        Ok((row.get::<_, i64>(0)?, row.get::<_, i64>(1)?))
                    })?;
                corpus_digest.update_u8(0);
                corpus_digest.update_json(&session)?;
                corpus_digest.update_i64(message_count);
                corpus_digest.update_i64(human_message_count);
                messages_in_selected_sessions = messages_in_selected_sessions
                    .checked_add(u64::try_from(message_count)?)
                    .ok_or_else(|| anyhow!("analysis total message count overflow"))?;
                analyzed_user_messages = analyzed_user_messages
                    .checked_add(u64::try_from(human_message_count)?)
                    .ok_or_else(|| anyhow!("analysis human-authored message count overflow"))?;
                last_selected_session_id = Some(session.id.clone());
                if let Some(updated_at) = session.updated_at.or(session.created_at) {
                    max_selected_session_updated_at = Some(
                        max_selected_session_updated_at
                            .map_or(updated_at, |current: DateTime<Utc>| current.max(updated_at)),
                    );
                }
                let session_id = session.id.clone();
                let mut rows = human_message_stmt
                    .query_map([&session.id], |row| {
                        Ok((row.get::<_, i64>(0)?, row.get::<_, String>(1)?))
                    })?
                    .map(|row| {
                        let (seq, content) = row.map_err(anyhow::Error::from)?;
                        corpus_digest.update_u8(1);
                        corpus_digest.update_bytes(session_id.as_bytes());
                        corpus_digest.update_i64(seq);
                        corpus_digest.update_bytes(content.as_bytes());
                        Ok((seq, content))
                    });
                visitor(session, message_count, human_message_count, &mut rows)?;
                for unread in rows {
                    unread?;
                }
            }
            selected_sessions = selected_sessions
                .checked_add(page_len as u64)
                .ok_or_else(|| anyhow!("analysis document count overflow"))?;
            if request
                .selection()
                .max_sessions()
                .is_some_and(|maximum| selected_sessions >= maximum.get() as u64)
            {
                has_more = next_cursor.is_some();
                break;
            }
            let Some(next_cursor) = next_cursor else {
                break;
            };
            if cursor
                .as_ref()
                .is_some_and(|previous: &crate::models::AnalysisCursor| {
                    previous.as_str() >= next_cursor.as_str()
                })
            {
                // Same reasoning as the empty-page case above: a non-advancing cursor is an
                // internal pagination bug, not a data problem.
                bail!(
                    "internal error: analysis pagination did not advance to a new cursor; this \
                     indicates a bug in aise's pagination logic — please file an issue at \
                     https://github.com/ahundt/ai-session-search/issues with the filters/query \
                     that triggered it, or send a pull request fixing analysis_session_page's \
                     cursor logic in db.rs"
                );
            }
            cursor = Some(next_cursor);
        }
        Ok(AnalysisTraversalReceipt {
            selected_sessions,
            messages_in_selected_sessions,
            analyzed_user_messages,
            has_more,
            last_selected_session_id,
            max_selected_session_updated_at,
            corpus_digest: corpus_digest.finish(),
        })
    }

    pub fn search(
        &self,
        query: &str,
        filters: &SearchFilters,
        current_repo: Option<&str>,
        scoring: &crate::config::ScoringConfig,
    ) -> Result<Vec<SearchHit>> {
        self.search_with_cancellation(query, filters, current_repo, scoring, None)
    }

    pub(crate) fn search_cancellable(
        &self,
        query: &str,
        filters: &SearchFilters,
        current_repo: Option<&str>,
        scoring: &crate::config::ScoringConfig,
        cancellation: &QueryCancellation,
    ) -> Result<Vec<SearchHit>> {
        self.search_with_cancellation(query, filters, current_repo, scoring, Some(cancellation))
    }

    fn search_with_cancellation(
        &self,
        query: &str,
        filters: &SearchFilters,
        current_repo: Option<&str>,
        scoring: &crate::config::ScoringConfig,
        cancellation: Option<&QueryCancellation>,
    ) -> Result<Vec<SearchHit>> {
        self.validate_access_scope()?;
        if let Some(cancellation) = cancellation {
            cancellation.ensure_active()?;
        }
        let query_lower = fold_caseless(query);
        let tokens: Vec<&str> = query_lower.split_whitespace().collect();
        let query_needle = UnicodeLowerNeedle::from_lowered(&query_lower);
        let token_needles = tokens
            .iter()
            .map(|token| UnicodeLowerNeedle::from_lowered(token))
            .collect::<Vec<_>>();
        let context = SessionScoreContext {
            query,
            query_needle: &query_needle,
            tokens: &tokens,
            token_needles: &token_needles,
            current_repo,
            scoring,
            cancellation,
            now: Utc::now(),
        };
        let mut hits = Vec::new();
        let ranked_limit = filters.limit;
        let mut sql = format!(
            "select {}, coalesce(t.transcript_text, '') as transcript_text
               from sessions s
               left join transcripts t on t.session_id = s.id
              where 1 = 1",
            session_record_columns!()
        );
        let mut params_vec = Vec::new();
        push_session_filters(&mut sql, &mut params_vec, filters, &self.access_scope);
        sql.push_str(" order by s.id asc");
        let mut stmt = self.conn.prepare(&sql)?;
        let candidates = stmt.query_map(
            rusqlite::params_from_iter(params_vec.iter()),
            row_to_session_with_transcript,
        )?;

        let mut batch = Vec::with_capacity(SESSION_SCORE_BATCH_SIZE);
        let mut batch_bytes = 0_usize;
        for record in candidates {
            if let Some(cancellation) = cancellation {
                cancellation.ensure_active()?;
            }
            let record = record?;
            batch_bytes = batch_bytes.saturating_add(session_search_record_bytes(&record));
            batch.push(record);
            if batch.len() == SESSION_SCORE_BATCH_SIZE || batch_bytes >= SESSION_SCORE_BATCH_BYTES {
                let scored = self
                    .runtime
                    .install(|| score_session_records(std::mem::take(&mut batch), &context))??;
                if let Some(cancellation) = cancellation {
                    cancellation.ensure_active()?;
                }
                batch_bytes = 0;
                hits.extend(scored);
                if ranked_limit > 0 && hits.len() >= top_k_compaction_threshold(ranked_limit) {
                    retain_top_session_hits(&mut hits, ranked_limit);
                }
            }
        }
        if !batch.is_empty() {
            hits.extend(
                self.runtime
                    .install(|| score_session_records(batch, &context))??,
            );
        }
        if let Some(cancellation) = cancellation {
            cancellation.ensure_active()?;
        }

        if ranked_limit > 0 {
            retain_top_session_hits(&mut hits, ranked_limit);
        }
        if let Some(cancellation) = cancellation {
            cancellation.ensure_active()?;
        }
        hits.sort_by(compare_session_hits);
        if let Some(cancellation) = cancellation {
            cancellation.ensure_active()?;
        }
        Ok(hits)
    }

    pub fn resolve_session(&self, value: &str) -> Result<SessionWithTranscript> {
        let exact = self.session_resolution_matches(
            RESOLVE_SESSION_EXACT_SQL,
            value,
            row_to_session_with_transcript,
        )?;
        if !exact.is_empty() {
            return unique_session_match(value, exact, |session| &session.session.id);
        }
        let prefix = literal_like_prefix_pattern(value);
        let matches = self.session_resolution_matches(
            RESOLVE_SESSION_PREFIX_SQL,
            &prefix,
            row_to_session_with_transcript,
        )?;
        unique_session_match(value, matches, |session| &session.session.id)
    }

    pub fn resolve_session_record(&self, value: &str) -> Result<SessionRecord> {
        let exact = self.session_resolution_matches(
            RESOLVE_SESSION_RECORD_EXACT_SQL,
            value,
            row_to_session_record,
        )?;
        if !exact.is_empty() {
            return unique_session_match(value, exact, |session| &session.id);
        }
        let prefix = literal_like_prefix_pattern(value);
        let matches = self.session_resolution_matches(
            RESOLVE_SESSION_RECORD_PREFIX_SQL,
            &prefix,
            row_to_session_record,
        )?;
        unique_session_match(value, matches, |session| &session.id)
    }

    /// Inspect one session's canonical transcript without cloning the complete TEXT value into
    /// a `String`. The callback's borrow cannot escape the SQLite row, so retained memory is
    /// determined by the caller's output rather than by transcript size. This is the same
    /// transcript authority used by `resolve_session`, CLI `show`, MCP `get_session`, and export.
    pub(crate) fn inspect_session_transcript<T>(
        &self,
        value: &str,
        cancellation: &QueryCancellation,
        inspect: impl FnOnce(&SessionRecord, &str) -> Result<T>,
    ) -> Result<T> {
        self.with_read_snapshot(|| {
            let session = self.resolve_session_record(value)?;
            cancellation.ensure_active()?;
            let mut statement = self.conn.prepare(
                "select coalesce(transcript_text, '') from transcripts where session_id = ?1",
            )?;
            let mut rows = statement.query([&session.id])?;
            let transcript = match rows.next()? {
                Some(row) => row.get_ref(0)?.as_str()?,
                None => "",
            };
            cancellation.ensure_active()?;
            let result = inspect(&session, transcript);
            drop(rows);
            drop(statement);
            result
        })
    }

    /// Query one exact or prefix session-resolution stage under the current access authority.
    ///
    /// Exact lookup is attempted first by callers, allowing SQLite to use the canonical-id and
    /// provider-native-id indexes in `O(log S + K)` planner work. Only an exact miss reaches the
    /// prefix query, whose case-insensitive `LIKE` fallback may scan `O(S)`. Returned memory is
    /// `O(K)` candidate records, capped only by the authorized matching corpus.
    fn session_resolution_matches<T>(
        &self,
        base_sql: &str,
        value: &str,
        mapper: fn(&rusqlite::Row<'_>) -> rusqlite::Result<T>,
    ) -> Result<Vec<T>> {
        self.access_scope.validate_stable()?;
        let mut sql = base_sql.to_string();
        let mut args = vec![rusqlite::types::Value::Text(value.to_string())];
        push_access_scope(&mut sql, &mut args, "s.id", &self.access_scope);
        let mut stmt = self.conn.prepare(&sql)?;
        let rows = stmt.query_map(rusqlite::params_from_iter(args.iter()), mapper)?;
        let mut matches = Vec::new();
        for row in rows {
            matches.push(row?);
        }
        Ok(matches)
    }

    pub fn count_parse_warnings(&self) -> Result<i64> {
        self.conn
            .query_row(
                "select count(*) from sessions where parse_warning is not null and parse_warning != ''",
                [],
                |row| row.get(0),
            )
            .map_err(Into::into)
    }

    pub fn parser_health(&self) -> Result<ParserHealth> {
        let schema_version: i64 = self
            .conn
            .query_row("pragma user_version", [], |row| row.get(0))?;
        let mut stmt = self.conn.prepare(
            "select provider, parse_version, count(*) from sessions
             group by provider, parse_version",
        )?;
        let grouped = stmt
            .query_map([], |row| {
                Ok((
                    row.get::<_, String>(0)?,
                    row.get::<_, String>(1)?,
                    row.get::<_, i64>(2)?,
                ))
            })?
            .collect::<rusqlite::Result<Vec<_>>>()?;

        let providers = crate::source::PROVIDERS
            .into_iter()
            .map(|provider| {
                let expected = crate::util::provider_parse_version(provider);
                let mut indexed_sessions = 0;
                let mut current_sessions = 0;
                for (stored_provider, parse_version, count) in &grouped {
                    if stored_provider == provider.as_str() {
                        indexed_sessions += count;
                        if parse_version == expected {
                            current_sessions += count;
                        }
                    }
                }
                ProviderParserHealth {
                    provider,
                    expected_parse_version: expected.to_string(),
                    indexed_sessions,
                    current_sessions,
                    stale_sessions: indexed_sessions - current_sessions,
                }
            })
            .collect::<Vec<_>>();
        let indexed_sessions = providers.iter().map(|item| item.indexed_sessions).sum();
        let current_sessions = providers.iter().map(|item| item.current_sessions).sum();

        Ok(ParserHealth {
            schema_version,
            expected_schema_version: SCHEMA_VERSION,
            schema_current: schema_version == SCHEMA_VERSION,
            indexed_sessions,
            current_sessions,
            stale_sessions: indexed_sessions - current_sessions,
            parse_warnings: self.count_parse_warnings()?,
            providers,
        })
    }

    pub(crate) fn stale_session_sources(&self) -> Result<Vec<(Provider, String)>> {
        let mut stmt = self
            .conn
            .prepare("select provider, parse_version, source_path from sessions")?;
        let rows = stmt
            .query_map([], |row| {
                Ok((
                    row.get::<_, String>(0)?,
                    row.get::<_, String>(1)?,
                    row.get::<_, String>(2)?,
                ))
            })?
            .collect::<rusqlite::Result<Vec<_>>>()?;
        rows.into_iter()
            .filter_map(|(provider, parse_version, source_path)| {
                let provider =
                    match decode_db_enum(provider, 0, "sessions.provider", Provider::from_db_str) {
                        Ok(provider) => provider,
                        Err(error) => return Some(Err(error.into())),
                    };
                (parse_version != crate::util::provider_parse_version(provider))
                    .then_some(Ok((provider, source_path)))
            })
            .collect()
    }

    pub fn session_time_profile(&self, session_id: &str) -> Result<SessionTimeProfile> {
        use rusqlite::types::Value;

        self.validate_access_scope()?;
        let mut sql = String::from(
            "with ordered as (
                 select ts, kind, lag(ts) over (order by seq) as previous_ts
                 from messages where session_id = ?",
        );
        let mut args = vec![Value::Text(session_id.to_string())];
        push_access_scope(&mut sql, &mut args, "session_id", &self.access_scope);
        sql.push_str(
            ") select count(*), count(ts), min(ts), max(ts),
                    max(case when previous_ts is null or ts is null then null
                             else unixepoch(ts) - unixepoch(previous_ts) end),
                    coalesce(sum(kind = 'tool_call'), 0),
                    coalesce(sum(kind = 'tool_result'), 0)
               from ordered",
        );
        let row = self
            .conn
            .query_row(&sql, rusqlite::params_from_iter(args.iter()), |row| {
                Ok((
                    row.get::<_, i64>(0)?,
                    row.get::<_, i64>(1)?,
                    row.get::<_, Option<String>>(2)?,
                    row.get::<_, Option<String>>(3)?,
                    row.get::<_, Option<i64>>(4)?,
                    row.get::<_, i64>(5)?,
                    row.get::<_, i64>(6)?,
                ))
            })?;
        let parse_ts = |value: Option<String>| {
            value.and_then(|value| {
                chrono::DateTime::parse_from_rfc3339(&value)
                    .ok()
                    .map(|timestamp| timestamp.with_timezone(&Utc))
            })
        };
        let first_timestamp = parse_ts(row.2);
        let last_timestamp = parse_ts(row.3);
        Ok(SessionTimeProfile {
            messages: row.0,
            timestamped_messages: row.1,
            undated_messages: row.0 - row.1,
            observed_span_seconds: first_timestamp
                .zip(last_timestamp)
                .map(|(first, last)| (last - first).num_seconds()),
            first_timestamp,
            last_timestamp,
            max_message_gap_seconds: row.4,
            tool_calls: row.5,
            tool_results: row.6,
        })
    }

    pub fn counts_by_provider(&self) -> Result<HashMap<String, i64>> {
        let mut stmt = self
            .conn
            .prepare("select provider, count(*) from sessions group by provider")?;
        let rows = stmt.query_map([], |row| {
            Ok((row.get::<_, String>(0)?, row.get::<_, i64>(1)?))
        })?;
        let mut out = HashMap::new();
        for row in rows {
            let (provider, count) = row?;
            out.insert(provider, count);
        }
        Ok(out)
    }
}

const ANALYSIS_MESSAGE_COUNTS_SQL: &str = "select count(*),
            coalesce(sum(
                case
                    when m.record_relation = 'original'
                     and (
                        m.authorship = 'human'
                        or (
                            m.authorship = 'mixed'
                            and exists (
                                select 1
                                from message_content_parts p
                                where p.message_id = m.id and p.authorship = 'human'
                            )
                        )
                     )
                    then 1
                    else 0
                end
            ), 0)
     from messages m
     where m.session_id = ?1";

/// One ordered text row per original message with attributable human-authored content.
///
/// SQLite `substr` counts Unicode code points, matching the persisted Unicode-scalar part
/// coordinates. The ordered compound subquery concatenates only human parts before grouping, so
/// generated/tool/harness regions never cross into the analysis process. Both message branches
/// use `idx_messages_session_authorship_relation_seq`; part lookup uses the table primary key.
///
/// Let `M` be candidate messages and `P_h` selected human parts. Time is `O(log M + M + P_h)` plus
/// emitted text bytes, and retained SQLite state is bounded by one session's selected part rows.
const ANALYSIS_ATTRIBUTABLE_HUMAN_MESSAGES_SQL: &str = "select seq, group_concat(fragment, '')
     from (
         select m.id as message_id, m.seq as seq, -1 as ordinal, m.content as fragment
         from messages m
         where m.session_id = ?1
           and m.authorship = 'human'
           and m.record_relation = 'original'
         union all
         select m.id as message_id, m.seq as seq, p.ordinal as ordinal,
                substr(m.content, p.start_char + 1, p.end_char - p.start_char) as fragment
         from messages m
         join message_content_parts p on p.message_id = m.id
         where m.session_id = ?1
           and m.authorship = 'mixed'
           and m.record_relation = 'original'
           and p.authorship = 'human'
         order by seq, message_id, ordinal
     )
     group by message_id, seq
     order by seq";

/// One keyset page of matching session records, ordered by canonical session ID.
fn analysis_session_page(
    transaction: &rusqlite::Transaction<'_>,
    filters: &SearchFilters,
    cursor: Option<&crate::models::AnalysisCursor>,
    page_limit: usize,
    access: &crate::search_scope::EffectiveAccessScope,
) -> Result<(Vec<SessionRecord>, Option<crate::models::AnalysisCursor>)> {
    use crate::models::AnalysisCursor;
    use std::fmt::Write as _;

    if page_limit == 0 {
        bail!("analysis document page limit must be greater than zero");
    }
    let fetch_limit = page_limit
        .checked_add(1)
        .ok_or_else(|| anyhow!("analysis document page limit is too large"))?;
    let mut sql = format!(
        "select {} from sessions s where 1 = 1",
        session_record_columns!()
    );
    let mut params_vec = Vec::new();
    push_session_filters(&mut sql, &mut params_vec, filters, access);
    if let Some(cursor) = cursor {
        sql.push_str(" and s.id > ? ");
        params_vec.push(cursor.as_str().to_string());
    }
    write!(sql, " order by s.id asc limit {fetch_limit}")?;

    let mut session_stmt = transaction.prepare(&sql)?;
    let session_rows = session_stmt.query_map(
        rusqlite::params_from_iter(params_vec.iter()),
        row_to_session_record,
    )?;
    let mut sessions = Vec::new();
    for row in session_rows {
        sessions.push(row?);
    }
    let has_more = sessions.len() > page_limit;
    sessions.truncate(page_limit);
    let next_cursor = has_more
        .then(|| sessions.last().map(|session| session.id.clone()))
        .flatten()
        .map(AnalysisCursor::after);
    Ok((sessions, next_cursor))
}

fn analysis_document_page(
    transaction: &rusqlite::Transaction<'_>,
    filters: &SearchFilters,
    cursor: Option<&crate::models::AnalysisCursor>,
    page_limit: usize,
    access: &crate::search_scope::EffectiveAccessScope,
) -> Result<crate::models::AnalysisDocumentPage> {
    use crate::models::{AnalysisDocument, AnalysisDocumentPage};

    let (sessions, next_cursor) =
        analysis_session_page(transaction, filters, cursor, page_limit, access)?;
    let mut count_stmt = transaction.prepare(ANALYSIS_MESSAGE_COUNTS_SQL)?;
    let mut human_message_stmt = transaction.prepare(ANALYSIS_ATTRIBUTABLE_HUMAN_MESSAGES_SQL)?;
    let mut documents = Vec::with_capacity(sessions.len());
    for session in sessions {
        let (message_count, human_message_count) = count_stmt.query_row([&session.id], |row| {
            Ok((row.get::<_, i64>(0)?, row.get::<_, i64>(1)?))
        })?;
        let rows = human_message_stmt.query_map([&session.id], |row| {
            Ok((row.get::<_, i64>(0)?, row.get::<_, String>(1)?))
        })?;
        let mut user_text = String::new();
        let mut first_user_text = None;
        for row in rows {
            let (_seq, content) = row?;
            if first_user_text.is_none() {
                first_user_text = Some(content.clone());
            }
            if !user_text.is_empty() {
                user_text.push(' ');
            }
            user_text.push_str(&content);
        }
        documents.push(AnalysisDocument {
            session,
            user_text,
            first_user_text,
            message_count,
            user_message_count: human_message_count,
        });
    }
    Ok(AnalysisDocumentPage {
        documents,
        next_cursor,
    })
}

fn push_session_filters(
    sql: &mut String,
    params_vec: &mut Vec<String>,
    filters: &SearchFilters,
    access: &crate::search_scope::EffectiveAccessScope,
) {
    if let Some(provider) = filters.provider {
        sql.push_str(" and s.provider = ? ");
        params_vec.push(provider.as_str().to_string());
    }
    if let Some(path_prefix) = &filters.path_prefix {
        push_session_path_prefix(sql, params_vec, path_prefix);
    }
    push_session_access_scope(sql, params_vec, access);
    push_session_exclusions(sql, params_vec, filters);
    push_session_kinds(sql, filters);
    if let Some(parent_session_id) = &filters.parent_session_id {
        sql.push_str(" and s.parent_session_id = ? ");
        params_vec.push(parent_session_id.clone());
    }
    push_session_time_window(sql, params_vec, filters.since, filters.until);
    if filters.warnings_only {
        sql.push_str(" and s.parse_warning is not null and s.parse_warning != '' ");
    }
}

/// RFC3339 text for an inclusive UPPER date bound. `dates.rs` already expands imprecise calendar,
/// hour, and minute periods to the final nanosecond while preserving explicit RFC3339 instants.
/// Always rendering nine fractional digits makes lexicographic SQLite comparison agree with
/// chronological order and preserves an exact fractional bound for race reconstruction.
fn until_bound_text(until: chrono::DateTime<Utc>) -> String {
    until.to_rfc3339_opts(chrono::SecondsFormat::Nanos, false)
}

/// Least string ordering after every string that starts with `prefix`, so `term >= prefix and
/// term < bound` selects exactly the terms extending it. UTF-8 bytes sort in code-point order in
/// both SQLite's BINARY collation and Rust, so the two agree on the range.
///
/// Returns None when the prefix is one or more `char::MAX` and no greater string exists; the
/// caller then applies the lower bound alone, which is still exact because nothing sorts after it.
/// Prefer this over `glob 'prefix*'`, which reads `*`, `?`, and `[` in the prefix as wildcards.
fn prefix_upper_bound(prefix: &str) -> Option<String> {
    let mut head = prefix.to_string();
    while let Some(last) = head.pop() {
        // 0xD800..=0xDFFF are UTF-16 surrogates rather than scalar values, so step over the block.
        let next = match u32::from(last) + 1 {
            0xD800 => 0xE000,
            code => code,
        };
        if let Some(next) = char::from_u32(next) {
            head.push(next);
            return Some(head);
        }
    }
    None
}

/// Append the `path_prefix` predicate — restrict rows to sessions rooted at the prefix — onto a
/// query whose rows expose `session_id` as `id_col` (e.g. `m.session_id` or a bare `session_id`).
/// The `sessions` table is tiny relative to messages/file edits, so a subquery is cheap and needs
/// no dedicated index. Mirrors the session-level `path_prefix` semantics in `list_recent`/`search`
/// (exact directory or a child path, with LIKE metacharacters escaped) so `--path` behaves
/// identically across session, message, analytics, and file surfaces. No-op when `path_prefix` is
/// None.
fn push_path_prefix(
    sql: &mut String,
    args: &mut Vec<rusqlite::types::Value>,
    id_col: &str,
    path_prefix: Option<&str>,
) {
    use std::fmt::Write as _;
    if let Some(prefix) = path_prefix {
        let _ = write!(sql, " and {id_col} in (select id from sessions where ");
        push_path_condition(sql, args, prefix);
        sql.push(')');
    }
}

fn push_path_condition(sql: &mut String, args: &mut Vec<rusqlite::types::Value>, prefix: &str) {
    use rusqlite::types::Value;
    sql.push_str(
        "(coalesce(cwd, '') = ? or coalesce(cwd, '') like ? escape '\\' \
          or coalesce(repo_root, '') = ? or coalesce(repo_root, '') like ? escape '\\' \
          or coalesce(source_path, '') = ? or coalesce(source_path, '') like ? escape '\\')",
    );
    let (exact, child_pattern) = path_prefix_patterns(prefix);
    args.push(Value::Text(exact.clone()));
    args.push(Value::Text(child_pattern.clone()));
    args.push(Value::Text(exact.clone()));
    args.push(Value::Text(child_pattern.clone()));
    args.push(Value::Text(exact));
    args.push(Value::Text(child_pattern));
}

#[derive(Clone, Copy)]
enum SessionPathDomain {
    Workspace,
    Transcript,
}

fn push_domain_path_prefix(
    sql: &mut String,
    args: &mut Vec<rusqlite::types::Value>,
    id_col: &str,
    prefix: Option<&str>,
    domain: SessionPathDomain,
) {
    use std::fmt::Write as _;
    if let Some(prefix) = prefix {
        let _ = write!(sql, " and {id_col} in (select id from sessions where ");
        push_domain_path_condition(sql, args, prefix, domain);
        sql.push(')');
    }
}

fn push_domain_path_condition(
    sql: &mut String,
    args: &mut Vec<rusqlite::types::Value>,
    prefix: &str,
    domain: SessionPathDomain,
) {
    use rusqlite::types::Value;
    let (exact, child_pattern) = path_prefix_patterns(prefix);
    match domain {
        SessionPathDomain::Workspace => {
            sql.push_str(
                "(coalesce(cwd, '') = ? or coalesce(cwd, '') like ? escape '\\' \
                  or coalesce(repo_root, '') = ? or coalesce(repo_root, '') like ? escape '\\')",
            );
            args.push(Value::Text(exact.clone()));
            args.push(Value::Text(child_pattern.clone()));
            args.push(Value::Text(exact));
            args.push(Value::Text(child_pattern));
        }
        SessionPathDomain::Transcript => {
            sql.push_str(
                "(coalesce(source_path, '') = ? or coalesce(source_path, '') like ? escape '\\')",
            );
            args.push(Value::Text(exact));
            args.push(Value::Text(child_pattern));
        }
    }
}

fn push_access_scope(
    sql: &mut String,
    args: &mut Vec<rusqlite::types::Value>,
    id_col: &str,
    access: &crate::search_scope::EffectiveAccessScope,
) {
    use std::fmt::Write as _;
    let prefixes: Vec<&str> = access.workspace_prefixes().collect();
    if prefixes.is_empty() {
        return;
    }
    let _ = write!(sql, " and {id_col} in (select id from sessions where ");
    for (index, prefix) in prefixes.into_iter().enumerate() {
        if index > 0 {
            sql.push_str(" or ");
        }
        push_domain_path_condition(sql, args, prefix, SessionPathDomain::Workspace);
    }
    sql.push(')');
}

fn push_session_access_scope(
    sql: &mut String,
    args: &mut Vec<String>,
    access: &crate::search_scope::EffectiveAccessScope,
) {
    let prefixes: Vec<&str> = access.workspace_prefixes().collect();
    if prefixes.is_empty() {
        return;
    }
    sql.push_str(" and (");
    for (index, prefix) in prefixes.into_iter().enumerate() {
        if index > 0 {
            sql.push_str(" or ");
        }
        let (exact, child_pattern) = path_prefix_patterns(prefix);
        sql.push_str(
            "(coalesce(s.cwd, '') = ? or coalesce(s.cwd, '') like ? escape '\\' \
              or coalesce(s.repo_root, '') = ? or coalesce(s.repo_root, '') like ? escape '\\')",
        );
        args.push(exact.clone());
        args.push(child_pattern.clone());
        args.push(exact);
        args.push(child_pattern);
    }
    sql.push(')');
}

fn push_exclude_domain_path_prefixes(
    sql: &mut String,
    args: &mut Vec<rusqlite::types::Value>,
    id_col: &str,
    prefixes: &[String],
    domain: SessionPathDomain,
) {
    use std::fmt::Write as _;
    if prefixes.is_empty() {
        return;
    }
    let _ = write!(sql, " and {id_col} not in (select id from sessions where ");
    for (index, prefix) in prefixes.iter().enumerate() {
        if index > 0 {
            sql.push_str(" or ");
        }
        push_domain_path_condition(sql, args, prefix, domain);
    }
    sql.push(')');
}

fn push_exclude_path_prefixes(
    sql: &mut String,
    args: &mut Vec<rusqlite::types::Value>,
    id_col: &str,
    prefixes: &[String],
) {
    use std::fmt::Write as _;
    if prefixes.is_empty() {
        return;
    }
    let _ = write!(sql, " and {id_col} not in (select id from sessions where ");
    for (i, prefix) in prefixes.iter().enumerate() {
        if i > 0 {
            sql.push_str(" or ");
        }
        push_path_condition(sql, args, prefix);
    }
    sql.push(')');
}

/// Append the structural message predicates shared by [`Db::search_messages`] and
/// [`Db::explain_message_search`] — role, provider, session, tool name, the date
/// window, and the compaction filter — all ANDed onto an existing WHERE using the
/// `m` table alias. Centralizing this guarantees the `explain` candidate count is
/// computed over exactly the rows `search_messages` scans (no filter drift between
/// the two as filters are added).
/// Which message-class clause [`append_message_filters_with_class`] emits. Every search and
/// count uses [`Self::FromFilters`]; the two other selections exist only so the receipt's corpus
/// count can be written as `count(unrestricted) - count(only the excluded classes)`, both halves
/// of which existing indexes answer without reading message rows.
#[derive(Debug, Clone, Copy)]
enum ClassSelection<'a> {
    /// The class predicate the filters resolve to ([`MessageFilters::kind_predicate`]).
    FromFilters,
    /// No class clause at all: every stored `kind`, known to this build or not.
    Unrestricted,
    /// Exactly these classes (`kind in (...)`).
    Only(&'a [crate::models::MessageKind]),
}

fn append_message_filters(
    sql: &mut String,
    args: &mut Vec<rusqlite::types::Value>,
    filters: &MessageFilters,
    access: &crate::search_scope::EffectiveAccessScope,
) {
    append_message_filters_with_class(sql, args, filters, access, ClassSelection::FromFilters);
}

fn append_message_filters_with_class(
    sql: &mut String,
    args: &mut Vec<rusqlite::types::Value>,
    filters: &MessageFilters,
    access: &crate::search_scope::EffectiveAccessScope,
    class: ClassSelection<'_>,
) {
    use rusqlite::types::Value;
    if let Some(role) = filters.role {
        sql.push_str(" and m.role = ?");
        args.push(Value::Text(role.as_str().to_string()));
    }
    // One clause decides which classes come back. `kinds` and `no_compaction` are resolved
    // into a single set first, so no combination can both select and exclude a class.
    //
    // PATTERN: do not add a second class predicate here. A `kind != 'harness_notice'` clause
    // was added beside this one and removed: combined with `kind = 'harness_notice'` it
    // produced an always-empty result that reads as "no such messages exist". The removed
    // `is_compaction = 0` clause was the same redundancy, since role Compaction always infers
    // kind Compaction. Class selection changes belong in `MessageFilters::effective_kinds`.
    let predicate = match class {
        ClassSelection::FromFilters => Some(filters.kind_predicate()),
        ClassSelection::Unrestricted => None,
        ClassSelection::Only(kinds) => Some(crate::models::KindPredicate::Only(kinds.to_vec())),
    };
    match predicate {
        None => {}
        Some(crate::models::KindPredicate::AllExcept(excluded)) => {
            for kind in excluded {
                sql.push_str(" and m.kind != ?");
                args.push(Value::Text(kind.as_str().to_string()));
            }
        }
        Some(crate::models::KindPredicate::Only(kinds)) if kinds.is_empty() => {
            // Every named class was removed. Match nothing rather than silently matching all.
            sql.push_str(" and 0");
        }
        Some(crate::models::KindPredicate::Only(kinds)) => {
            sql.push_str(" and m.kind in (");
            for (i, kind) in kinds.iter().enumerate() {
                if i > 0 {
                    sql.push_str(", ");
                }
                sql.push('?');
                args.push(Value::Text(kind.as_str().to_string()));
            }
            sql.push(')');
        }
    }
    if let Some(providers) = &filters.providers {
        if providers.is_empty() {
            sql.push_str(" and 0");
        } else {
            sql.push_str(" and m.provider in (");
            for (index, provider) in providers.iter().enumerate() {
                if index > 0 {
                    sql.push_str(", ");
                }
                sql.push('?');
                args.push(Value::Text(provider.as_str().to_string()));
            }
            sql.push(')');
        }
    }
    if let Some(session_id) = &filters.session_id {
        sql.push_str(" and m.session_id = ?");
        args.push(Value::Text(session_id.clone()));
    }
    push_message_session_kinds(sql, "m.session_id", filters.session_kinds.as_ref());
    push_access_scope(sql, args, "m.session_id", access);
    push_path_prefix(sql, args, "m.session_id", filters.path_prefix.as_deref());
    push_exclude_path_prefixes(sql, args, "m.session_id", &filters.exclude_path_prefixes);
    push_domain_path_prefix(
        sql,
        args,
        "m.session_id",
        filters.workspace_path_prefix.as_deref(),
        SessionPathDomain::Workspace,
    );
    push_domain_path_prefix(
        sql,
        args,
        "m.session_id",
        filters.transcript_path_prefix.as_deref(),
        SessionPathDomain::Transcript,
    );
    push_exclude_domain_path_prefixes(
        sql,
        args,
        "m.session_id",
        &filters.exclude_workspace_path_prefixes,
        SessionPathDomain::Workspace,
    );
    push_exclude_domain_path_prefixes(
        sql,
        args,
        "m.session_id",
        &filters.exclude_transcript_path_prefixes,
        SessionPathDomain::Transcript,
    );
    for session_id in &filters.exclude_session_ids {
        sql.push_str(" and m.session_id <> ?");
        args.push(Value::Text(session_id.clone()));
    }
    if let Some(tool) = &filters.tool {
        // NULL tool_name rows are excluded because the scalar predicate returns false.
        sql.push_str(" and unicode_lower_contains(m.tool_name, ?)");
        args.push(Value::Text(fold_caseless(tool)));
    }
    if let Some(seq_from) = filters.seq_from {
        sql.push_str(" and m.seq >= ?");
        args.push(Value::Integer(seq_from));
    }
    if let Some(seq_to) = filters.seq_to {
        sql.push_str(" and m.seq <= ?");
        args.push(Value::Integer(seq_to));
    }
    push_ts_window(sql, args, "m.ts", filters.since, filters.until);
    // Class selection, including compaction and harness notices, is applied by the single
    // `m.kind in (...)` clause above. `is_compaction` is left unused here because it is
    // redundant with `kind`: role Compaction always infers kind Compaction, so filtering on
    // both would be two sources of truth for one fact.
}

/// Insert message rows and their nonduplicating content-part ranges for `session`.
///
/// Taking each row's `seq` from the caller supports both full upsert parse order and incremental
/// append. Shared by `upsert_session` and `append_tail` so validation, message insertion, part
/// insertion, and correlation binding have one owner. Runtime is `O(M + S)` for `M` messages and
/// `S` parts, with `O(1)` additional memory beyond the parsed input.
fn insert_messages<'a>(
    tx: &rusqlite::Transaction<'_>,
    session: &SessionRecord,
    rows: impl Iterator<Item = (i64, &'a crate::models::Message)>,
) -> Result<()> {
    let mut stmt = tx.prepare(
        "insert into messages
            (session_id, provider, seq, role, ts, tool_name, kind, tool_call_id, is_compaction,
             content, authorship, correlation_authority, correlation_scope, correlation_id,
             record_relation)
         values (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, ?15)",
    )?;
    let mut part_stmt = tx.prepare(
        "insert into message_content_parts
            (message_id, ordinal, start_char, end_char, authorship, origin)
         values (?1, ?2, ?3, ?4, ?5, ?6)",
    )?;
    for (seq, message) in rows {
        if let Err(detail) = message.provenance.validate(&message.content) {
            bail!(
                "invalid provenance for message sequence {seq} in session '{}': {detail}",
                session.id
            );
        }
        let correlation = message.provenance.correlation_identity.as_ref();
        stmt.execute(params![
            session.id,
            session.provider.as_str(),
            seq,
            message.role.as_str(),
            message.ts.map(|ts| ts.to_rfc3339()),
            message.tool_name,
            message.kind.as_str(),
            message.tool_call_id,
            message.is_compaction as i64,
            message.content,
            message.provenance.authorship.as_str(),
            correlation.map(|value| value.authority.as_str()),
            correlation.map(|value| value.scope.as_str()),
            correlation.map(|value| value.id.as_str()),
            message.provenance.record_relation.as_str(),
        ])?;
        let message_id = tx.last_insert_rowid();
        for part in &message.provenance.content_parts {
            part_stmt.execute(params![
                message_id,
                i64::from(part.ordinal),
                i64::try_from(part.start_char).context("content-part start exceeds SQLite i64")?,
                i64::try_from(part.end_char).context("content-part end exceeds SQLite i64")?,
                part.authorship.as_str(),
                part.origin.as_str(),
            ])?;
        }
    }
    Ok(())
}

/// Insert file-edit rows for `session`, with the caller-supplied `seq`. Shared by `upsert_session`
/// and `append_tail`. `edits` serialize to a JSON `[old, new]` array (NULL when empty); the same
/// shape both call sites previously duplicated.
fn insert_file_edits<'a>(
    tx: &rusqlite::Transaction<'_>,
    session: &SessionRecord,
    rows: impl Iterator<Item = (i64, &'a FileEdit)>,
) -> Result<()> {
    let mut stmt = tx.prepare(
        "insert into file_edits
            (session_id, provider, seq, ts, tool, file_path, file_name, new_content, edits_json)
         values (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)",
    )?;
    for (seq, edit) in rows {
        let edits_json = if edit.edits.is_empty() {
            None
        } else {
            Some(serde_json::to_string(&edit.edits)?)
        };
        stmt.execute(params![
            session.id,
            session.provider.as_str(),
            seq,
            edit.ts.map(|ts| ts.to_rfc3339()),
            edit.tool,
            edit.file_path,
            edit.file_name,
            edit.new_content,
            edits_json,
        ])?;
    }
    Ok(())
}

/// Append the inclusive timestamp-window clauses and push their rfc3339 args,
/// centralizing the date filter shared by every time-scoped query (messages,
/// corrections, planning, files). `col` lets callers target `ts` or a table-qualified
/// `m.ts`. Args are pushed since-then-until to match the SQL order. The upper bound
/// preserves the exact resolved endpoint (see [`until_bound_text`]).
/// Unknown (`NULL`) timestamps do not match a date window. Providers/indexing paths
/// that need date-filterable rows must persist a fallback timestamp instead of letting
/// every undated row leak through every date filter.
fn push_ts_window(
    sql: &mut String,
    args: &mut Vec<rusqlite::types::Value>,
    col: &str,
    since: Option<chrono::DateTime<Utc>>,
    until: Option<chrono::DateTime<Utc>>,
) {
    use rusqlite::types::Value;
    use std::fmt::Write as _;
    // `write!` into the existing String avoids a throwaway `format!` allocation; writing to a
    // String is infallible, so the `Result` is discarded.
    if let Some(since) = since {
        let _ = write!(sql, " and {col} >= ?");
        args.push(Value::Text(since.to_rfc3339()));
    }
    if let Some(until) = until {
        let _ = write!(sql, " and {col} <= ?");
        args.push(Value::Text(until_bound_text(until)));
    }
}

fn push_file_filters(
    sql: &mut String,
    args: &mut Vec<rusqlite::types::Value>,
    query: &FileQuery,
    access: &crate::search_scope::EffectiveAccessScope,
) {
    use rusqlite::types::Value;
    if let Some(provider) = query.provider {
        sql.push_str(" and provider = ?");
        args.push(Value::Text(provider.as_str().to_string()));
    }
    if let Some(session_id) = query.session_id.as_deref() {
        sql.push_str(" and session_id = ?");
        args.push(Value::Text(session_id.to_string()));
    }
    push_access_scope(sql, args, "session_id", access);
    push_path_prefix(sql, args, "session_id", query.path_prefix.as_deref());
    push_exclude_path_prefixes(sql, args, "session_id", &query.exclude_path_prefixes);
    for session_id in &query.exclude_session_ids {
        sql.push_str(" and session_id <> ?");
        args.push(Value::Text(session_id.clone()));
    }
}

fn path_prefix_parts(prefix: &str) -> (String, String) {
    let bytes = prefix.as_bytes();
    let windows_style = prefix.starts_with(r"\\")
        || matches!(bytes, [drive, b':', b'\\' | b'/', ..] if drive.is_ascii_alphabetic());
    let separator = if windows_style { '\\' } else { '/' };
    let exact = prefix.trim_end_matches(separator).to_string();
    let child = format!("{exact}{separator}");
    (exact, child)
}

fn path_prefix_patterns(prefix: &str) -> (String, String) {
    let (exact, child) = path_prefix_parts(prefix);
    (exact, literal_like_prefix_pattern(&child))
}

/// Escape a caller-authored literal for a SQLite `LIKE ... ESCAPE '\'` prefix probe.
///
/// Time and returned memory are `O(|value|)`. Centralizing this prevents session IDs and path
/// prefixes containing `%`, `_`, or `\` from accidentally becoming wildcard expressions.
fn literal_like_prefix_pattern(value: &str) -> String {
    let mut escaped = String::with_capacity(value.len() + 2);
    for ch in value.chars() {
        match ch {
            '%' | '_' | '\\' => {
                escaped.push('\\');
                escaped.push(ch);
            }
            other => escaped.push(other),
        }
    }
    escaped.push('%');
    escaped
}

fn push_session_path_prefix(sql: &mut String, args: &mut Vec<String>, path_prefix: &str) {
    let (exact, child_pattern) = path_prefix_patterns(path_prefix);
    sql.push_str(
        " and ((coalesce(s.cwd, '') = ? or coalesce(s.cwd, '') like ? escape '\\') \
         or (coalesce(s.repo_root, '') = ? or coalesce(s.repo_root, '') like ? escape '\\') \
         or (coalesce(s.source_path, '') = ? or coalesce(s.source_path, '') like ? escape '\\')) ",
    );
    args.push(exact.clone());
    args.push(child_pattern.clone());
    args.push(exact.clone());
    args.push(child_pattern.clone());
    args.push(exact);
    args.push(child_pattern);
}

fn push_session_exclusions(sql: &mut String, args: &mut Vec<String>, filters: &SearchFilters) {
    for session_id in &filters.exclude_session_ids {
        sql.push_str(" and s.id <> ? ");
        args.push(session_id.clone());
    }
    for prefix in &filters.exclude_path_prefixes {
        let (exact, child_pattern) = path_prefix_patterns(prefix);
        sql.push_str(
            " and not ((coalesce(s.cwd, '') = ? or coalesce(s.cwd, '') like ? escape '\\') \
             or (coalesce(s.repo_root, '') = ? or coalesce(s.repo_root, '') like ? escape '\\') \
             or (coalesce(s.source_path, '') = ? or coalesce(s.source_path, '') like ? escape '\\')) ",
        );
        args.push(exact.clone());
        args.push(child_pattern.clone());
        args.push(exact.clone());
        args.push(child_pattern.clone());
        args.push(exact);
        args.push(child_pattern);
    }
}

/// Restrict which classes of session come back, ORing each selected class's own predicate.
///
/// PATTERN: one clause decides session class, the way `append_message_filters` has one clause
/// for message class. Do not add a second predicate beside it — a `parent_session_id is null`
/// clause added elsewhere would combine with `session_kinds = [subagent]` into an always-empty
/// result that reads as "no such sessions exist". Class selection belongs in
/// [`SearchFilters::effective_session_kinds`].
///
/// Takes no `args` because [`SessionKind::sql_predicate`] is a fixed null test, not a bound
/// value: the class is derived from `parent_session_id`, never stored as text.
/// The OR-ed class predicate for a session-kind selection over `alias`.
///
/// `None` means every class is selected, so a predicate would be a tautology and the caller
/// should emit nothing. `Some("0")` means the selection is empty: match nothing rather than
/// silently matching all, which is the failure that makes an over-narrowed filter look like an
/// empty database.
///
/// Shared by the `sessions`-rooted query and the message-side subquery so the two cannot drift
/// on what an empty or full selection means.
fn session_kind_predicate(selected: &[crate::models::SessionKind], alias: &str) -> Option<String> {
    if selected.is_empty() {
        return Some("0".to_string());
    }
    if crate::models::SessionKind::all()
        .iter()
        .all(|kind| selected.contains(kind))
    {
        return None;
    }
    let mut predicate = String::from("(");
    for (index, kind) in selected.iter().enumerate() {
        if index > 0 {
            predicate.push_str(" or ");
        }
        predicate.push_str(&kind.sql_predicate(alias));
    }
    predicate.push(')');
    Some(predicate)
}

fn push_session_kinds(sql: &mut String, filters: &SearchFilters) {
    if let Some(predicate) = session_kind_predicate(&filters.effective_session_kinds(), "s") {
        sql.push_str(" and ");
        sql.push_str(&predicate);
        sql.push(' ');
    }
}

/// Restrict messages to sessions of the selected classes, through the same
/// `<id_col> in (select id from sessions where ...)` shape `push_path_prefix` uses.
fn push_message_session_kinds(
    sql: &mut String,
    id_col: &str,
    session_kinds: Option<&Vec<crate::models::SessionKind>>,
) {
    use std::fmt::Write as _;
    let Some(selected) = session_kinds else {
        // None = every class, which is what `messages search` and `list` already return.
        return;
    };
    let Some(predicate) = session_kind_predicate(selected, "sessions") else {
        return;
    };
    if predicate == "0" {
        sql.push_str(" and 0");
        return;
    }
    let _ = write!(
        sql,
        " and {id_col} in (select id from sessions where {predicate})"
    );
}

/// Append closed-interval overlap predicates for a session's known indexed span.
///
/// Let `S` be session rows considered by SQLite. This adds at most two constant-time text
/// comparisons per considered row: `O(S)` worst-case SQL work and `O(1)` application memory.
/// It performs no message join, allocation proportional to `S`, output growth, or database write;
/// ordering, paging, and result retention remain owned by the calling query.
fn push_session_time_window(
    sql: &mut String,
    args: &mut Vec<String>,
    since: Option<chrono::DateTime<Utc>>,
    until: Option<chrono::DateTime<Utc>>,
) {
    if let Some(since) = since {
        sql.push_str(" and coalesce(s.updated_at, s.created_at) >= ? ");
        args.push(since.to_rfc3339());
    }
    if let Some(until) = until {
        sql.push_str(" and coalesce(s.created_at, s.updated_at) <= ? ");
        args.push(until_bound_text(until));
    }
}

fn row_to_message_hit(row: &rusqlite::Row<'_>) -> rusqlite::Result<MessageHit> {
    row_to_message_hit_at(row, 0)
}

fn decode_db_enum<T>(
    value: String,
    column_index: usize,
    context: &'static str,
    decode: impl FnOnce(&str) -> std::result::Result<T, String>,
) -> rusqlite::Result<T> {
    // The recovery advice travels with the decoder's reason: an unknown provider means a newer
    // aise wrote the row and the fix is to upgrade, while an unknown role means corruption and
    // the fix is a full reparse. This wrapper only adds where the value was read. It must not
    // append its own `aise reindex --full` advice: for a provider that is the command that fails
    // the same way, the circular advice a Pi session hit on 2026-08-13.
    decode(&value).map_err(|reason| {
        rusqlite::Error::FromSqlConversionFailure(
            column_index,
            rusqlite::types::Type::Text,
            std::io::Error::new(
                std::io::ErrorKind::InvalidData,
                format!("{reason} (while reading {context})"),
            )
            .into(),
        )
    })
}

fn row_to_message_hit_at(row: &rusqlite::Row<'_>, offset: usize) -> rusqlite::Result<MessageHit> {
    let ts: Option<String> = row.get(offset + 4)?;
    Ok(MessageHit {
        session_id: row.get(offset)?,
        provider: decode_db_enum(
            row.get::<_, String>(offset + 1)?,
            offset + 1,
            "messages.provider",
            Provider::from_db_str,
        )?,
        seq: row.get(offset + 2)?,
        role: decode_db_enum(
            row.get::<_, String>(offset + 3)?,
            offset + 3,
            "messages.role",
            Role::from_db_str,
        )?,
        ts: ts.and_then(|value| {
            chrono::DateTime::parse_from_rfc3339(&value)
                .ok()
                .map(|dt| dt.with_timezone(&Utc))
        }),
        tool_name: row.get(offset + 5)?,
        kind: crate::models::MessageKind::from_db_str(&row.get::<_, String>(offset + 6)?),
        tool_call_id: row.get(offset + 7)?,
        fuzzy_score: None,
        content: row.get(offset + 8)?,
    })
}

/// Convert regex required literals into raw-JSON-safe trigram groups for a projected tool
/// argument.
///
/// A JSON string may escape quotes, backslashes, and control characters, so a trigram spanning
/// any such character is not necessarily present in the stored envelope. Removing those grams
/// preserves the candidate-superset contract; if any regex alternative loses every usable gram,
/// this returns `None` and the caller scans every eligible tool call. Provider-normalized tool
/// envelopes and non-string projections both use `serde_json`'s compact serialization, while
/// string projections remove their surrounding quotes and decode escapes; this is why only the
/// latter representation boundary needs filtering. The projected-value matcher remains final.
///
/// For Q query scalar values and G extracted trigrams, runtime is O(Q + G), peak memory is O(G),
/// and latency is one serial extraction pass. In practice G <= O(Q); no corpus data is read here.
fn json_projection_prefilter_groups(pattern: &str) -> Option<Vec<Vec<String>>> {
    let groups = crate::trigram::trigram_prefilter_groups(pattern)?;
    let groups = groups
        .into_iter()
        .map(|group| {
            group
                .into_iter()
                .filter(|trigram| {
                    trigram.chars().all(|character| {
                        !character.is_control() && !matches!(character, '"' | '\\')
                    })
                })
                .collect::<Vec<_>>()
        })
        .collect::<Vec<_>>();
    (!groups.is_empty() && groups.iter().all(|group| !group.is_empty())).then_some(groups)
}

/// Project and score one derived-field batch in parallel. For raw bytes `B_b`, rows `N_b`, and
/// workers `P`, tool-argument projection plus fuzzy scoring does O(B_b + score(B_b)) aggregate
/// work and ideal O((B_b + score(B_b))/P) scoring latency, excluding serial SQLite traversal and
/// scheduling. Worker-local matcher/buffer state is O(P*Q); output retains only matching rows.
fn score_fuzzy_derived_hits(
    pattern: &Pattern,
    query_lower: &str,
    field: SearchField,
    argument_path: Option<&str>,
    hits: Vec<MessageHit>,
) -> Vec<(MessageHit, bool)> {
    let exact_phrase_needle = UnicodeLowerNeedle::from_lowered(query_lower);
    hits.into_par_iter()
        .map_init(
            || (NucleoMatcher::new(NucleoConfig::DEFAULT), Vec::new()),
            |(matcher, utf32_buf), mut hit| {
                let value = selected_message_field_parts(&hit, field, argument_path)?.into_owned();
                utf32_buf.clear();
                pattern
                    .score(Utf32Str::new(&value, utf32_buf), matcher)
                    .map(|score| {
                        hit.fuzzy_score = Some(score);
                        let exact_phrase = exact_phrase_needle.contains(&value);
                        (hit, exact_phrase)
                    })
            },
        )
        .filter_map(std::convert::identity)
        .collect()
}

fn score_fuzzy_message_hits(
    pattern: &Pattern,
    query_lower: &str,
    hits: Vec<MessageHit>,
) -> Vec<(MessageHit, bool)> {
    let exact_phrase_needle = UnicodeLowerNeedle::from_lowered(query_lower);
    hits.into_par_iter()
        .map_init(
            || (NucleoMatcher::new(NucleoConfig::DEFAULT), Vec::new()),
            |(matcher, utf32_buf), mut hit| {
                let score = {
                    let haystack = Utf32Str::new(&hit.content, utf32_buf);
                    pattern.score(haystack, matcher)
                };
                score.map(|score| {
                    hit.fuzzy_score = Some(score);
                    let exact_phrase = exact_phrase_needle.contains(&hit.content);
                    (hit, exact_phrase)
                })
            },
        )
        .filter_map(std::convert::identity)
        .collect()
}

fn compare_fuzzy_hits(left: &(MessageHit, bool), right: &(MessageHit, bool)) -> std::cmp::Ordering {
    right
        .0
        .fuzzy_score
        .unwrap_or_default()
        .cmp(&left.0.fuzzy_score.unwrap_or_default())
        .then_with(|| right.1.cmp(&left.1))
        .then_with(|| left.0.session_id.cmp(&right.0.session_id))
        .then_with(|| left.0.seq.cmp(&right.0.seq))
}

/// The receipt for a fuzzy page that scored every eligible row.
///
/// `matched` is how many of them the pattern matched and `corpus` how many were eligible. The
/// message names the retention bound [`Db::fuzzy_ranking_window`] enforces, so a reader can tell
/// that a deep page costs scoring time without costing proportional memory.
fn scored_whole_corpus(matched: i64, corpus: i64) -> SearchExplain {
    SearchExplain {
        prefilter: None,
        candidates: Some(matched),
        prefilter_skipped: Some(
            "complete filtered corpus scored, retaining at most min(offset + limit, corpus) ranked rows"
                .to_string(),
        ),
        corpus,
    }
}

/// The receipt for a fuzzy page whose window starts at or past the last eligible row.
///
/// `candidates` counts rows that scored, and none did, so it stays absent rather than reporting a
/// zero that would read as "the corpus was scored and nothing matched". `corpus` is exact: it is
/// the index-only count that decided the page is empty.
fn empty_past_corpus(corpus: i64) -> SearchExplain {
    SearchExplain {
        prefilter: None,
        candidates: None,
        prefilter_skipped: Some(
            "offset starts at or past the last eligible row, so no row was scored".to_string(),
        ),
        corpus,
    }
}

/// The rows a fuzzy derived-field scan visits, as an SQL fragment over alias `m`.
///
/// One owner for the restriction keeps the statement and the bound measured against it in step:
/// [`Db::fuzzy_ranking_window`] takes the same fragment so the corpus it counts is the corpus the
/// scan reads. Tool-argument search restricts itself to tool calls, while the tool-name fallback
/// (schema versions below 4, which have no tool-name vocabulary to search) visits every admitted
/// row and lets scoring skip the ones carrying no tool name.
const fn fuzzy_derived_scan_predicate(field: SearchField) -> &'static str {
    match field {
        SearchField::ToolArgument => "m.kind = 'tool_call'",
        SearchField::ToolName | SearchField::Content => "1 = 1",
    }
}

/// The outcome of sizing a fuzzy page's ranking window against the eligible corpus.
///
/// See [`Db::fuzzy_ranking_window`], which explains why the window is bounded at all.
enum FuzzyRankingWindow {
    /// Score the corpus while retaining at most `limit` ranked candidates. `corpus` carries the
    /// eligible count when sizing the window had to measure it, so a receipt can reuse it instead
    /// of repeating the query.
    Rank { limit: usize, corpus: Option<i64> },
    /// The window starts at or past the last eligible row, so the page is empty whatever the
    /// scores are. `corpus` is the exact eligible count, which the receipt reports in place of a
    /// scored-candidate count that was never measured.
    PastCorpus { corpus: i64 },
}

fn fuzzy_ranked_limit(filters: &MessageFilters) -> Result<usize> {
    filters
        .offset
        .checked_add(filters.limit)
        .ok_or_else(|| anyhow!("fuzzy offset + limit exceeds the platform addressable range"))
}

/// Compact after retained candidates roughly double. This keeps retained row count `O(K)` while
/// making repeated linear selections amortize to `O(N)` rather than rescanning `K` rows every
/// fixed batch. Retained text bytes still scale with the selected rows' content sizes.
fn top_k_compaction_threshold(limit: usize) -> usize {
    limit.saturating_mul(2).max(FUZZY_SCORE_BATCH_SIZE)
}

fn retain_top_fuzzy_hits(scored: &mut Vec<(MessageHit, bool)>, limit: usize) {
    if scored.len() > limit {
        scored.select_nth_unstable_by(limit, compare_fuzzy_hits);
        scored.truncate(limit);
    }
}

fn finish_fuzzy_hits(
    mut scored: Vec<(MessageHit, bool)>,
    ranked_limit: usize,
    offset: usize,
) -> Vec<MessageHit> {
    retain_top_fuzzy_hits(&mut scored, ranked_limit);
    scored.sort_by(compare_fuzzy_hits);
    scored
        .into_iter()
        .skip(offset)
        .map(|(hit, _)| hit)
        .collect()
}

fn session_search_record_bytes(record: &SessionWithTranscript) -> usize {
    record.transcript_text.len()
        + record.session.preview_text.len()
        + record.session.title.as_ref().map_or(0, String::len)
        + record.session.summary.as_ref().map_or(0, String::len)
        + record.session.cwd.as_ref().map_or(0, String::len)
        + record.session.repo_root.as_ref().map_or(0, String::len)
}

struct SessionScoreContext<'a> {
    query: &'a str,
    query_needle: &'a UnicodeLowerNeedle,
    tokens: &'a [&'a str],
    token_needles: &'a [UnicodeLowerNeedle],
    current_repo: Option<&'a str>,
    scoring: &'a crate::config::ScoringConfig,
    cancellation: Option<&'a QueryCancellation>,
    now: DateTime<Utc>,
}

fn session_contains(
    needle: &UnicodeLowerNeedle,
    value: &str,
    cancellation: Option<&QueryCancellation>,
) -> Result<bool> {
    needle
        .contains_while(value, || {
            cancellation.is_none_or(|token| !token.is_cancelled())
        })
        .ok_or_else(|| QueryCancelled.into())
}

fn session_snippet(
    value: &str,
    query: &str,
    cancellation: Option<&QueryCancellation>,
) -> Result<String> {
    match cancellation {
        Some(token) => snippet_from_match_while(value, query, 160, || !token.is_cancelled())
            .ok_or_else(|| QueryCancelled.into()),
        None => Ok(snippet_from_match(value, query, 160)),
    }
}

/// Score one bounded batch independently. For batch bytes `B_b`, rows `N_b`, query tokens `A`,
/// and workers `P`, aggregate work is O(B_b * (A + 1) + N_b); ideal scoring latency is
/// O(B_b * (A + 1) / P + N_b / P), excluding Rayon scheduling. Output memory is O(N_b + D_b)
/// for matching record bytes `D_b`; the caller compacts globally retained top-K results between
/// batches. A single `now` value preserves recency scores across worker counts and batch timing.
fn score_session_records(
    records: Vec<SessionWithTranscript>,
    context: &SessionScoreContext<'_>,
) -> Result<Vec<SearchHit>> {
    let SessionScoreContext {
        query,
        query_needle,
        tokens,
        token_needles,
        current_repo,
        scoring,
        cancellation,
        now,
    } = context;
    records
        .into_par_iter()
        .map(|record| -> Result<Option<SearchHit>> {
            if let Some(cancellation) = cancellation {
                cancellation.ensure_active()?;
            }
            let matcher = SkimMatcherV2::default().smart_case();
            let title = record.session.title.as_deref().unwrap_or_default();
            let summary = record.session.summary.as_deref().unwrap_or_default();
            let cwd = record.session.cwd.as_deref().unwrap_or_default();
            let repo_root = record.session.repo_root.as_deref().unwrap_or_default();
            let preview = record.session.preview_text.as_str();
            let transcript = record.transcript_text.as_str();
            let haystacks = [
                ("title", title),
                ("summary", summary),
                ("cwd", cwd),
                ("repo", repo_root),
                ("preview", preview),
                ("transcript", transcript),
            ];

            let mut score = 0_i64;
            let mut best_source = "fuzzy".to_string();
            let mut best_source_score = i64::MIN;
            let mut best_snippet = session_snippet(preview, query, *cancellation)?;
            let mut term_coverage = vec![false; tokens.len()];
            let mut matched = false;
            for (source, value) in haystacks {
                let mut source_score = 0_i64;
                if session_contains(query_needle, value, *cancellation)? {
                    matched = true;
                    source_score += match source {
                        "title" => scoring.title_score,
                        "summary" => scoring.summary_score,
                        "cwd" | "repo" => scoring.path_score,
                        "preview" => scoring.preview_score,
                        _ => scoring.other_score,
                    };
                }
                for (index, token) in tokens.iter().enumerate() {
                    if !token.is_empty()
                        && session_contains(&token_needles[index], value, *cancellation)?
                    {
                        matched = true;
                        source_score += scoring.token_bonus;
                        term_coverage[index] = true;
                    }
                }
                if matches!(source, "title" | "cwd" | "repo" | "preview") {
                    if let Some(fuzzy_score) = matcher.fuzzy_match(value, query) {
                        matched = true;
                        source_score += fuzzy_score;
                    }
                }
                score += source_score;
                if source_score > best_source_score {
                    best_source_score = source_score;
                    best_source = source.to_string();
                    best_snippet = session_snippet(value, query, *cancellation)?;
                }
            }
            if !matched {
                return Ok(None);
            }
            if tokens.len() > 1 && term_coverage.iter().all(|matched| *matched) {
                score += scoring.all_tokens_bonus;
            }
            if let Some(updated_at) = record.session.updated_at {
                let age_days = (*now - updated_at)
                    .num_days()
                    .clamp(0, scoring.recency_max_days);
                score += (scoring.recency_max_days - age_days) * scoring.recency_weight;
            }
            if let (Some(current_repo), Some(repo_root)) =
                (current_repo, record.session.repo_root.as_deref())
            {
                if *current_repo == repo_root {
                    score += scoring.current_repo_bonus;
                    if best_source == "fuzzy" {
                        best_source = "repo".to_string();
                        best_snippet = snippet_from_match(repo_root, query, 160);
                    }
                }
            }
            Ok(Some(SearchHit {
                session: record.session,
                score,
                match_source: best_source,
                match_snippet: best_snippet,
            }))
        })
        // Transpose before collecting so non-matching rows are dropped inside the parallel
        // fold. Collecting `Vec<Option<SearchHit>>` first and flattening afterwards would size
        // the intermediate by batch rows `N_b` rather than by matches `M_b`, and move every
        // surviving hit a second time.
        .filter_map(|scored| scored.transpose())
        .collect::<Result<Vec<_>>>()
}

fn compare_session_hits(left: &SearchHit, right: &SearchHit) -> std::cmp::Ordering {
    right
        .score
        .cmp(&left.score)
        .then_with(|| right.session.updated_at.cmp(&left.session.updated_at))
        .then_with(|| left.session.id.cmp(&right.session.id))
}

fn retain_top_session_hits(hits: &mut Vec<SearchHit>, limit: usize) {
    if hits.len() > limit {
        hits.select_nth_unstable_by(limit, compare_session_hits);
        hits.truncate(limit);
    }
}

/// Translate a shell-style glob into an `(column, LIKE-pattern)` pair for the
/// `file_edits` table. A pattern without `/` matches the basename (`file_name`);
/// one containing `/` matches anywhere in the absolute `file_path` (leading `%`).
/// `*`→`%`, `?`→`_`; literal `%`/`_`/`\` are backslash-escaped (use `escape '\'`).
fn glob_clause(pattern: &str) -> (&'static str, String) {
    let mut like = String::with_capacity(pattern.len() + 1);
    for ch in pattern.chars() {
        match ch {
            '*' => like.push('%'),
            '?' => like.push('_'),
            '%' | '_' | '\\' => {
                like.push('\\');
                like.push(ch);
            }
            other => like.push(other),
        }
    }
    if pattern.contains('/') {
        ("file_path", format!("%{like}"))
    } else {
        ("file_name", like)
    }
}

const RESOLVE_SESSION_EXACT_SQL: &str = concat!(
    "select ",
    session_record_columns!(),
    ", coalesce(t.transcript_text, '') as transcript_text \
     from sessions s \
     left join transcripts t on t.session_id = s.id \
     where (s.id = ?1 or s.provider_session_id = ?1)"
);

const RESOLVE_SESSION_PREFIX_SQL: &str = concat!(
    "select ",
    session_record_columns!(),
    // Aliased so the reader can take it by name and stay immune to columns being added to
    // session_record_columns!.
    ", coalesce(t.transcript_text, '') as transcript_text \
     from sessions s \
     left join transcripts t on t.session_id = s.id \
     where (s.id like ?1 escape '\\' or s.provider_session_id like ?1 escape '\\')"
);

const RESOLVE_SESSION_RECORD_EXACT_SQL: &str = concat!(
    "select ",
    session_record_columns!(),
    " from sessions s where (s.id = ?1 or s.provider_session_id = ?1)"
);

const RESOLVE_SESSION_RECORD_PREFIX_SQL: &str = concat!(
    "select ",
    session_record_columns!(),
    " from sessions s where (s.id like ?1 escape '\\' or s.provider_session_id like ?1 escape '\\')"
);

fn unique_session_match<T>(
    value: &str,
    mut matches: Vec<T>,
    id_of: impl Fn(&T) -> &str,
) -> Result<T> {
    // Exact canonical/native probes run before prefix fallback. Retain this exact preference as a
    // defensive invariant for callers that provide a combined candidate set, while still
    // rejecting a bare native ID shared by multiple providers with canonical candidates named.
    if matches.len() > 1 {
        let is_exact =
            |id: &str| id == value || id.split_once(':').is_some_and(|(_, rest)| rest == value);
        let mut exact = matches
            .iter()
            .enumerate()
            .filter(|(_, m)| is_exact(id_of(m)));
        if let (Some((index, _)), None) = (exact.next(), exact.next()) {
            return Ok(matches.remove(index));
        }
    }
    match matches.len() {
        0 => Err(anyhow!(
            "no session matches '{value}' — run `aise list` to see recent session \
             ids, or `aise search <keywords>` to find one"
        )),
        1 => Ok(matches.remove(0)),
        _ => {
            let shown: Vec<&str> = matches.iter().take(8).map(id_of).collect();
            let more = matches.len().saturating_sub(shown.len());
            let suffix = if more > 0 {
                format!(" (+{more} more)")
            } else {
                String::new()
            };
            Err(anyhow!(
                "session prefix '{value}' is ambiguous — {} sessions match: {}{}. \
                 Pass a longer prefix or the full id.",
                matches.len(),
                shown.join(", "),
                suffix
            ))
        }
    }
}

fn row_to_session_with_transcript(
    row: &rusqlite::Row<'_>,
) -> rusqlite::Result<SessionWithTranscript> {
    Ok(SessionWithTranscript {
        session: row_to_session_record(row)?,
        // By NAME, not position: this column follows `session_record_columns!`, so every column
        // added to that macro shifts its index. Adding parent_session_id and agent_label broke
        // it exactly that way, and the failure was a confusing "Invalid column type Null at
        // index 17" rather than anything naming this line.
        transcript_text: row.get("transcript_text")?,
    })
}

fn row_to_session_record(row: &rusqlite::Row<'_>) -> rusqlite::Result<SessionRecord> {
    let provider: String = row.get(1)?;
    Ok(SessionRecord {
        id: row.get(0)?,
        provider: decode_db_enum(provider, 1, "sessions.provider", Provider::from_db_str)?,
        provider_session_id: row.get(2)?,
        title: row.get(3)?,
        summary: row.get(4)?,
        cwd: row.get(5)?,
        repo_root: row.get(6)?,
        created_at: row
            .get::<_, Option<String>>(7)?
            .as_deref()
            .and_then(crate::util::parse_datetime),
        updated_at: row
            .get::<_, Option<String>>(8)?
            .as_deref()
            .and_then(crate::util::parse_datetime),
        last_message_at: row
            .get::<_, Option<String>>(9)?
            .as_deref()
            .and_then(crate::util::parse_datetime),
        preview_text: row.get(10)?,
        source_path: row.get(11)?,
        message_count: row.get(12)?,
        parse_version: row.get(13)?,
        raw_metadata_json: row.get(14)?,
        parse_warning: row.get(15)?,
        discovery_source: row.get(16)?,
        parent_session_id: row.get(17)?,
        agent_label: row.get(18)?,
    })
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::models::SessionKind;

    const TEST_BUSY_TIMEOUT_MS: u64 = 250;
    const TEST_NO_WAIT_BUSY_TIMEOUT_MS: u64 = 0;

    #[test]
    fn message_row_rejects_corrupt_provider_and_role_with_recovery_context() {
        let connection = Connection::open_in_memory().unwrap();
        // The recovery differs by column: an unknown provider was written by a newer aise and a
        // reindex from this build fails on the same rows, so it must say upgrade; an unknown role
        // is corruption, so it must say reindex.
        for (provider, role, bad_value, column, advice, forbidden) in [
            (
                "not-a-provider",
                "user",
                "not-a-provider",
                "messages.provider",
                "upgrade aise",
                "reindex --full",
            ),
            (
                "claude",
                "not-a-role",
                "not-a-role",
                "messages.role",
                "aise reindex --full",
                "upgrade aise",
            ),
        ] {
            let error = connection
                .query_row(
                    "select 'session', ?1, 0, ?2, null, null, 'conversation', null, 'content'",
                    params![provider, role],
                    row_to_message_hit,
                )
                .unwrap_err();
            let error = error.to_string();
            assert!(error.contains(bad_value), "{error}");
            assert!(error.contains(column), "{error}");
            assert!(error.contains(advice), "{error}");
            assert!(!error.contains(forbidden), "{error}");
        }
    }

    /// A one-policy set built from ad-hoc `(category, [patterns])` pairs.
    ///
    /// Tests exercising the *query* path — scoping, paging, provider filters, parallelism — care
    /// about which rows come back, not about how a policy got selected, so they state categories
    /// inline instead of standing up a skill directory. Patterns are written WITHOUT `(?i)`: the
    /// compiler adds exactly one per category, as `analytics::compile_category_patterns` does.
    fn test_policies(
        categories: &[(&str, &[&str])],
    ) -> crate::corrections::ResolvedCorrectionPolicySet {
        let spec = crate::corrections::CorrectionPolicySpec {
            schema_version: crate::corrections::CORRECTION_POLICY_SCHEMA_VERSION,
            name: "test-policy".to_string(),
            version: "1.0.0".to_string(),
            categories: categories
                .iter()
                .map(
                    |(name, patterns)| crate::corrections::CorrectionCategorySpec {
                        name: (*name).to_string(),
                        patterns: patterns.iter().map(|p| (*p).to_string()).collect(),
                    },
                )
                .collect(),
        };
        crate::corrections::ResolvedCorrectionPolicySet::from_policies(vec![spec
            // `Embedded` because these bytes really do live in the program, not on disk.
            .compile_in_memory(crate::corrections::CorrectionPolicySource::Embedded)
            .expect("test correction policy compiles")])
    }

    /// What `aise skills corrections` evaluates for its embedded primary package.
    fn default_policies() -> crate::corrections::ResolvedCorrectionPolicySet {
        crate::corrections::ResolvedCorrectionPolicySet::from_policies(vec![
            crate::corrections::embedded_policy().expect("the built-in capability compiles"),
        ])
    }

    fn schema_fingerprint(conn: &Connection) -> Vec<(String, String, String, Option<String>)> {
        conn.prepare(
            "select type, name, tbl_name, sql
               from sqlite_schema
              where name not like 'sqlite_autoindex_%'
              order by type, name, tbl_name",
        )
        .unwrap()
        .query_map([], |row| {
            Ok((row.get(0)?, row.get(1)?, row.get(2)?, row.get(3)?))
        })
        .unwrap()
        .collect::<rusqlite::Result<_>>()
        .unwrap()
    }

    fn enable_v3_custom_trigram_compatibility(db: &Db) {
        db.conn
            .execute_batch(
                "drop trigger if exists messages_ai;
                 drop trigger if exists messages_ad;
                 drop trigger if exists messages_au;
                 drop table if exists messages_trigram_terms;
                 drop table if exists messages_trigram_vocab;
                 drop table if exists messages_trigram;",
            )
            .unwrap();
        crate::fts::install_released_message_word_index(&db.conn).unwrap();
        crate::trigram_index::ensure_schema(&db.conn).unwrap();
        db.conn.pragma_update(None, "user_version", 3).unwrap();
    }

    #[derive(Debug, Clone, Copy)]
    enum MessageContentMode {
        Literal,
        Regex,
        Fuzzy,
    }

    impl MessageContentMode {
        fn search(
            self,
            db: &Db,
            pattern: &str,
            mut filters: MessageFilters,
        ) -> Result<Vec<MessageHit>> {
            filters.match_mode = match self {
                Self::Literal => MessageSearchMode::Literal,
                Self::Regex => MessageSearchMode::Regex,
                Self::Fuzzy => MessageSearchMode::Fuzzy,
            };
            db.search_messages(pattern, &filters)
        }
    }

    const MESSAGE_CONTENT_MODE_CASES: [(MessageContentMode, &str); 3] = [
        (MessageContentMode::Literal, "shared needle"),
        (MessageContentMode::Regex, r"shared\s+needle"),
        (MessageContentMode::Fuzzy, "shared needle"),
    ];

    fn hit_keys(hits: Vec<MessageHit>) -> Vec<(String, i64)> {
        hits.into_iter()
            .map(|hit| (hit.session_id, hit.seq))
            .collect()
    }

    fn utc(value: &str) -> DateTime<Utc> {
        DateTime::parse_from_rfc3339(value)
            .unwrap()
            .with_timezone(&Utc)
    }

    #[test]
    fn glob_clause_maps_basename_and_path() {
        // No slash → basename match; `*`→`%`, `?`→`_`.
        assert_eq!(glob_clause("*.rs"), ("file_name", "%.rs".to_string()));
        assert_eq!(glob_clause("db.rs"), ("file_name", "db.rs".to_string()));
        // Slash present → full-path match, anchored with a leading `%`.
        assert_eq!(
            glob_clause("src/*.rs"),
            ("file_path", "%src/%.rs".to_string())
        );
        // LIKE specials are escaped so they match literally.
        assert_eq!(glob_clause("a_b%c"), ("file_name", "a\\_b\\%c".to_string()));
    }

    /// A session that spawned subagents must still resolve by its own id.
    ///
    /// Runs are identified as `<parent>/<run>`, so a spawner's id is a prefix of every run it
    /// spawned. Prefix resolution therefore reports the spawner's own exact id as ambiguous,
    /// which breaks `messages get`, `show`, `export`, and `resume` for exactly the sessions
    /// that delegated the most work. Caught by the demo suite the moment subagent fixtures were
    /// added: `session prefix 'cafe0001-...-000000000006' is ambiguous — 3 sessions match`.
    ///
    /// An exact identity is never ambiguous, whether given as the whole `id` or as the bare
    /// `provider_session_id`. A prefix that is nobody's exact id still reports every candidate.
    #[test]
    fn a_spawner_resolves_by_its_own_id_even_though_its_runs_extend_it() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions (
                     id, provider, provider_session_id, updated_at, preview_text,
                     source_path, parse_version, discovery_source, parent_session_id
                 ) values
                   ('claude:s6', 'claude', 's6', '2026-03-01T00:00:00+00:00', '', '/p', 'v1',
                    'test', null),
                   ('claude:s6/agent-a', 'claude', 's6/agent-a', '2026-03-02T00:00:00+00:00', '',
                    '/a', 'v1', 'test', 'claude:s6'),
                   ('claude:s6/agent-b', 'claude', 's6/agent-b', '2026-03-03T00:00:00+00:00', '',
                    '/b', 'v1', 'test', 'claude:s6');",
            )
            .unwrap();

        for spelling in ["s6", "claude:s6"] {
            assert_eq!(
                db.resolve_session_record(spelling).unwrap().id,
                "claude:s6",
                "the spawner's exact id must win over the runs that extend it: {spelling}"
            );
        }
        // A run still resolves by its own exact id.
        assert_eq!(
            db.resolve_session_record("s6/agent-a").unwrap().id,
            "claude:s6/agent-a"
        );
        // A prefix that is nobody's exact id is still reported as ambiguous, naming candidates.
        let error = db
            .resolve_session_record("s6/agent-")
            .expect_err("a genuine prefix collision must still be refused")
            .to_string();
        assert!(error.contains("ambiguous"), "{error}");
        assert!(
            error.contains("claude:s6/agent-a") && error.contains("claude:s6/agent-b"),
            "the refusal must name the candidates: {error}"
        );
    }

    /// Session date bounds intersect the closed known session span.
    ///
    /// A session spanning January through March matches periods and exact instants inside that
    /// span even when its terminal update lies outside the query. Missing endpoints retain the
    /// existing defensive fallback to the endpoint that is present.
    #[test]
    fn session_date_window_intersects_known_span_and_falls_back_for_null_endpoints() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions (
                     id, provider, provider_session_id, created_at, updated_at, preview_text,
                     source_path, parse_version, discovery_source
                 ) values
                   ('claude:long-running', 'claude', 'long-running', '2026-01-10T00:00:00+00:00',
                    '2026-03-10T00:00:00+00:00', '', '/long', 'v1', 'test'),
                   ('claude:february', 'claude', 'february', '2026-02-05T00:00:00+00:00',
                    '2026-02-06T00:00:00+00:00', '', '/february', 'v1', 'test'),
                   ('claude:never-updated', 'claude', 'never-updated', '2026-03-11T00:00:00+00:00',
                    null, '', '/never', 'v1', 'test'),
                   ('claude:creation-missing', 'claude', 'creation-missing', null,
                    '2026-01-20T00:00:00+00:00', '', '/creation-missing', 'v1', 'test');",
            )
            .unwrap();

        let ids = |since: Option<&str>, until: Option<&str>| {
            let mut ids: Vec<String> = db
                .list_recent(&SearchFilters {
                    since: since.and_then(crate::util::parse_datetime),
                    until: until.and_then(crate::util::parse_datetime),
                    ..SearchFilters::default()
                })
                .unwrap()
                .into_iter()
                .map(|session| session.id)
                .collect();
            ids.sort();
            ids
        };

        assert_eq!(
            ids(
                Some("2026-01-01T00:00:00+00:00"),
                Some("2026-01-31T23:59:59+00:00")
            ),
            vec!["claude:creation-missing", "claude:long-running"],
            "January intersects the long-running span and both point fallbacks"
        );
        assert_eq!(
            ids(
                Some("2026-02-15T00:00:00+00:00"),
                Some("2026-02-15T00:00:00+00:00")
            ),
            vec!["claude:long-running"],
            "an exact instant inside the known span is included"
        );
        assert_eq!(
            ids(None, Some("2026-01-31T23:59:59+00:00")),
            vec!["claude:creation-missing", "claude:long-running"],
            "until compares the session start, not terminal activity"
        );
        assert_eq!(
            ids(Some("2026-03-01T00:00:00+00:00"), None),
            vec!["claude:long-running", "claude:never-updated"],
            "since compares the session end"
        );
        assert!(ids(Some("2026-03-12T00:00:00+00:00"), None).is_empty());
    }

    /// Subagent runs outnumber the sessions that spawned them — 4,051 against 858 user-started
    /// claude sessions on the machine this was built against — so selecting a class has to
    /// work, and the default has to return both rather than quietly halving the index.
    #[test]
    fn session_kinds_select_user_started_runs_or_both() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions (
                     id, provider, provider_session_id, updated_at, preview_text,
                     source_path, parse_version, discovery_source, parent_session_id, agent_label
                 ) values
                   ('claude:parent', 'claude', 'parent', '2026-03-01T00:00:00+00:00', '',
                    '/parent', 'v1', 'test', null, null),
                   ('claude:parent/agent-a', 'claude', 'parent/agent-a', '2026-03-02T00:00:00+00:00',
                    '', '/a', 'v1', 'test', 'claude:parent', 'Explore'),
                   ('claude:other/agent-b', 'claude', 'other/agent-b', '2026-03-03T00:00:00+00:00',
                    '', '/b', 'v1', 'test', 'claude:other', 'general-purpose');",
            )
            .unwrap();

        let ids = |kinds: Option<Vec<SessionKind>>, parent: Option<&str>| {
            let mut ids: Vec<String> = db
                .list_recent(&SearchFilters {
                    session_kinds: kinds,
                    parent_session_id: parent.map(str::to_string),
                    ..SearchFilters::default()
                })
                .unwrap()
                .into_iter()
                .map(|session| session.id)
                .collect();
            ids.sort();
            ids
        };

        assert_eq!(
            ids(None, None),
            vec![
                "claude:other/agent-b",
                "claude:parent",
                "claude:parent/agent-a"
            ],
            "naming no class returns every class, so indexed work is never invisible"
        );
        assert_eq!(
            ids(Some(vec![SessionKind::User]), None),
            vec!["claude:parent"]
        );
        assert_eq!(
            ids(Some(vec![SessionKind::User, SessionKind::User]), None),
            vec!["claude:parent"],
            "repeating one set member must not make it equivalent to the complete set"
        );
        assert_eq!(
            ids(Some(vec![SessionKind::Subagent]), None),
            vec!["claude:other/agent-b", "claude:parent/agent-a"]
        );
        assert_eq!(
            ids(Some(vec![SessionKind::User, SessionKind::Subagent]), None),
            ids(None, None),
            "naming both classes is the default set spelled out"
        );
        assert!(
            ids(Some(Vec::new()), None).is_empty(),
            "deselecting every class matches nothing rather than silently matching all"
        );

        // `parent_session_id` holds the parent row's whole id, so the value a caller already
        // holds from a listing is the value that selects that session's runs.
        assert_eq!(
            ids(None, Some("claude:parent")),
            vec!["claude:parent/agent-a"]
        );
        assert!(ids(None, Some("claude:parent/agent-a")).is_empty());

        // `claude:other` is named by a run but is not itself a row, which is the ordinary case
        // rather than corruption: providers keep a run's transcript after the parent
        // conversation is rotated away, and 69 of 69 unresolved parents in one project
        // directory had no transcript left on disk. The run must still store and still select,
        // which is what makes that otherwise-unreachable work searchable.
        assert_eq!(
            ids(Some(vec![SessionKind::Subagent]), Some("claude:other")),
            vec!["claude:other/agent-b"],
            "a run whose parent is not indexed is still a session"
        );
    }

    #[test]
    fn list_recent_is_sql_bounded_and_does_not_read_transcripts() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions (
                     id, provider, provider_session_id, updated_at, preview_text,
                     source_path, parse_version, discovery_source
                 ) values
                   ('claude:old', 'claude', 'old', '2026-01-01T00:00:00+00:00', '', '/old', 'v1', 'test'),
                   ('claude:middle', 'claude', 'middle', '2026-02-01T00:00:00+00:00', '', '/middle', 'v1', 'test'),
                   ('claude:new', 'claude', 'new', '2026-03-01T00:00:00+00:00', '', '/new', 'v1', 'test');
                 drop table transcripts;",
            )
            .unwrap();

        let mut filters = SearchFilters {
            limit: 2,
            ..SearchFilters::default()
        };
        let sessions = db.list_recent(&filters).unwrap();

        assert_eq!(
            sessions
                .into_iter()
                .map(|session| session.id)
                .collect::<Vec<_>>(),
            ["claude:new", "claude:middle"]
        );

        filters.limit = 0;
        assert_eq!(
            db.list_recent(&filters)
                .unwrap()
                .into_iter()
                .map(|session| session.id)
                .collect::<Vec<_>>(),
            ["claude:new", "claude:middle", "claude:old"]
        );
    }

    #[test]
    fn analysis_documents_keyset_pages_normalized_user_text_and_empty_sessions() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions (
                     id, provider, provider_session_id, preview_text,
                     source_path, parse_version, discovery_source
                 ) values
                   ('claude:a', 'claude', 'a', '', '/a', 'v1', 'test'),
                   ('claude:b', 'claude', 'b', '', '/b', 'v1', 'test'),
                   ('codex:c', 'codex', 'c', '', '/c', 'v1', 'test');
                 insert into messages (
                     session_id, provider, seq, role, content, authorship, record_relation
                 ) values
                   ('claude:a', 'claude', 0, 'user', 'first request', 'human', 'original'),
                   ('claude:a', 'claude', 1, 'assistant', 'answer', 'agent', 'original'),
                   ('claude:a', 'claude', 2, 'user', 'second request', 'human', 'original'),
                   ('codex:c', 'codex', 0, 'user', 'other provider', 'human', 'original');
                 drop table transcripts;",
            )
            .unwrap();
        let filters = SearchFilters {
            provider: Some(Provider::Claude),
            limit: 1,
            ..SearchFilters::default()
        };

        let first = db.analysis_documents(&filters, None).unwrap();
        assert_eq!(first.documents.len(), 1);
        assert_eq!(first.documents[0].session.id, "claude:a");
        assert_eq!(first.documents[0].message_count, 3);
        assert_eq!(first.documents[0].user_message_count, 2);
        assert_eq!(first.documents[0].user_text, "first request second request");
        assert_eq!(
            first.documents[0].first_user_text.as_deref(),
            Some("first request")
        );

        let second = db
            .analysis_documents(&filters, first.next_cursor.as_ref())
            .unwrap();
        assert_eq!(second.documents.len(), 1);
        assert_eq!(second.documents[0].session.id, "claude:b");
        assert_eq!(second.documents[0].message_count, 0);
        assert_eq!(second.documents[0].user_message_count, 0);
        assert!(second.documents[0].user_text.is_empty());
        assert!(second.documents[0].first_user_text.is_none());
        assert!(second.next_cursor.is_none());
    }

    #[test]
    fn analysis_selects_original_human_authorship_and_human_parts_of_mixed_messages() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions (
                     id, provider, provider_session_id, preview_text,
                     source_path, parse_version, discovery_source
                 ) values ('claude:authorship', 'claude', 'authorship', '', '/authorship', 'v1', 'test');
                 insert into messages (
                     id, session_id, provider, seq, role, kind, content, authorship, record_relation
                 ) values
                   (101, 'claude:authorship', 'claude', 0, 'user', 'conversation',
                    'human original', 'human', 'original'),
                   (102, 'claude:authorship', 'claude', 1, 'user', 'conversation',
                    'agent delegation', 'agent', 'original'),
                   (103, 'claude:authorship', 'claude', 2, 'user', 'conversation',
                    'human α\ngenerated β\nhuman γ', 'mixed', 'original'),
                   (104, 'claude:authorship', 'claude', 3, 'user', 'conversation',
                    'mirrored human', 'human', 'mirror'),
                   (105, 'claude:authorship', 'claude', 4, 'user', 'conversation',
                    'legacy uncertainty', 'unknown', 'unknown');
                 insert into message_content_parts (
                     message_id, ordinal, start_char, end_char, authorship, origin
                 ) values
                   (103, 0, 0, 8, 'human', 'direct_input'),
                   (103, 1, 8, 20, 'generated', 'tool_payload'),
                   (103, 2, 20, 27, 'human', 'direct_input');",
            )
            .unwrap();

        let filters = SearchFilters {
            limit: 1,
            ..SearchFilters::default()
        };
        let page = db.analysis_documents(&filters, None).unwrap();
        let document = &page.documents[0];
        assert_eq!(document.message_count, 5);
        assert_eq!(document.user_message_count, 2);
        assert_eq!(
            document.user_text, "human original human α\nhuman γ",
            "analysis must exclude agent, generated, mirrored, and unknown-attribution text"
        );
        assert_eq!(document.first_user_text.as_deref(), Some("human original"));

        let request = crate::models::AnalysisRequest::new(
            SearchFilters::default(),
            crate::models::AnalysisSessionSelection::AllEligible,
        )
        .unwrap();
        let mut chunks = Vec::new();
        let receipt = db
            .visit_analysis_sessions(
                &request,
                std::num::NonZeroUsize::new(1).unwrap(),
                |_session, _message_count, human_message_count, messages| {
                    assert_eq!(human_message_count, 2);
                    chunks.extend(messages.collect::<Result<Vec<_>>>()?);
                    Ok(())
                },
            )
            .unwrap();
        assert_eq!(
            chunks,
            [
                (0, "human original".to_string()),
                (2, "human α\nhuman γ".to_string())
            ]
        );
        assert_eq!(receipt.analyzed_user_messages, 2);
    }

    #[test]
    fn analysis_visit_keeps_one_snapshot_across_bounded_pages() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("index.db");
        let db = Db::open(&path).unwrap();
        let writer = Db::open(&path).unwrap();
        for (id, source) in [
            ("claude:a", "/fixture/a.jsonl"),
            ("claude:z", "/fixture/z.jsonl"),
        ] {
            let mut parsed =
                crate::util::minimal_record(Provider::Claude, Path::new(source), "test".into());
            parsed.session.id = id.into();
            parsed.session.provider_session_id = id.into();
            parsed.messages.push(crate::models::Message {
                seq: 0,
                role: crate::models::Role::User,
                ts: None,
                tool_name: None,
                kind: crate::models::MessageKind::Conversation,
                tool_call_id: None,
                is_compaction: false,
                content: format!("content for {id}"),
                provenance: crate::models::MessageProvenance::default(),
            });
            db.upsert_session(&parsed, 0, 0).unwrap();
        }
        let mut late = crate::util::minimal_record(
            Provider::Claude,
            Path::new("/fixture/m.jsonl"),
            "test".into(),
        );
        late.session.id = "claude:m".into();
        late.session.provider_session_id = "claude:m".into();
        let request = crate::models::AnalysisRequest::new(
            SearchFilters::default(),
            crate::models::AnalysisSessionSelection::AllEligible,
        )
        .unwrap();
        let mut seen = Vec::new();
        let receipt = db
            .visit_analysis_sessions(
                &request,
                std::num::NonZeroUsize::new(1).unwrap(),
                |session, _message_count, _user_message_count, _chunks| {
                    seen.push(session.id);
                    if seen.len() == 1 {
                        writer.upsert_session(&late, 0, 0)?;
                    }
                    Ok(())
                },
            )
            .unwrap();

        assert_eq!(receipt.selected_sessions, 2);
        assert!(!receipt.has_more);
        assert_eq!(seen, ["claude:a", "claude:z"]);
        assert_eq!(
            receipt.last_selected_session_id.as_deref(),
            Some("claude:z")
        );
        assert_eq!(
            db.resolve_session_record("claude:m").unwrap().id,
            "claude:m"
        );
        let original_population = crate::models::AnalysisRequest::new(
            SearchFilters {
                exclude_session_ids: vec!["claude:m".to_owned()],
                ..SearchFilters::default()
            },
            crate::models::AnalysisSessionSelection::AllEligible,
        )
        .unwrap();
        let consumed = db
            .visit_analysis_sessions(
                &original_population,
                std::num::NonZeroUsize::new(1).unwrap(),
                |_session, _message_count, _user_message_count, chunks| {
                    for chunk in chunks {
                        chunk?;
                    }
                    Ok(())
                },
            )
            .unwrap();
        assert_eq!(
            receipt.corpus_digest, consumed.corpus_digest,
            "the owner must hash unread human-authored message rows after a successful visitor"
        );
        let later = db
            .visit_analysis_sessions(
                &request,
                std::num::NonZeroUsize::new(1).unwrap(),
                |_session, _message_count, _user_message_count, _chunks| Ok(()),
            )
            .unwrap();
        assert_eq!(later.selected_sessions, 3);
        assert_ne!(
            receipt.corpus_digest, later.corpus_digest,
            "the earlier receipt must describe only its original read snapshot"
        );
    }

    #[test]
    fn analysis_documents_rejects_unbounded_pages() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let error = db
            // limit stated rather than defaulted: an unbounded page is what this rejects, so
            // the value under test must not move if the default ever does.
            .analysis_documents(
                &SearchFilters {
                    limit: 0,
                    ..SearchFilters::default()
                },
                None,
            )
            .unwrap_err();
        assert!(error.to_string().contains("greater than zero"));
    }

    #[test]
    fn planning_usage_optionally_filters_by_command_patterns() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute(
                "insert into sessions (id, provider, provider_session_id, preview_text, \
                 source_path, parse_version, discovery_source) \
                 values ('s1','claude','s1','','/p','1','test')",
                [],
            )
            .unwrap();
        db.conn
            .execute(
                "insert into sessions (id, provider, provider_session_id, preview_text, \
                 source_path, parse_version, discovery_source) \
                 values ('s2','codex','s2','','/p2','1','test')",
                [],
            )
            .unwrap();
        let slash = |id: i64, session_id: &str, provider: &str, seq: i64, content: &str| {
            db.conn
                .execute(
                    "insert into messages (id, session_id, provider, seq, role, content) \
                     values (?1,?2,?3,?4,'slash',?5)",
                    params![id, session_id, provider, seq, content],
                )
                .unwrap();
        };
        slash(1, "s1", "claude", 0, "/cmd-a make a plan");
        slash(2, "s1", "claude", 1, "/cmd-b");
        slash(3, "s1", "claude", 2, "/cmd-a refine it");
        slash(4, "s2", "codex", 0, "/cmd-c ship the fix");

        // No filter (config default) → every slash command is counted.
        let all = db.planning_usage(&MessageFilters::default(), &[]).unwrap();
        assert_eq!(all.len(), 3, "all distinct commands counted");

        // A configured filter restricts to matching commands.
        let only = db
            .planning_usage(
                &MessageFilters::default(),
                &[regex::Regex::new(r"^/cmd-a$").unwrap()],
            )
            .unwrap();
        assert_eq!(only.len(), 1);
        assert_eq!(only[0].command, "/cmd-a");
        assert_eq!(only[0].count, 2);

        let command_token_only = db
            .planning_usage(
                &MessageFilters::default(),
                &[regex::Regex::new(r"^/cmd-b$").unwrap()],
            )
            .unwrap();
        assert_eq!(
            command_token_only
                .iter()
                .map(|row| row.command.as_str())
                .collect::<Vec<_>>(),
            vec!["/cmd-b"],
            "planning filters command tokens, not arbitrary slash-message body text"
        );

        // Shared MessageFilters must apply here too; planning is not a special search path.
        let codex = db
            .planning_usage(
                &MessageFilters {
                    providers: Some(vec![Provider::Codex]),
                    ..Default::default()
                },
                &[],
            )
            .unwrap();
        assert_eq!(codex.len(), 1);
        assert_eq!(codex[0].command, "/cmd-c");
    }

    #[test]
    fn search_messages_uses_exact_literal_substring_semantics() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute(
                "insert into sessions (id, provider, provider_session_id, preview_text, \
                 source_path, parse_version, discovery_source) \
                 values ('s1','claude','s1','','/p','1','test')",
                [],
            )
            .unwrap();
        let insert = |id: i64, seq: i64, content: &str| {
            db.conn
                .execute(
                    "insert into messages (id, session_id, provider, seq, role, content) \
                     values (?1,'s1','claude',?2,'user',?3)",
                    params![id, seq, content],
                )
                .unwrap();
        };
        insert(1, 0, "please handle the error");
        insert(2, 1, "the handler crashed");
        insert(3, 2, "we mishandled the input");
        insert(4, 3, "error handling code here");
        insert(5, 4, "use a => b arrow");
        insert(6, 5, "literal /goal command");
        insert(7, 6, "plain goal token");
        insert(8, 7, "compile C++ today");
        insert(9, 8, "flag --path passed");
        insert(10, 9, "CAFÉ diagnostic");
        insert(11, 10, "İstanbul diagnostic");

        let seqs = |query: &str| -> Vec<i64> {
            let mut v: Vec<i64> = db
                .search_messages(query, &MessageFilters::default())
                .unwrap()
                .into_iter()
                .map(|h| h.seq)
                .collect();
            v.sort();
            v
        };
        assert_eq!(seqs("handle"), vec![0, 1, 2]);
        assert_eq!(seqs("handled"), vec![2]);
        // A multi-word query is a contiguous phrase.
        assert_eq!(seqs("error handling"), vec![3]);
        assert_eq!(seqs("=>"), vec![4]);
        assert_eq!(seqs("/goal"), vec![5]);
        assert_eq!(seqs("goal"), vec![5, 6]);
        assert_eq!(seqs("C++"), vec![7]);
        assert_eq!(seqs("--path"), vec![8]);
        assert_eq!(seqs("café"), vec![9]);
        assert_eq!(seqs("İS"), vec![10]);
        assert_eq!(
            seqs("İST"),
            vec![10],
            "the trigram candidate gate must remain a superset of Unicode lowercase matching"
        );
        // Empty query lists everything (structured filters only).
        assert_eq!(seqs("").len(), 11);
        // --regex still matches arbitrary patterns over the rows (scan path).
        let re = db
            .search_messages(
                "h.ndler",
                &MessageFilters {
                    match_mode: MessageSearchMode::Regex,
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(re.into_iter().map(|h| h.seq).collect::<Vec<_>>(), vec![1]);
    }

    #[test]
    fn fuzzy_message_search_ranks_approximate_matches_without_changing_literal_search() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute(
                "insert into sessions (id, provider, provider_session_id, preview_text, \
                 source_path, parse_version, discovery_source) \
                 values ('s1','claude','s1','','/p','1','test')",
                [],
            )
            .unwrap();
        for (seq, content) in [
            (
                0,
                "please avoid magic values and keep settings configurable",
            ),
            (1, "hard-coded timeout should move into config"),
            (2, "unrelated transcript text"),
            (3, "magic numbers should move into named values"),
        ] {
            db.conn
                .execute(
                    "insert into messages (session_id, provider, seq, role, content) \
                     values ('s1','claude',?1,'user',?2)",
                    params![seq, content],
                )
                .unwrap();
        }

        let literal = db
            .search_messages("magic config", &MessageFilters::default())
            .unwrap();
        assert!(literal.is_empty(), "literal search remains exact");

        let fuzzy = db
            .search_messages(
                "magic config",
                &MessageFilters {
                    match_mode: MessageSearchMode::Fuzzy,
                    limit: 10,
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(fuzzy.iter().map(|hit| hit.seq).collect::<Vec<_>>(), vec![0]);
        assert!(fuzzy[0].fuzzy_score.is_some());

        let fuzzy_phrase = db
            .search_messages(
                "magic values",
                &MessageFilters {
                    match_mode: MessageSearchMode::Fuzzy,
                    limit: 10,
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(fuzzy_phrase[0].seq, 0, "exact phrase wins fuzzy ties");
    }

    #[test]
    fn schema_v4_fuzzy_search_filters_structurally_before_exhaustive_scoring() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("index.db");
        {
            let db = Db::open(&path).unwrap();
            for (id, provider, seq, role, content) in [
                (
                    "s1",
                    "claude",
                    0,
                    "user",
                    "incremental trigram acceleration",
                ),
                ("s1", "claude", 1, "assistant", "unrelated response"),
                ("s2", "codex", 0, "user", "incremental index design"),
            ] {
                db.conn
                    .execute(
                        "insert or ignore into sessions
                         (id, provider, provider_session_id, preview_text, source_path,
                          parse_version, discovery_source)
                         values (?1, ?2, ?1, '', '/p', '1', 'test')",
                        params![id, provider],
                    )
                    .unwrap();
                db.conn
                    .execute(
                        "insert into messages
                         (session_id, provider, seq, role, content)
                         values (?1, ?2, ?3, ?4, ?5)",
                        params![id, provider, seq, role, content],
                    )
                    .unwrap();
            }
        }

        let db = Db::open(&path).unwrap();
        let (hits, explain) = db
            .search_messages_with_explain(
                "incrmental trigram",
                &MessageFilters {
                    providers: Some(vec![Provider::Claude]),
                    role: Some(Role::User),
                    match_mode: MessageSearchMode::Fuzzy,
                    limit: 10,
                    ..Default::default()
                },
                true,
            )
            .unwrap();
        assert_eq!(hits.iter().map(|hit| hit.seq).collect::<Vec<_>>(), vec![0]);
        assert!(hits[0].fuzzy_score.is_some());
        let explain = explain.unwrap();
        assert_eq!(explain.prefilter.as_deref(), None);
        assert_eq!(
            explain.prefilter_skipped.as_deref(),
            Some("complete filtered corpus scored, retaining at most min(offset + limit, corpus) ranked rows")
        );
        assert_eq!(explain.corpus, 1);
    }

    #[test]
    fn exhaustive_fuzzy_ranking_keeps_a_best_hit_beyond_the_old_candidate_cap() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute(
                "insert into sessions (id, provider, provider_session_id, preview_text,
                 source_path, parse_version, discovery_source)
                 values ('s1','claude','s1','','/p','1','test')",
                [],
            )
            .unwrap();
        let tx = db.conn.unchecked_transaction().unwrap();
        {
            let mut insert = tx
                .prepare(
                    "insert into messages(session_id, provider, seq, role, content)
                     values ('s1','claude',?1,'user',?2)",
                )
                .unwrap();
            for seq in 0..1_300_i64 {
                insert
                    .execute(params![
                        seq,
                        format!("magic values configurable filler {seq}")
                    ])
                    .unwrap();
            }
            insert.execute(params![1_300_i64, "magic config"]).unwrap();
        }
        tx.commit().unwrap();

        let hits = db
            .search_messages(
                "magic config",
                &MessageFilters {
                    match_mode: MessageSearchMode::Fuzzy,
                    limit: 1,
                    ..Default::default()
                },
            )
            .unwrap();

        assert_eq!(hits.len(), 1);
        assert_eq!(hits[0].seq, 1_300);

        let first_two = db
            .search_messages(
                "magic config",
                &MessageFilters {
                    match_mode: MessageSearchMode::Fuzzy,
                    limit: 2,
                    ..Default::default()
                },
            )
            .unwrap();
        let second = db
            .search_messages(
                "magic config",
                &MessageFilters {
                    match_mode: MessageSearchMode::Fuzzy,
                    limit: 1,
                    offset: 1,
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(second.len(), 1);
        assert_eq!(second[0].session_id, first_two[1].session_id);
        assert_eq!(second[0].seq, first_two[1].seq);
        assert_eq!(second[0].fuzzy_score, first_two[1].fuzzy_score);
    }

    #[test]
    fn search_messages_path_prefix_scopes_by_session_root_and_metadata_enriches() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let session = |id: &str, cwd: &str, repo: &str, title: &str| {
            db.conn
                .execute(
                    "insert into sessions (id, provider, provider_session_id, title, cwd, \
                     repo_root, preview_text, source_path, parse_version, discovery_source) \
                     values (?1,'claude',?1,?2,?3,?4,'','/p','1','test')",
                    params![id, title, cwd, repo],
                )
                .unwrap();
        };
        session("a", "/Users/x/proj-a", "/Users/x/proj-a", "Proj A");
        session("b", "/Users/x/proj-b", "/Users/x/proj-b", "Proj B");
        let msg = |id: i64, sid: &str| {
            db.conn
                .execute(
                    "insert into messages (id, session_id, provider, seq, role, content) \
                     values (?1,?2,'claude',0,'user','shared keyword here')",
                    params![id, sid],
                )
                .unwrap();
        };
        msg(1, "a");
        msg(2, "b");

        // path_prefix scopes to sessions rooted under the prefix (cwd OR repo_root),
        // mirroring the session-level `--path` semantics.
        let scoped = db
            .search_messages(
                "keyword",
                &MessageFilters {
                    path_prefix: Some("/Users/x/proj-a".into()),
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(
            scoped
                .iter()
                .map(|h| h.session_id.clone())
                .collect::<Vec<_>>(),
            vec!["a"],
            "only the proj-a session matches the path prefix"
        );

        // No prefix → both sessions match.
        assert_eq!(
            db.search_messages("keyword", &MessageFilters::default())
                .unwrap()
                .len(),
            2
        );

        // session_metadata batch-enriches by id (used by the MCP search_messages serializer).
        let meta = db
            .session_metadata(&["a".to_string(), "b".to_string()])
            .unwrap();
        assert_eq!(meta["a"].cwd.as_deref(), Some("/Users/x/proj-a"));
        assert_eq!(meta["a"].repo_root.as_deref(), Some("/Users/x/proj-a"));
        assert_eq!(meta["a"].title.as_deref(), Some("Proj A"));
        assert_eq!(meta["b"].title.as_deref(), Some("Proj B"));
    }

    #[test]
    fn session_metadata_batches_use_one_bind_and_indexed_sql_above_parameter_limits() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let ids = (0..1_200)
            .map(|index| format!("codex:metadata-{index}"))
            .collect::<Vec<_>>();
        {
            let transaction = db.conn.unchecked_transaction().unwrap();
            {
                let mut insert = transaction
                    .prepare(
                        "insert into sessions (
                             id, provider, provider_session_id, title, preview_text, source_path,
                             parse_version, discovery_source, raw_metadata_json
                         ) values (?1, 'codex', ?2, ?2, '', ?3, '1', 'test', ?4)",
                    )
                    .unwrap();
                for (index, id) in ids.iter().enumerate() {
                    let provider_session_id = format!("metadata-{index}");
                    insert
                        .execute(params![
                            id,
                            provider_session_id,
                            format!("/transcripts/{provider_session_id}.jsonl"),
                            format!(r#"{{"index":{index}}}"#),
                        ])
                        .unwrap();
                }
            }
            transaction.commit().unwrap();
        }

        let metadata = db.session_metadata(&ids).unwrap();
        let raw_metadata = db.session_raw_provider_metadata(&ids).unwrap();
        assert_eq!(metadata.len(), ids.len());
        assert_eq!(raw_metadata.len(), ids.len());
        assert_eq!(
            metadata[&ids[1_199]].title.as_deref(),
            Some("metadata-1199")
        );

        let plan = {
            let mut statement = db
                .conn
                .prepare(
                    "explain query plan
                     select s.id
                       from json_each(?) requested
                       join sessions s on s.id = requested.value",
                )
                .unwrap();
            statement
                .query_map([serde_json::to_string(&ids).unwrap()], |row| {
                    row.get::<_, String>(3)
                })
                .unwrap()
                .collect::<rusqlite::Result<Vec<_>>>()
                .unwrap()
                .join(" | ")
        };
        assert!(
            plan.contains("sqlite_autoindex_sessions_1"),
            "session metadata join must probe indexed sessions.id: {plan}"
        );
    }

    #[test]
    fn search_messages_excludes_paths_and_sessions_before_limit() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let session = |id: &str, cwd: &str, repo: &str, source_path: &str| {
            db.conn
                .execute(
                    "insert into sessions (id, provider, provider_session_id, cwd, repo_root, \
                     preview_text, source_path, parse_version, discovery_source) \
                     values (?1,'claude',?1,?2,?3,'',?4,'1','test')",
                    params![id, cwd, repo, source_path],
                )
                .unwrap();
        };
        session("a", "/Users/x/proj-a", "/Users/x", "/logs/a.jsonl");
        session("b", "/Users/x/proj-b", "/Users/x", "/logs/b.jsonl");
        session("c", "/Users/x/proj-c", "/Users/x", "/tmp/noisy/c.jsonl");
        for (id, seq) in [("a", 0), ("b", 0), ("c", 0)] {
            db.conn
                .execute(
                    "insert into messages (session_id, provider, seq, role, content) \
                     values (?1,'claude',?2,'user','shared needle')",
                    params![id, seq],
                )
                .unwrap();
        }

        for (mode, pattern) in MESSAGE_CONTENT_MODE_CASES {
            let hits = mode
                .search(
                    &db,
                    pattern,
                    MessageFilters {
                        path_prefix: Some("/Users/x".into()),
                        exclude_path_prefixes: vec!["/Users/x/proj-a".into(), "/tmp/noisy".into()],
                        limit: 1,
                        ..Default::default()
                    },
                )
                .unwrap();
            assert_eq!(
                hits.iter()
                    .map(|hit| hit.session_id.as_str())
                    .collect::<Vec<_>>(),
                vec!["b"],
                "{mode:?}: exclusions apply before limit, including source_path exclusions"
            );
        }

        for (mode, pattern) in MESSAGE_CONTENT_MODE_CASES {
            let hits = mode
                .search(
                    &db,
                    pattern,
                    MessageFilters {
                        exclude_session_ids: vec!["b".into()],
                        limit: 10,
                        ..Default::default()
                    },
                )
                .unwrap();
            assert_eq!(
                hits.iter()
                    .map(|hit| hit.session_id.as_str())
                    .collect::<Vec<_>>(),
                vec!["a", "c"],
                "{mode:?}: session exclusions apply before content matching"
            );
        }
    }

    #[test]
    fn search_messages_content_modes_share_structural_filters() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let session = |id: &str, provider: Provider, cwd: &str, repo: &str, source_path: &str| {
            db.conn
                .execute(
                    "insert into sessions (id, provider, provider_session_id, cwd, repo_root, \
                     preview_text, source_path, parse_version, discovery_source) \
                     values (?1,?2,?1,?3,?4,'',?5,'1','test')",
                    params![id, provider.as_str(), cwd, repo, source_path],
                )
                .unwrap();
        };
        session(
            "target",
            Provider::Claude,
            "/Users/x/proj-a",
            "/Users/x/proj-a",
            "/logs/target.jsonl",
        );
        session(
            "wrong-provider",
            Provider::Codex,
            "/Users/x/proj-a",
            "/Users/x/proj-a",
            "/logs/wrong-provider.jsonl",
        );
        session(
            "wrong-path",
            Provider::Claude,
            "/Users/x/proj-b",
            "/Users/x/proj-b",
            "/logs/wrong-path.jsonl",
        );
        let msg =
            |id: i64, session_id: &str, provider: Provider, seq: i64, role: Role, ts: &str| {
                db.conn
                    .execute(
                        "insert into messages (id, session_id, provider, seq, role, ts, content) \
                     values (?1,?2,?3,?4,?5,?6,'shared needle phrase')",
                        params![id, session_id, provider.as_str(), seq, role.as_str(), ts],
                    )
                    .unwrap();
            };
        msg(
            1,
            "target",
            Provider::Claude,
            10,
            Role::User,
            "2026-01-02T00:00:00Z",
        );
        msg(
            2,
            "target",
            Provider::Claude,
            11,
            Role::Assistant,
            "2026-01-02T00:00:00Z",
        );
        msg(
            3,
            "wrong-provider",
            Provider::Codex,
            10,
            Role::User,
            "2026-01-02T00:00:00Z",
        );
        msg(
            4,
            "wrong-path",
            Provider::Claude,
            10,
            Role::User,
            "2026-01-02T00:00:00Z",
        );
        msg(
            5,
            "target",
            Provider::Claude,
            9,
            Role::User,
            "2025-12-31T00:00:00Z",
        );

        let filters = MessageFilters {
            role: Some(Role::User),
            providers: Some(vec![Provider::Claude]),
            path_prefix: Some("/Users/x/proj-a".into()),
            since: Some(utc("2026-01-01T00:00:00Z")),
            until: Some(utc("2026-01-31T00:00:00Z")),
            seq_from: Some(10),
            seq_to: Some(10),
            limit: 10,
            ..Default::default()
        };

        for (mode, pattern) in MESSAGE_CONTENT_MODE_CASES {
            assert_eq!(
                hit_keys(mode.search(&db, pattern, filters.clone()).unwrap()),
                vec![("target".to_string(), 10)],
                "{mode:?}: content mode must compose with role/provider/path/time/seq filters"
            );
        }
    }

    #[test]
    fn read_session_messages_selects_by_order_within_range_and_offset() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute(
                "insert into sessions (id, provider, provider_session_id, cwd, repo_root, \
                 preview_text, source_path, parse_version, discovery_source) \
                 values ('claude:s','claude','s','/p','/p','','/p','1','test')",
                [],
            )
            .unwrap();
        let msg = |seq: i64, role: &str, content: &str| {
            db.conn
                .execute(
                    "insert into messages (session_id, provider, seq, role, content) \
                     values ('claude:s','claude',?1,?2,?3)",
                    params![seq, role, content],
                )
                .unwrap();
        };
        // seq 0..3, roles: user, assistant, user, slash (mirrors the CLAUDE_FIXTURE shape).
        msg(0, "user", "first user turn");
        msg(1, "assistant", "assistant reply");
        msg(2, "user", "second user turn");
        msg(3, "slash", "/cmd make a plan");

        let seqs = |hits: Vec<MessageHit>| hits.iter().map(|h| h.seq).collect::<Vec<i64>>();
        let filters = |mutate: &dyn Fn(&mut MessageFilters)| {
            let mut f = MessageFilters {
                session_id: Some("claude:s".to_string()),
                ..Default::default()
            };
            mutate(&mut f);
            f
        };

        // OldestFirst + limit 2 = the first (oldest) 2, in chronological order.
        assert_eq!(
            seqs(
                db.read_session_messages(&filters(&|f| f.limit = 2), MessageOrder::OldestFirst)
                    .unwrap()
            ),
            vec![0, 1]
        );
        // NewestFirst + limit 2 = the last (newest) 2, STILL returned oldest-first. Order drives
        // SELECTION, not just display (no git --reverse-after-limit trap).
        assert_eq!(
            seqs(
                db.read_session_messages(&filters(&|f| f.limit = 2), MessageOrder::NewestFirst)
                    .unwrap()
            ),
            vec![2, 3]
        );
        // limit 0 = all, chronological regardless of the fetch direction.
        assert_eq!(
            seqs(
                db.read_session_messages(&filters(&|f| f.limit = 0), MessageOrder::NewestFirst)
                    .unwrap()
            ),
            vec![0, 1, 2, 3]
        );
        // Role filter composes with the newest-N window.
        assert_eq!(
            seqs(
                db.read_session_messages(
                    &filters(&|f| {
                        f.role = Some(Role::User);
                        f.limit = 1;
                    }),
                    MessageOrder::NewestFirst
                )
                .unwrap()
            ),
            vec![2]
        );
        // Inclusive seq range is the non-overlapping chunked-read primitive.
        assert_eq!(
            seqs(
                db.read_session_messages(
                    &filters(&|f| {
                        f.seq_from = Some(1);
                        f.seq_to = Some(2);
                    }),
                    MessageOrder::OldestFirst
                )
                .unwrap()
            ),
            vec![1, 2]
        );
        // Offset paginates the oldest-first window.
        assert_eq!(
            seqs(
                db.read_session_messages(
                    &filters(&|f| {
                        f.offset = 1;
                        f.limit = 2;
                    }),
                    MessageOrder::OldestFirst
                )
                .unwrap()
            ),
            vec![1, 2]
        );
    }

    #[test]
    fn read_session_messages_requires_a_session_id() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        // Without a session_id the newest-first direction is undefined (seq is session-local).
        assert!(db
            .read_session_messages(&MessageFilters::default(), MessageOrder::NewestFirst)
            .is_err());
    }

    #[test]
    fn read_session_messages_edge_cases_from_the_premortem_catalog() {
        // Covers failure modes F6-F14 from
        // notes/2026_07_20_2230_read_capability_premortem_and_failure_modes.md.
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute(
                "insert into sessions (id, provider, provider_session_id, cwd, repo_root, \
                 preview_text, source_path, parse_version, discovery_source) \
                 values ('claude:s','claude','s','/p','/p','','/p','1','test')",
                [],
            )
            .unwrap();
        // A single-message session to exercise F14 in isolation.
        db.conn
            .execute(
                "insert into sessions (id, provider, provider_session_id, cwd, repo_root, \
                 preview_text, source_path, parse_version, discovery_source) \
                 values ('claude:one','claude','one','/p','/p','','/p','1','test')",
                [],
            )
            .unwrap();
        db.conn
            .execute(
                "insert into messages (session_id, provider, seq, role, content) \
                 values ('claude:one','claude',0,'user','only turn')",
                [],
            )
            .unwrap();
        for seq in 0..6 {
            db.conn
                .execute(
                    "insert into messages (session_id, provider, seq, role, content) \
                     values ('claude:s','claude',?1,'user',?2)",
                    params![seq, format!("turn {seq}")],
                )
                .unwrap();
        }
        let seqs = |hits: Vec<MessageHit>| hits.iter().map(|h| h.seq).collect::<Vec<i64>>();
        let f = |mutate: &dyn Fn(&mut MessageFilters)| {
            let mut m = MessageFilters {
                session_id: Some("claude:s".to_string()),
                ..Default::default()
            };
            mutate(&mut m);
            m
        };

        // F7: an inclusive range includes BOTH endpoints exactly.
        assert_eq!(
            seqs(
                db.read_session_messages(
                    &f(&|m| {
                        m.seq_from = Some(1);
                        m.seq_to = Some(3);
                    }),
                    MessageOrder::OldestFirst
                )
                .unwrap()
            ),
            vec![1, 2, 3]
        );
        // F11: range then limit — newest 2 WITHIN [1,4] is [3,4], still chronological.
        assert_eq!(
            seqs(
                db.read_session_messages(
                    &f(&|m| {
                        m.seq_from = Some(1);
                        m.seq_to = Some(4);
                        m.limit = 2;
                    }),
                    MessageOrder::NewestFirst
                )
                .unwrap()
            ),
            vec![3, 4]
        );
        // F11 (oldest side): first 2 within [1,4] is [1,2].
        assert_eq!(
            seqs(
                db.read_session_messages(
                    &f(&|m| {
                        m.seq_from = Some(1);
                        m.seq_to = Some(4);
                        m.limit = 2;
                    }),
                    MessageOrder::OldestFirst
                )
                .unwrap()
            ),
            vec![1, 2]
        );
        // F10: offset skips from the NEWEST edge under NewestFirst (skip seq 5), then limit 2 →
        // [4,3] reversed to chronological [3,4].
        assert_eq!(
            seqs(
                db.read_session_messages(
                    &f(&|m| {
                        m.offset = 1;
                        m.limit = 2;
                    }),
                    MessageOrder::NewestFirst
                )
                .unwrap()
            ),
            vec![3, 4]
        );
        // F9: an offset past the end returns empty, not a panic or wrap.
        assert_eq!(
            seqs(
                db.read_session_messages(&f(&|m| m.offset = 99), MessageOrder::OldestFirst)
                    .unwrap()
            ),
            Vec::<i64>::new()
        );
        // F8: a seq range beyond the max seq returns empty.
        assert_eq!(
            seqs(
                db.read_session_messages(
                    &f(&|m| {
                        m.seq_from = Some(100);
                        m.seq_to = Some(200);
                    }),
                    MessageOrder::OldestFirst
                )
                .unwrap()
            ),
            Vec::<i64>::new()
        );
        // F6: from>to is rejected at the DB layer too (MessageFilters::validate), not silently
        // returned as empty — so the same invalid range fails the same way through every surface.
        assert!(db
            .read_session_messages(
                &f(&|m| {
                    m.seq_from = Some(4);
                    m.seq_to = Some(1);
                }),
                MessageOrder::OldestFirst
            )
            .is_err());
        // F13: a role with no matches is empty, not misleading.
        assert_eq!(
            seqs(
                db.read_session_messages(
                    &f(&|m| m.role = Some(Role::Assistant)),
                    MessageOrder::NewestFirst
                )
                .unwrap()
            ),
            Vec::<i64>::new()
        );
        // F14: a single-message session returns that one row for both directions.
        let one = |order| {
            db.read_session_messages(
                &MessageFilters {
                    session_id: Some("claude:one".to_string()),
                    ..Default::default()
                },
                order,
            )
            .unwrap()
        };
        assert_eq!(seqs(one(MessageOrder::OldestFirst)), vec![0]);
        assert_eq!(seqs(one(MessageOrder::NewestFirst)), vec![0]);
    }

    #[test]
    fn path_prefix_matches_directory_boundary_and_escapes_like_metacharacters() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let session = |id: &str, cwd: &str| {
            db.conn
                .execute(
                    "insert into sessions (id, provider, provider_session_id, cwd, repo_root, \
                     preview_text, source_path, parse_version, discovery_source) \
                     values (?1,'claude',?1,?2,?2,'','/p','1','test')",
                    params![id, cwd],
                )
                .unwrap();
        };
        session("root", "/tmp/proj");
        session("child", "/tmp/proj/sub");
        session("sibling", "/tmp/project2");
        session("under", "/tmp/proj_under");
        session("percent", "/tmp/proj%literal");
        let msg = |id: i64, sid: &str| {
            db.conn
                .execute(
                    "insert into messages (id, session_id, provider, seq, role, content) \
                     values (?1,?2,'claude',0,'user','needle')",
                    params![id, sid],
                )
                .unwrap();
        };
        msg(1, "root");
        msg(2, "child");
        msg(3, "sibling");
        msg(4, "under");
        msg(5, "percent");

        let ids = |prefix: &str| -> Vec<String> {
            let mut ids: Vec<String> = db
                .search_messages(
                    "needle",
                    &MessageFilters {
                        path_prefix: Some(prefix.into()),
                        ..Default::default()
                    },
                )
                .unwrap()
                .into_iter()
                .map(|h| h.session_id)
                .collect();
            ids.sort();
            ids
        };

        assert_eq!(ids("/tmp/proj"), vec!["child", "root"]);
        assert_eq!(ids("/tmp/proj%literal"), vec!["percent"]);

        session("windows-root", r"C:\Users\x\proj");
        session("windows-child", r"C:\Users\x\proj\sub");
        session("windows-sibling", r"C:\Users\x\project2");
        msg(6, "windows-root");
        msg(7, "windows-child");
        msg(8, "windows-sibling");
        assert_eq!(
            ids(r"C:\Users\x\proj"),
            vec!["windows-child", "windows-root"]
        );
    }

    #[test]
    fn list_recent_returns_newest_sessions_in_exact_directory_or_descendants() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions (
                     id, provider, provider_session_id, cwd, updated_at, preview_text,
                     source_path, parse_version, discovery_source
                 ) values
                   ('claude:root-old', 'claude', 'root-old', '/work/project',
                    '2026-01-01T00:00:00+00:00', '', '/root-old', 'v1', 'test'),
                   ('claude:child-new', 'claude', 'child-new', '/work/project/sub/dir',
                    '2026-03-01T00:00:00+00:00', '', '/child-new', 'v1', 'test'),
                   ('claude:sibling-newer', 'claude', 'sibling-newer', '/work/project-other',
                    '2026-04-01T00:00:00+00:00', '', '/sibling-newer', 'v1', 'test');",
            )
            .unwrap();

        let query = |limit| SearchFilters {
            path_prefix: Some("/work/project".to_string()),
            limit,
            ..SearchFilters::default()
        };
        assert_eq!(
            db.list_recent(&query(1))
                .unwrap()
                .into_iter()
                .map(|session| session.id)
                .collect::<Vec<_>>(),
            ["claude:child-new"],
            "limit applies after exact-directory/descendant filtering and newest-first ordering"
        );
        assert_eq!(
            db.list_recent(&query(0))
                .unwrap()
                .into_iter()
                .map(|session| session.id)
                .collect::<Vec<_>>(),
            ["claude:child-new", "claude:root-old"]
        );
    }

    #[test]
    fn restricted_fuzzy_search_scores_only_authorized_messages() {
        use crate::config::{SearchScopeConfig, SearchScopeMode};
        use crate::search_scope::{EffectiveAccessScope, TrustedAccessInputs};

        let dir = tempfile::tempdir().unwrap();
        let allowed = dir.path().join("allowed");
        let hidden = dir.path().join("hidden");
        fs::create_dir_all(&allowed).unwrap();
        fs::create_dir_all(&hidden).unwrap();
        let mut db = Db::open(&dir.path().join("index.db")).unwrap();
        db.mark_schema_current().unwrap();
        let transaction = db.conn.unchecked_transaction().unwrap();
        {
            let mut insert_session = transaction
                .prepare(
                    "insert into sessions (
                         id, provider, provider_session_id, cwd, repo_root, preview_text,
                         source_path, parse_version, discovery_source
                     ) values (?, 'claude', ?, ?, ?, '', '/fixture', '1', 'test')",
                )
                .unwrap();
            let mut insert_message = transaction
                .prepare(
                    "insert into messages (
                         id, session_id, provider, seq, role, kind, content
                     ) values (?, ?, 'claude', 0, 'user', 'conversation', 'needle')",
                )
                .unwrap();
            for index in 0..1_201_i64 {
                let id = format!("hidden-{index:04}");
                let workspace = hidden.to_string_lossy();
                insert_session
                    .execute(params![id, id, workspace.as_ref(), workspace.as_ref()])
                    .unwrap();
                insert_message.execute(params![index + 1, id]).unwrap();
            }
            let allowed_id = "allowed";
            let workspace = allowed.to_string_lossy();
            insert_session
                .execute(params![
                    allowed_id,
                    allowed_id,
                    workspace.as_ref(),
                    workspace.as_ref()
                ])
                .unwrap();
            insert_message
                .execute(params![1_202_i64, allowed_id])
                .unwrap();
        }
        transaction.commit().unwrap();

        db.set_access_scope(
            EffectiveAccessScope::resolve(
                &SearchScopeConfig {
                    mode: SearchScopeMode::AllowedRoots,
                    roots: vec![allowed.to_string_lossy().into_owned()],
                    include_invocation_directory: false,
                },
                TrustedAccessInputs::default(),
            )
            .unwrap(),
        );
        let hits = db
            .search_messages(
                "needle",
                &MessageFilters {
                    match_mode: MessageSearchMode::Fuzzy,
                    limit: 1,
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(hits.len(), 1);
        assert_eq!(hits[0].session_id, "allowed");
    }

    #[test]
    fn exact_session_filter_does_not_merge_substring_matches() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        for id in ["abc", "xabcx"] {
            db.conn
                .execute(
                    "insert into sessions (id, provider, provider_session_id, preview_text, \
                     source_path, parse_version, discovery_source) \
                     values (?1,'claude',?1,'','/p','1','test')",
                    params![id],
                )
                .unwrap();
        }
        db.conn
            .execute(
                "insert into messages (id, session_id, provider, seq, role, content) \
                 values (1,'abc','claude',0,'user','same')",
                [],
            )
            .unwrap();
        db.conn
            .execute(
                "insert into messages (id, session_id, provider, seq, role, content) \
                 values (2,'xabcx','claude',0,'user','same')",
                [],
            )
            .unwrap();

        let exact = db
            .search_messages(
                "",
                &MessageFilters {
                    session_id: Some("abc".into()),
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(exact.len(), 1);
        assert_eq!(exact[0].session_id, "abc");
    }

    #[test]
    fn open_with_busy_timeout_sets_sqlite_busy_timeout() {
        let dir = tempfile::tempdir().unwrap();
        let db =
            Db::open_with_busy_timeout(&dir.path().join("index.db"), TEST_BUSY_TIMEOUT_MS).unwrap();
        assert_eq!(db.busy_timeout_ms().unwrap(), TEST_BUSY_TIMEOUT_MS);
    }

    #[test]
    fn scoped_busy_timeout_restores_previous_value() {
        let dir = tempfile::tempdir().unwrap();
        let db =
            Db::open_with_busy_timeout(&dir.path().join("index.db"), TEST_BUSY_TIMEOUT_MS).unwrap();
        let observed = db
            .with_busy_timeout_ms(TEST_NO_WAIT_BUSY_TIMEOUT_MS, || db.busy_timeout_ms())
            .unwrap();
        assert_eq!(observed, TEST_NO_WAIT_BUSY_TIMEOUT_MS);
        assert_eq!(db.busy_timeout_ms().unwrap(), TEST_BUSY_TIMEOUT_MS);
    }

    #[test]
    fn sqlite_busy_error_detection_matches_locked_writer() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("index.db");
        let writer = Db::open(&path).unwrap();
        let contender = Db::open_with_busy_timeout(&path, TEST_NO_WAIT_BUSY_TIMEOUT_MS).unwrap();

        writer.conn.execute_batch("begin immediate").unwrap();
        let err = contender
            .conn
            .execute(
                "insert into sessions (id, provider, provider_session_id, preview_text, \
                 source_path, parse_version, discovery_source) \
                 values ('busy','claude','busy','','/p','1','test')",
                [],
            )
            .unwrap_err();
        let err = anyhow::Error::from(err);
        assert!(Db::is_sqlite_busy_error(&err));
        writer.conn.execute_batch("rollback").unwrap();
    }

    #[test]
    fn auto_reindex_completion_timestamp_controls_shared_freshness_window() {
        const COMPLETED_MS: i64 = 20_000;
        const INTERVAL_MS: u64 = 1_000;

        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("index.db");
        let first = Db::open(&path).unwrap();
        let second = Db::open(&path).unwrap();

        assert!(!second
            .auto_reindex_is_fresh_at(COMPLETED_MS, INTERVAL_MS)
            .unwrap());
        let completed_at = Utc.timestamp_millis_opt(COMPLETED_MS).single().unwrap()
            + chrono::Duration::nanoseconds(456_789);
        first.mark_auto_reindex_complete_at(completed_at).unwrap();
        assert_eq!(
            second.auto_reindex_completed_at().unwrap(),
            Some(completed_at)
        );
        assert!(second
            .auto_reindex_is_fresh_at(COMPLETED_MS + 999, INTERVAL_MS)
            .unwrap());
        assert!(!second
            .auto_reindex_is_fresh_at(COMPLETED_MS + 1_000, INTERVAL_MS)
            .unwrap());
    }

    #[test]
    fn auto_reindex_freshness_uses_only_metadata_primary_keys() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.mark_auto_reindex_complete().unwrap();
        let plan = db
            .conn
            .prepare(&format!("explain query plan {AUTO_REINDEX_FRESHNESS_SQL}"))
            .unwrap()
            .query_map(
                params![
                    AUTO_REINDEX_COMPLETED_MS_KEY,
                    AUTO_REINDEX_PARSER_CONTRACT_KEYS[0],
                    AUTO_REINDEX_PARSER_CONTRACT_KEYS[1],
                    AUTO_REINDEX_PARSER_CONTRACT_KEYS[2],
                    AUTO_REINDEX_PARSER_CONTRACT_KEYS[3],
                ],
                |row| row.get::<_, String>(3),
            )
            .unwrap()
            .collect::<rusqlite::Result<Vec<_>>>()
            .unwrap()
            .join("\n");

        assert!(!plan.contains("SCAN"), "{plan}");
        assert_eq!(
            plan.matches("sqlite_autoindex_index_metadata_1").count(),
            5,
            "{plan}"
        );
    }

    #[test]
    fn message_search_filters_by_session_local_seq_range() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        for id in ["claude:s1", "claude:s2"] {
            db.conn
                .execute(
                    "insert into sessions (id, provider, provider_session_id, preview_text, \
                     source_path, parse_version, discovery_source) \
                     values (?1,'claude',?1,'','/p','1','test')",
                    params![id],
                )
                .unwrap();
            for seq in 0..5 {
                db.conn
                    .execute(
                        "insert into messages (session_id, provider, seq, role, content) \
                         values (?1,'claude',?2,'user',?3)",
                        params![id, seq, format!("needle {id} {seq}")],
                    )
                    .unwrap();
            }
        }

        let bounded = db
            .search_messages(
                "needle",
                &MessageFilters {
                    session_id: Some("claude:s1".into()),
                    seq_from: Some(1),
                    seq_to: Some(3),
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(
            bounded.iter().map(|h| h.seq).collect::<Vec<_>>(),
            vec![1, 2, 3]
        );
        assert!(bounded.iter().all(|h| h.session_id == "claude:s1"));

        let open_ended = db
            .search_messages(
                "",
                &MessageFilters {
                    session_id: Some("claude:s2".into()),
                    seq_from: Some(3),
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(
            open_ended.iter().map(|h| h.seq).collect::<Vec<_>>(),
            vec![3, 4]
        );
    }

    #[test]
    fn find_corrections_honors_path_prefix() {
        // Regression: the analytics queries build bespoke SQL, so path_prefix must be applied
        // there too (it was silently ignored until push_path_prefix unified the predicate).
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let session = |id: &str, cwd: &str| {
            db.conn
                .execute(
                    "insert into sessions (id, provider, provider_session_id, cwd, repo_root, \
                     preview_text, source_path, parse_version, discovery_source) \
                     values (?1,'claude',?1,?2,?2,'','/p','1','test')",
                    params![id, cwd],
                )
                .unwrap();
        };
        session("a", "/Users/x/proj-a");
        session("b", "/Users/x/proj-b");
        let user_msg = |id: i64, sid: &str| {
            db.conn
                .execute(
                    "insert into messages (
                         id, session_id, provider, seq, role, content,
                         authorship, record_relation
                     ) values (
                         ?1,?2,'claude',0,'user','that is wrong, please revert',
                         'human','original'
                     )",
                    params![id, sid],
                )
                .unwrap();
        };
        user_msg(1, "a");
        user_msg(2, "b");

        let policies = test_policies(&[("misc", &["wrong"])]);
        let scoped = db
            .find_corrections(
                &policies,
                &MessageFilters {
                    path_prefix: Some("/Users/x/proj-a".into()),
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(
            scoped
                .iter()
                .map(|c| c.session_id.clone())
                .collect::<Vec<_>>(),
            vec!["a"],
            "path_prefix must scope corrections to the matching session"
        );
        // Without the prefix both sessions' corrections surface.
        assert_eq!(
            db.find_corrections(&policies, &MessageFilters::default())
                .unwrap()
                .len(),
            2
        );
    }

    #[test]
    fn analytics_queries_honor_exact_session_id() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let session = |id: &str| {
            db.conn
                .execute(
                    "insert into sessions (id, provider, provider_session_id, preview_text, \
                     source_path, parse_version, discovery_source) \
                     values (?1,'claude',?1,'','/p','1','test')",
                    params![id],
                )
                .unwrap();
        };
        session("s1");
        session("s10");
        let message = |id: i64, sid: &str, seq: i64, role: &str, content: &str| {
            db.conn
                .execute(
                    "insert into messages (
                         id, session_id, provider, seq, role, content,
                         authorship, record_relation
                     ) values (?1,?2,'claude',?3,?4,?5,'human','original')",
                    params![id, sid, seq, role, content],
                )
                .unwrap();
        };
        message(1, "s1", 0, "user", "that is wrong");
        message(2, "s1", 1, "slash", "/cmd-a");
        message(3, "s10", 0, "user", "that is wrong");
        message(4, "s10", 1, "slash", "/cmd-b");

        let filters = MessageFilters {
            session_id: Some("s1".into()),
            ..Default::default()
        };
        let policies = test_policies(&[("misc", &["wrong"])]);
        assert_eq!(
            db.find_corrections(&policies, &filters)
                .unwrap()
                .iter()
                .map(|row| row.session_id.as_str())
                .collect::<Vec<_>>(),
            vec!["s1"],
            "exact session_id must not match s10"
        );
        assert_eq!(
            db.message_role_counts(&filters).unwrap(),
            vec![("slash".to_string(), 1), ("user".to_string(), 1)]
        );
        let planning = db.planning_usage(&filters, &[]).unwrap();
        assert_eq!(planning.len(), 1);
        assert_eq!(planning[0].command, "/cmd-a");
    }

    #[test]
    fn search_messages_filters_by_tool_name_and_surfaces_it() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute(
                "insert into sessions (id, provider, provider_session_id, preview_text, \
                 source_path, parse_version, discovery_source) \
                 values ('s1','claude','s1','','/p','1','test')",
                [],
            )
            .unwrap();
        let insert = |id: i64, seq: i64, role: &str, tool: Option<&str>, content: &str| {
            db.conn
                .execute(
                    "insert into messages (id, session_id, provider, seq, role, tool_name, content) \
                     values (?1,'s1','claude',?2,?3,?4,?5)",
                    params![id, seq, role, tool, content],
                )
                .unwrap();
        };
        insert(1, 0, "user", None, "run the build");
        insert(2, 1, "tool", Some("Bash"), "build ok");
        insert(3, 2, "tool", Some("Edit"), "edited the file");
        insert(4, 3, "tool", Some("ÄTool"), "unicode tool");

        // tool_name is surfaced on the hit.
        let tools = db
            .search_messages(
                "",
                &MessageFilters {
                    role: Some(Role::Tool),
                    ..Default::default()
                },
            )
            .unwrap();
        let bash = tools
            .iter()
            .find(|h| h.seq == 1)
            .expect("Bash tool message");
        assert_eq!(bash.tool_name.as_deref(), Some("Bash"));

        // --tool is a case-insensitive substring filter and never matches NULL-tool rows.
        let only = db
            .search_messages(
                "",
                &MessageFilters {
                    tool: Some("bash".into()),
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(only.len(), 1);
        assert_eq!(only[0].seq, 1);
        let unicode = db
            .search_messages(
                "ät",
                &MessageFilters {
                    field: Some(SearchField::ToolName),
                    limit: 1,
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(unicode.len(), 1);
        assert_eq!(unicode[0].tool_name.as_deref(), Some("ÄTool"));
        db.conn
            .execute_batch(
                "with recursive n(value) as (
                     values(1) union all select value + 1 from n where value < 100
                 )
                 insert into messages (
                     session_id, provider, seq, role, tool_name, content
                 )
                 select 's1', 'claude', 100 + value, 'tool',
                        printf('other_tool_%03d', value), 'unrelated'
                   from n;",
            )
            .unwrap();
        let (fuzzy, explain) = db
            .search_messages_with_explain(
                "edt",
                &MessageFilters {
                    field: Some(SearchField::ToolName),
                    match_mode: MessageSearchMode::Fuzzy,
                    limit: 5,
                    ..Default::default()
                },
                true,
            )
            .unwrap();
        assert_eq!(fuzzy.len(), 1);
        assert_eq!(fuzzy[0].tool_name.as_deref(), Some("Edit"));
        let explain = explain.unwrap();
        assert_eq!(explain.prefilter, None);
        assert_eq!(explain.candidates, Some(1));
        assert_eq!(
            explain.prefilter_skipped.as_deref(),
            Some("complete filtered tool-name vocabulary scored before matching rows are loaded")
        );
        assert!(explain.candidates.unwrap() < explain.corpus);
        let vocabulary_plan = db
            .conn
            .prepare(
                "explain query plan select tool_name from messages
                  where tool_name is not null order by tool_name",
            )
            .unwrap()
            .query_map([], |row| row.get::<_, String>(3))
            .unwrap()
            .collect::<rusqlite::Result<Vec<_>>>()
            .unwrap()
            .join("\n");
        assert!(
            vocabulary_plan.contains("idx_messages_tool_name"),
            "{vocabulary_plan}"
        );
        let none = db
            .search_messages(
                "",
                &MessageFilters {
                    tool: Some("zzz".into()),
                    ..Default::default()
                },
            )
            .unwrap();
        assert!(
            none.is_empty(),
            "unknown tool matches nothing (incl. NULL-tool rows)"
        );
    }

    #[test]
    #[ignore = "deterministic release-mode tool-name vocabulary performance measurement"]
    fn fuzzy_tool_name_vocabulary_benchmark() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions (
                     id, provider, provider_session_id, preview_text, source_path,
                     parse_version, discovery_source
                 ) values ('s1','claude','s1','','/p','1','test')",
            )
            .unwrap();
        let tx = db.conn.unchecked_transaction().unwrap();
        {
            let mut insert = tx
                .prepare(
                    "insert into messages (
                         session_id, provider, seq, role, tool_name, content
                     ) values ('s1', 'claude', ?1, 'tool', ?2, ?3)",
                )
                .unwrap();
            for seq in 0..250_000_i64 {
                let name = if seq % 25_000 == 0 {
                    "exec_command".to_string()
                } else {
                    format!("unrelated_tool_{:03}", seq % 250)
                };
                insert
                    .execute(params![seq, name, "x".repeat(2_048)])
                    .unwrap();
            }
        }
        tx.commit().unwrap();
        let filters = MessageFilters {
            field: Some(SearchField::ToolName),
            match_mode: MessageSearchMode::Fuzzy,
            limit: 20,
            ..Default::default()
        };
        let measure = |optimized: bool| {
            let search = || {
                if optimized {
                    db.search_messages("exec", &filters).unwrap()
                } else {
                    db.search_tool_name_fuzzy_direct_for_test("exec", &filters)
                        .unwrap()
                }
            };
            let expected = serde_json::to_vec(&search()).unwrap();
            let digest = crate::hashing::sha256(&expected);
            let mut elapsed = Vec::new();
            for _ in 0..7 {
                let started = Instant::now();
                assert_eq!(serde_json::to_vec(&search()).unwrap(), expected);
                elapsed.push(started.elapsed().as_micros());
            }
            elapsed.sort_unstable();
            (
                elapsed[elapsed.len() / 2],
                elapsed[elapsed.len() - 1],
                digest,
            )
        };
        let direct = measure(false);
        let optimized = measure(true);
        assert_eq!(direct.2, optimized.2);
        eprintln!(
            "tool_name_vocabulary_benchmark rows=250000 vocabulary=251 direct_median_us={} direct_p95_us={} optimized_median_us={} optimized_p95_us={} digest=sha256:{}",
            direct.0, direct.1, optimized.0, optimized.1, direct.2
        );
    }

    #[test]
    fn global_tool_name_vocabulary_matches_distinct_index_scan() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions (
                     id, provider, provider_session_id, preview_text, source_path,
                     parse_version, discovery_source
                 ) values ('s1','claude','s1','','/p','1','test');
                 insert into messages (
                     session_id, provider, seq, role, tool_name, content
                 ) values
                   ('s1', 'claude', 0, 'tool', 'ÄTool', ''),
                   ('s1', 'claude', 1, 'tool', 'exec_command', ''),
                   ('s1', 'claude', 2, 'tool', 'exec_command', ''),
                   ('s1', 'claude', 3, 'user', null, '');",
            )
            .unwrap();
        let expected = db
            .conn
            .prepare(
                "select distinct tool_name from messages
                  where tool_name is not null order by tool_name",
            )
            .unwrap()
            .query_map([], |row| row.get::<_, String>(0))
            .unwrap()
            .collect::<rusqlite::Result<Vec<_>>>()
            .unwrap();
        assert_eq!(db.global_tool_name_vocabulary().unwrap(), expected);
    }

    #[test]
    fn fuzzy_tool_name_vocabulary_path_matches_direct_row_scoring() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions (
                     id, provider, provider_session_id, preview_text, source_path,
                     parse_version, discovery_source
                 ) values
                   ('s1','claude','s1','','/p','1','test'),
                   ('s2','codex','s2','','/q','1','test');
                 insert into messages (
                     session_id, provider, seq, role, tool_name, content
                 ) values
                   ('s1', 'claude', 0, 'tool', 'exec_command', 'large ignored payload a'),
                   ('s1', 'claude', 1, 'tool', 'Edit', 'large ignored payload b'),
                   ('s1', 'claude', 2, 'tool', 'mcp:memory:execute', 'large ignored payload c'),
                   ('s1', 'claude', 3, 'tool', 'ExecCommand', 'equal-score spelling payload'),
                   ('s2', 'codex', 0, 'tool', 'exec_command', 'large ignored payload d'),
                   ('s2', 'codex', 1, 'tool', 'write_stdin', 'large ignored payload e');",
            )
            .unwrap();
        let filters = MessageFilters {
            field: Some(SearchField::ToolName),
            match_mode: MessageSearchMode::Fuzzy,
            providers: Some(vec![Provider::Claude]),
            limit: 2,
            offset: 1,
            ..Default::default()
        };
        let optimized = db.search_messages("exec", &filters).unwrap();
        let direct = db
            .search_tool_name_fuzzy_direct_for_test("exec", &filters)
            .unwrap();
        assert_eq!(
            optimized
                .iter()
                .map(|hit| (&hit.session_id, hit.seq, hit.fuzzy_score))
                .collect::<Vec<_>>(),
            direct
                .iter()
                .map(|hit| (&hit.session_id, hit.seq, hit.fuzzy_score))
                .collect::<Vec<_>>()
        );
    }

    #[test]
    fn fuzzy_tool_name_searches_the_complete_filtered_vocabulary() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions (
                     id, provider, provider_session_id, preview_text, source_path,
                     parse_version, discovery_source
                 ) values ('s1','claude','s1','','/p','1','test')",
            )
            .unwrap();
        let tx = db.conn.unchecked_transaction().unwrap();
        {
            let mut insert = tx
                .prepare(
                    "insert into messages (
                         session_id, provider, seq, role, tool_name, content
                     ) values ('s1', 'claude', ?1, 'tool', ?2, '')",
                )
                .unwrap();
            for seq in 0..=10_000_usize {
                insert
                    .execute(params![seq as i64, format!("tool_{seq:05}")])
                    .unwrap();
            }
        }
        tx.commit().unwrap();

        db.conn
            .execute(
                "insert into messages (
                     session_id, provider, seq, role, tool_name, content
                 ) values ('s1', 'claude', ?1, 'tool', 'tol', '')",
                params![10_001_i64],
            )
            .unwrap();

        let (hits, explain) = db
            .search_messages_with_explain(
                "tol",
                &MessageFilters {
                    field: Some(SearchField::ToolName),
                    match_mode: MessageSearchMode::Fuzzy,
                    limit: 1,
                    ..Default::default()
                },
                true,
            )
            .unwrap();

        assert_eq!(hits.len(), 1);
        assert_eq!(hits[0].tool_name.as_deref(), Some("tol"));
        let explain = explain.unwrap();
        assert_eq!(explain.corpus, 10_002);
        assert_eq!(explain.candidates, Some(10_002));
    }

    /// A literal or regex tool-name search verifies in SQLite with no prefilter, and its receipt
    /// used to report the rows the caller's page happened to read (`limit + 1` with the CLI's
    /// look-ahead, so `--limit 1` printed `2 / 2 corpus rows`). The receipt now carries the
    /// structural denominator, tool-call and tool-result rows the filters admit, whatever the
    /// page size, and no candidate count because nothing was prefiltered.
    #[test]
    fn tool_name_literal_receipt_reports_the_named_tool_corpus_independent_of_the_page() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions (
                     id, provider, provider_session_id, preview_text, source_path,
                     parse_version, discovery_source
                 ) values ('s1','claude','s1','','/p','1','test');
                 insert into messages (session_id, provider, seq, role, kind, tool_name, content)
                 values ('s1', 'claude', 0, 'tool', 'tool_call', 'exec_command', ''),
                        ('s1', 'claude', 1, 'tool', 'tool_call', 'exec_command', ''),
                        ('s1', 'claude', 2, 'tool', 'tool_call', 'apply_patch', ''),
                        ('s1', 'claude', 3, 'user', 'conversation', null, 'no tool');",
            )
            .unwrap();
        for limit in [1, 2, 10] {
            let (hits, explain) = db
                .search_messages_with_explain(
                    "exec",
                    &MessageFilters {
                        field: Some(SearchField::ToolName),
                        limit,
                        ..Default::default()
                    },
                    true,
                )
                .unwrap();
            assert_eq!(hits.len(), 2.min(limit));
            let explain = explain.unwrap();
            assert_eq!(
                explain.corpus, 3,
                "limit {limit}: the denominator is every named-tool row the filters admit"
            );
            assert_eq!(explain.candidates, None, "nothing was prefiltered");
            assert!(explain.prefilter_skipped.is_some());
        }
    }

    /// Every fuzzy scoring batch is bounded by rows and by bytes; the content path used to be
    /// bounded by rows alone, so 512 megabyte-sized tool results were held before scoring.
    #[test]
    fn fuzzy_batches_score_at_the_row_cap_or_the_byte_cap_whichever_comes_first() {
        assert!(fuzzy_batch_is_full(FUZZY_SCORE_BATCH_SIZE, 0));
        assert!(fuzzy_batch_is_full(3, FUZZY_BATCH_BYTES));
        assert!(fuzzy_batch_is_full(3, FUZZY_BATCH_BYTES + 1));
        assert!(!fuzzy_batch_is_full(
            FUZZY_SCORE_BATCH_SIZE - 1,
            FUZZY_BATCH_BYTES - 1
        ));
        assert!(!fuzzy_batch_is_full(1, 1));
    }

    /// `offset` is caller input on every surface and no schema caps it. The ranked page
    /// (`offset + limit` rows) must be retained memory proportional to rows actually found, never
    /// a reservation sized by the request: `Vec::with_capacity(offset + limit)` panicked with
    /// "capacity overflow" at `--offset 100000000000000000` (CLI, and inside the MCP worker) and
    /// asked the allocator for ~150 GB at `--offset 1000000000` before that.
    #[test]
    fn fuzzy_tool_name_offset_beyond_the_corpus_returns_empty_without_reserving_the_offset() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions (
                     id, provider, provider_session_id, preview_text, source_path,
                     parse_version, discovery_source
                 ) values ('s1','claude','s1','','/p','1','test');
                 insert into messages (session_id, provider, seq, role, tool_name, content)
                 values ('s1', 'claude', 0, 'tool', 'exec_command', '');",
            )
            .unwrap();
        for offset in [100_000_000_000_000_000_usize, 1_000_000_000] {
            let hits = db
                .search_messages(
                    "exec",
                    &MessageFilters {
                        field: Some(SearchField::ToolName),
                        match_mode: MessageSearchMode::Fuzzy,
                        limit: 1,
                        offset,
                        ..Default::default()
                    },
                )
                .unwrap();
            assert!(hits.is_empty(), "offset {offset} lies past the only row");
        }
    }

    /// A fuzzy window past the eligible corpus is answered from the index, without scoring a row.
    ///
    /// `offset + limit` is the retention target for fuzzy ranking, and `retain_top_fuzzy_hits`
    /// truncates only above it. An offset larger than any corpus therefore made the target
    /// unreachable: every matching row stayed in memory with its content until `skip(offset)`
    /// threw all of it away. The receipt is the observable proof that no scoring happened —
    /// `candidates` counts rows that scored, and it is absent rather than a zero that would read
    /// as "the corpus was scored and nothing matched".
    #[test]
    fn a_fuzzy_window_past_the_corpus_is_answered_without_scoring_any_row() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions (
                     id, provider, provider_session_id, preview_text, source_path,
                     parse_version, discovery_source
                 ) values ('s1','claude','s1','','/p','1','test');",
            )
            .unwrap();
        for seq in 0..4 {
            db.conn
                .execute(
                    "insert into messages (session_id, provider, seq, role, tool_name, content) \
                     values ('s1', 'claude', ?, 'tool', 'exec_command', 'exec command output')",
                    [seq],
                )
                .unwrap();
        }

        for field in [
            None,
            Some(SearchField::ToolName),
            Some(SearchField::Content),
        ] {
            let filters = |offset: usize| MessageFilters {
                field,
                match_mode: MessageSearchMode::Fuzzy,
                limit: 2,
                offset,
                ..Default::default()
            };

            // Past the corpus: empty page, exact corpus, and nothing scored. The offset is above
            // FUZZY_SCORE_BATCH_SIZE, which is what makes the window worth bounding.
            let (hits, explain) = db
                .search_messages_with_explain("exec", &filters(1_000_000_000), true)
                .unwrap();
            assert!(hits.is_empty(), "{field:?}");
            let explain = explain.expect("an explained request returns a receipt");
            assert_eq!(explain.corpus, 4, "{field:?}");
            assert_eq!(
                explain.candidates, None,
                "{field:?}: no row scored, so no candidate count was measured"
            );

            // Inside the corpus the page and its receipt are unchanged by the bound.
            let (hits, explain) = db
                .search_messages_with_explain("exec", &filters(0), true)
                .unwrap();
            assert_eq!(hits.len(), 2, "{field:?}");
            assert_eq!(
                explain.expect("receipt").candidates,
                Some(4),
                "{field:?}: every row scored"
            );
        }
    }

    /// The last row inside the corpus is returned, and the first offset past it is not.
    ///
    /// [`Db::fuzzy_ranking_window`] answers a page from the count when `offset >= corpus`, and the
    /// two offsets either side of that comparison are where an off-by-one would flip: one row
    /// silently dropped from the end of a deep page, or an empty page reported as scored. The
    /// existing coverage uses offset zero and an offset far past any corpus, so both sit well away
    /// from the boundary. The window is only measured when the requested page exceeds one scoring
    /// batch, which is what the large limit is for.
    #[test]
    fn the_fuzzy_window_boundary_keeps_the_last_row_and_drops_the_first_one_past_it() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions (
                     id, provider, provider_session_id, preview_text, source_path,
                     parse_version, discovery_source
                 ) values ('s1','claude','s1','','/p','1','test');",
            )
            .unwrap();
        let corpus = 4_usize;
        // `seq` is a SQLite integer column: bind the width SQLite stores, which rusqlite 0.40
        // no longer infers from usize.
        for seq in 0..corpus as i64 {
            db.conn
                .execute(
                    "insert into messages (session_id, provider, seq, role, content) \
                     values ('s1', 'claude', ?, 'user', 'exec command output')",
                    [seq],
                )
                .unwrap();
        }

        let filters = |offset: usize| MessageFilters {
            match_mode: MessageSearchMode::Fuzzy,
            limit: FUZZY_SCORE_BATCH_SIZE + 100,
            offset,
            ..Default::default()
        };

        // The last offset inside the corpus still yields its one remaining row, scored.
        let (hits, explain) = db
            .search_messages_with_explain("exec", &filters(corpus - 1), true)
            .unwrap();
        assert_eq!(hits.len(), 1, "the last row is inside the corpus");
        assert_eq!(explain.expect("receipt").candidates, Some(corpus as i64));

        // The first offset past it is answered from the count, with nothing scored.
        let (hits, explain) = db
            .search_messages_with_explain("exec", &filters(corpus), true)
            .unwrap();
        assert!(hits.is_empty(), "one past the last row is an empty page");
        let explain = explain.expect("receipt");
        assert_eq!(explain.corpus, corpus as i64);
        assert_eq!(
            explain.candidates, None,
            "an empty page from the count scored no row"
        );
    }

    /// A literal search finds Greek text ending in sigma, whichever spelling either side uses.
    ///
    /// End to end rather than at the matcher: the query needle, the trigram candidate selection,
    /// and the SQL scalar that verifies each candidate all have to agree about sigma, and each was
    /// reached by a different route. The needle was lowered as a whole string, which turns a
    /// word-final `Σ` into `ς`, while the scalar folded the stored text one character at a time
    /// into `σ` — so a search for a word could return nothing for the message holding that word.
    #[test]
    fn a_literal_search_finds_greek_text_ending_in_sigma() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions (
                     id, provider, provider_session_id, preview_text, source_path,
                     parse_version, discovery_source
                 ) values ('s1','claude','s1','','/p','1','test');
                 insert into messages (session_id, provider, seq, role, kind, content)
                 values ('s1','claude',0,'user','message','η ΟΔΟΣΣ που ψαχνω'),
                        ('s1','claude',1,'user','message','η οδοσς που ψαχνω επισης');",
            )
            .unwrap();

        // Every spelling of the word selects both rows: the uppercase text, and the lowercase text
        // whose sigma is written in its word-final form.
        for query in ["ΟΔΟΣΣ", "οδοσς", "οδοσσ"] {
            let hits = db
                .search_messages(
                    query,
                    &MessageFilters {
                        match_mode: MessageSearchMode::Literal,
                        limit: 10,
                        ..Default::default()
                    },
                )
                .unwrap();
            assert_eq!(hits.len(), 2, "query {query:?} finds both spellings");
        }
    }

    /// A database on the pre-v4 layout finds that same Greek text.
    ///
    /// Schema versions below 4 have no FTS5 trigram table and select candidates from the custom
    /// [`crate::trigram_index`] instead. That index tokenizes a document with
    /// [`str::to_lowercase`], which writes a word-final `Σ` as `ς`, while the verifier folds every
    /// sigma onto `σ`. A query spelled with the other sigma then asks for a trigram no document
    /// holds, and a row the verifier would accept never becomes a candidate — a prefilter narrowing
    /// the result set instead of widening it, which is the one thing it may never do.
    #[test]
    fn a_pre_v4_literal_search_finds_greek_text_ending_in_sigma() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        enable_v3_custom_trigram_compatibility(&db);
        seed_messages(
            &db,
            &[
                ("user", "η ΟΔΟΣΣ που ψαχνω"),
                ("user", "η οδοσς που ψαχνω επισης"),
            ],
        );

        for query in ["ΟΔΟΣΣ", "οδοσς", "οδοσσ"] {
            let (hits, explain) = db
                .search_messages_with_explain(
                    query,
                    &MessageFilters {
                        match_mode: MessageSearchMode::Literal,
                        limit: 10,
                        ..Default::default()
                    },
                    true,
                )
                .unwrap();
            assert_eq!(hits.len(), 2, "query {query:?} finds both spellings");
            // Both rows come back because the scan reached the verifier, rather than because the
            // index happened to hold the spelling that was asked for: the receipt names the skip.
            let explain = explain.expect("receipt");
            assert_eq!(explain.prefilter, None, "query {query:?} indexed nothing");
            assert!(
                explain
                    .prefilter_skipped
                    .as_deref()
                    .is_some_and(|reason| reason.contains("sigma")),
                "query {query:?} reports why it scanned: {:?}",
                explain.prefilter_skipped
            );
        }
    }

    /// A tool-argument window is bounded by the tool-call rows, not by every message.
    ///
    /// [`Db::fuzzy_ranking_window`] takes the base predicate so that "each caller measures the rows
    /// it actually scans". The tool-argument scan restricts itself to `kind = 'tool_call'` but
    /// passed `1 = 1` to the window, so a corpus of ordinary conversation rows sized the retention
    /// bound and the receipt. A caller reading `corpus` then divides by a denominator the searched
    /// field never had, and an offset already past every tool argument still looked like it landed
    /// inside the corpus.
    #[test]
    fn a_tool_argument_window_counts_only_tool_call_rows() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions (
                     id, provider, provider_session_id, preview_text, source_path,
                     parse_version, discovery_source
                 ) values ('s1','claude','s1','','/p','1','test');
                 insert into messages (session_id, provider, seq, role, kind, tool_name, content)
                 values ('s1','claude',0,'tool','tool_call','exec_command','{\"args\":{\"cmd\":\"needle\"}}');
                 insert into messages (session_id, provider, seq, role, kind, content)
                 values ('s1','claude',1,'user','message','needle in ordinary prose'),
                        ('s1','claude',2,'assistant','message','needle again'),
                        ('s1','claude',3,'user','message','needle once more');",
            )
            .unwrap();

        let filters = |offset: usize| MessageFilters {
            field: Some(SearchField::ToolArgument),
            argument_path: Some("/cmd".to_string()),
            match_mode: MessageSearchMode::Fuzzy,
            limit: 1,
            offset,
            ..Default::default()
        };

        // One tool call carries an argument; the three ordinary rows are not tool arguments at all.
        let (hits, explain) = db
            .search_messages_with_explain("needle", &filters(0), true)
            .unwrap();
        assert_eq!(hits.len(), 1, "only the tool call has an argument");
        assert_eq!(
            explain.expect("receipt").corpus,
            1,
            "corpus is the rows the searched field admits"
        );

        // An offset past the only tool argument is answered from the count, with nothing scored.
        let (hits, explain) = db
            .search_messages_with_explain("needle", &filters(1_000_000_000), true)
            .unwrap();
        assert!(hits.is_empty());
        let explain = explain.expect("an explained request returns a receipt");
        assert_eq!(explain.corpus, 1, "ordinary rows are not tool arguments");
        assert_eq!(
            explain.candidates, None,
            "no row scored, so no candidate count was measured"
        );
    }

    /// An empty result describes itself the same way whatever page size asked for it.
    ///
    /// The past-corpus check compared `offset >= corpus`, and `0 >= 0` holds, so a filter matching
    /// no rows took the past-corpus path whenever `offset + limit` exceeded one scoring batch. Two
    /// requests differing only in `limit` then returned different receipt shapes for the same empty
    /// result, and the larger one blamed an offset that is zero and dropped `candidates` — the
    /// count readers divide by `corpus` to get selectivity.
    #[test]
    fn an_empty_corpus_reports_the_same_receipt_whatever_the_page_size() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();

        let receipt = |limit: usize| {
            let (hits, explain) = db
                .search_messages_with_explain(
                    "anything",
                    &MessageFilters {
                        match_mode: MessageSearchMode::Fuzzy,
                        limit,
                        ..Default::default()
                    },
                    true,
                )
                .unwrap();
            assert!(hits.is_empty(), "limit {limit}");
            explain.expect("an explained request returns a receipt")
        };

        // One page size stays under the scoring batch and the other exceeds it, which is what
        // decides whether the corpus is counted up front at all.
        let small = receipt(100);
        let large = receipt(FUZZY_SCORE_BATCH_SIZE + 1);
        assert_eq!(small.corpus, 0);
        assert_eq!(large.corpus, 0);
        assert_eq!(small.candidates, Some(0));
        assert_eq!(
            large.candidates, small.candidates,
            "an empty corpus scored nothing either way; the count is 0, not absent"
        );
        assert_eq!(large.prefilter_skipped, small.prefilter_skipped);
    }

    #[test]
    fn date_filter_until_covers_sub_second_tail_of_final_second() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute(
                "insert into sessions (id, provider, provider_session_id, preview_text, \
                 source_path, parse_version, discovery_source) \
                 values ('s1','claude','s1','','/p','1','test')",
                [],
            )
            .unwrap();
        // A message stored with sub-second precision in the final second of 2026-01-15.
        db.conn
            .execute(
                "insert into messages (id, session_id, provider, seq, role, ts, content) \
                 values (1,'s1','claude',0,'user','2026-01-15T23:59:59.123456789+00:00','late')",
                [],
            )
            .unwrap();
        let until =
            crate::dates::parse_bound("2026-01-15", crate::dates::Bound::End, Utc::now()).unwrap();
        let hits = db
            .search_messages(
                "",
                &MessageFilters {
                    until: Some(until),
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(
            hits.len(),
            1,
            "an inclusive --until must cover sub-second timestamps in its final second"
        );
    }

    #[test]
    fn date_filter_preserves_exact_fractional_upper_bound() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute(
                "insert into sessions (id, provider, provider_session_id, preview_text, \
                 source_path, parse_version, discovery_source) \
                 values ('s1','claude','s1','','/p','1','test')",
                [],
            )
            .unwrap();
        for (id, seq, ts) in [
            (1, 0, "2026-07-07T02:53:22.357999999+00:00"),
            (2, 1, "2026-07-07T02:53:22.358000000+00:00"),
            (3, 2, "2026-07-07T02:53:22.358000001+00:00"),
        ] {
            db.conn
                .execute(
                    "insert into messages (id, session_id, provider, seq, role, ts, content) \
                     values (?1,'s1','claude',?2,'user',?3,'event')",
                    rusqlite::params![id, seq, ts],
                )
                .unwrap();
        }
        let until = crate::dates::parse_bound(
            "2026-07-07T02:53:22.358Z",
            crate::dates::Bound::End,
            Utc::now(),
        )
        .unwrap();
        let hits = db
            .search_messages(
                "",
                &MessageFilters {
                    until: Some(until),
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(
            hits.iter().map(|hit| hit.seq).collect::<Vec<_>>(),
            vec![0, 1],
            "an exact fractional --until must exclude later events in the same second"
        );
    }

    #[test]
    fn date_filter_keeps_messages_with_unknown_timestamp() {
        use chrono::TimeZone;
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute(
                "insert into sessions (id, provider, provider_session_id, preview_text, \
                 source_path, parse_version, discovery_source) \
                 values ('s1','claude','s1','','/p','1','test')",
                [],
            )
            .unwrap();
        // A message whose timestamp is unknown (NULL) — e.g. a provider/record with no ts.
        db.conn
            .execute(
                "insert into messages (id, session_id, provider, seq, role, ts, content) \
                 values (1,'s1','claude',0,'user',NULL,'undated correction')",
                [],
            )
            .unwrap();
        let since = Utc.with_ymd_and_hms(2026, 1, 1, 0, 0, 0).single().unwrap();
        let until = Utc
            .with_ymd_and_hms(2026, 12, 31, 23, 59, 59)
            .single()
            .unwrap();
        let hits = db
            .search_messages(
                "zebracode",
                &MessageFilters {
                    since: Some(since),
                    until: Some(until),
                    ..Default::default()
                },
            )
            .unwrap();
        assert!(
            hits.is_empty(),
            "a NULL-timestamp message must not match every date filter; index a fallback timestamp instead"
        );
    }

    #[test]
    fn session_search_zero_is_unlimited_and_large_limit_does_not_overflow() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        for id in ["s1", "s2"] {
            db.conn
                .execute(
                    "insert into sessions (id, provider, provider_session_id, preview_text, \
                     source_path, parse_version, discovery_source) \
                     values (?1,'claude',?1,'alpha preview',?2,'1','test')",
                    params![id, format!("/{id}.jsonl")],
                )
                .unwrap();
        }

        let scoring = crate::config::ScoringConfig::default();
        let mut filters = SearchFilters::default();

        assert_eq!(
            db.search("alpha", &filters, None, &scoring).unwrap().len(),
            2
        );

        filters.limit = 1;
        assert_eq!(
            db.search("alpha", &filters, None, &scoring).unwrap().len(),
            1
        );

        filters.limit = usize::MAX;
        assert_eq!(
            db.search("alpha", &filters, None, &scoring).unwrap().len(),
            2
        );
    }

    #[test]
    fn session_search_requires_a_text_match_before_ranking_bonuses() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute(
                "insert into sessions (
                     id, provider, provider_session_id, cwd, repo_root, preview_text,
                     source_path, updated_at, parse_version, discovery_source
                 ) values ('s1','claude','s1','/repo','/repo','ordinary text','/p',?1,'1','test')",
                params![Utc::now().to_rfc3339()],
            )
            .unwrap();

        let hits = db
            .search(
                "⸘⸘⸘",
                &SearchFilters::default(),
                Some("/repo"),
                &crate::config::ScoringConfig::default(),
            )
            .unwrap();

        assert!(
            hits.is_empty(),
            "recency and repository bonuses must not admit an unrelated session"
        );
    }

    #[test]
    fn session_search_combines_query_term_coverage_across_one_session() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute(
                "insert into sessions (
                     id, provider, provider_session_id, title, summary, preview_text,
                     source_path, parse_version, discovery_source
                 ) values ('s1','claude','s1','alpha','beta','','/p','1','test')",
                [],
            )
            .unwrap();
        let scoring = crate::config::ScoringConfig {
            title_score: 0,
            summary_score: 0,
            path_score: 0,
            preview_score: 0,
            other_score: 0,
            token_bonus: 0,
            all_tokens_bonus: 150,
            recency_weight: 0,
            current_repo_bonus: 0,
            ..Default::default()
        };

        let hits = db
            .search("alpha beta", &SearchFilters::default(), None, &scoring)
            .unwrap();

        assert_eq!(hits.len(), 1);
        assert_eq!(hits[0].session.id, "s1");
        assert_eq!(hits[0].score, 150);
    }

    #[test]
    fn session_search_positive_limit_is_a_prefix_of_unlimited_ranking() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        for (id, title, preview) in [("s1", "", "alpha"), ("s2", "alpha", "")] {
            db.conn
                .execute(
                    "insert into sessions (
                         id, provider, provider_session_id, title, preview_text,
                         source_path, parse_version, discovery_source
                     ) values (?1,'claude',?1,?2,?3,?4,'1','test')",
                    params![id, title, preview, format!("/{id}.jsonl")],
                )
                .unwrap();
        }
        let scoring = crate::config::ScoringConfig {
            recency_weight: 0,
            ..Default::default()
        };
        let all_filters = SearchFilters {
            limit: 0,
            ..Default::default()
        };
        let all = db.search("alpha", &all_filters, None, &scoring).unwrap();
        let one_filter = SearchFilters {
            limit: 1,
            ..all_filters
        };
        let one = db.search("alpha", &one_filter, None, &scoring).unwrap();

        assert_eq!(one.len(), 1);
        assert_eq!(one[0].session.id, all[0].session.id);
        assert_eq!(one[0].session.id, "s2");
    }

    #[test]
    fn session_search_uses_the_application_worker_runtime_without_changing_ranking() {
        let root = tempfile::tempdir().unwrap();
        let one = Db::open_with_threads(
            &root.path().join("one.db"),
            TEST_BUSY_TIMEOUT_MS,
            NonZeroUsize::new(1).unwrap(),
        )
        .unwrap();
        let four = Db::open_with_threads(
            &root.path().join("four.db"),
            TEST_BUSY_TIMEOUT_MS,
            NonZeroUsize::new(4).unwrap(),
        )
        .unwrap();
        for db in [&one, &four] {
            for index in 0..1_100 {
                let id = format!("s{index:04}");
                db.conn
                    .execute(
                        "insert into sessions (
                             id, provider, provider_session_id, title, summary, cwd, repo_root,
                             preview_text, source_path, updated_at, parse_version, discovery_source
                         ) values (?1, 'claude', ?1, ?2, ?3, ?4, ?4, ?5, ?6, ?7, '1', 'test')",
                        params![
                            id,
                            (index % 7 == 0).then_some("database migration"),
                            format!("summary {index}"),
                            format!("/repo/{index}"),
                            format!("preview database work item {index}"),
                            format!("/{index}.jsonl"),
                            format!("2026-01-{:02}T00:00:00Z", index % 28 + 1),
                        ],
                    )
                    .unwrap();
                db.conn
                    .execute(
                        "insert into transcripts(session_id, transcript_text) values (?1, ?2)",
                        params![
                            format!("s{index:04}"),
                            format!(
                                "transcript {index} discusses database schema migration planning"
                            )
                        ],
                    )
                    .unwrap();
            }
        }
        let filters = SearchFilters {
            limit: 40,
            ..Default::default()
        };
        let scoring = crate::config::ScoringConfig {
            recency_weight: 0,
            ..Default::default()
        };
        let identities = |hits: Vec<SearchHit>| {
            hits.into_iter()
                .map(|hit| {
                    (
                        hit.session.id,
                        hit.score,
                        hit.match_source,
                        hit.match_snippet,
                    )
                })
                .collect::<Vec<_>>()
        };
        assert_eq!(one.worker_pool_build_count(), 0);
        assert_eq!(four.worker_pool_build_count(), 0);
        let expected = identities(
            one.search("databse migraton", &filters, Some("/repo/7"), &scoring)
                .unwrap(),
        );
        let actual = identities(
            four.search("databse migraton", &filters, Some("/repo/7"), &scoring)
                .unwrap(),
        );
        assert_eq!(
            actual, expected,
            "worker count must not change session ranking"
        );
        assert_eq!(one.worker_pool_build_count(), 1);
        assert_eq!(four.worker_pool_build_count(), 1);
    }

    /// Opt-in deterministic comparison of one-worker and multi-worker session scoring. Correctness
    /// belongs to the non-ignored parity test above; this prints p50/p95 and digest evidence without
    /// imposing a scheduler-sensitive speedup threshold.
    #[test]
    #[ignore = "deterministic release-mode session-search performance measurement"]
    fn session_search_parallel_scoring_benchmark() {
        let root = tempfile::tempdir().unwrap();
        let path = root.path().join("index.db");
        {
            let db =
                Db::open_with_threads(&path, TEST_BUSY_TIMEOUT_MS, NonZeroUsize::new(1).unwrap())
                    .unwrap();
            let transcript_padding = "database schema migration planning ".repeat(250);
            let tx = db.conn.unchecked_transaction().unwrap();
            {
                let mut session = tx
                    .prepare(
                        "insert into sessions (
                             id, provider, provider_session_id, title, preview_text, source_path,
                             parse_version, discovery_source
                         ) values (?1, 'claude', ?1, ?2, ?3, ?4, '1', 'test')",
                    )
                    .unwrap();
                let mut transcript = tx
                    .prepare("insert into transcripts(session_id, transcript_text) values (?1, ?2)")
                    .unwrap();
                for index in 0..4_000 {
                    let id = format!("s{index:04}");
                    session
                        .execute(params![
                            id,
                            (index % 11 == 0).then_some("database migration"),
                            format!("preview {index}"),
                            format!("/{index}.jsonl"),
                        ])
                        .unwrap();
                    transcript
                        .execute(params![
                            format!("s{index:04}"),
                            format!("{transcript_padding}{index}")
                        ])
                        .unwrap();
                }
            }
            tx.commit().unwrap();
        }
        let filters = SearchFilters {
            limit: 50,
            ..Default::default()
        };
        let scoring = crate::config::ScoringConfig {
            recency_weight: 0,
            ..Default::default()
        };
        let measure = |threads| {
            let db = Db::open_with_threads(
                &path,
                TEST_BUSY_TIMEOUT_MS,
                NonZeroUsize::new(threads).unwrap(),
            )
            .unwrap();
            let search = || {
                db.search("databse migraton", &filters, None, &scoring)
                    .unwrap()
            };
            let expected = serde_json::to_vec(&search()).unwrap();
            let digest = crate::hashing::sha256(&expected);
            let mut elapsed = Vec::new();
            for _ in 0..7 {
                let started = Instant::now();
                assert_eq!(serde_json::to_vec(&search()).unwrap(), expected);
                elapsed.push(started.elapsed().as_micros());
            }
            elapsed.sort_unstable();
            (
                elapsed[elapsed.len() / 2],
                elapsed[elapsed.len() - 1],
                digest,
            )
        };
        let one = measure(1);
        let four = measure(4);
        assert_eq!(one.2, four.2);
        eprintln!(
            "session_parallel_benchmark sessions=4000 transcript_bytes_per_session={} one_worker_median_us={} one_worker_p95_us={} four_worker_median_us={} four_worker_p95_us={} digest=sha256:{}",
            "database schema migration planning ".len() * 250,
            one.0,
            one.1,
            four.0,
            four.1,
            one.2
        );
    }

    /// Opt-in direct attribution of terminal-timestamp versus closed-span predicates. Correctness
    /// stays in ordinary tests; this records median/p95 and verifies both plans avoid message or
    /// transcript scans without making scheduler-sensitive timing a unit-test gate.
    #[test]
    #[ignore = "deterministic release-mode temporal predicate measurement"]
    fn session_temporal_overlap_predicate_benchmark() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let tx = db.conn.unchecked_transaction().unwrap();
        {
            let mut insert = tx
                .prepare(
                    "insert into sessions (id, provider, provider_session_id, created_at, updated_at, preview_text, source_path, parse_version, discovery_source) values (?1, 'claude', ?1, ?2, ?3, '', ?4, '1', 'test')",
                )
                .unwrap();
            for index in 0..100_000 {
                let created = if index % 2 == 0 {
                    "2026-01-01T00:00:00+00:00"
                } else {
                    "2025-12-01T00:00:00+00:00"
                };
                insert
                    .execute(params![
                        format!("s{index:06}"),
                        created,
                        "2026-01-15T00:00:00+00:00",
                        format!("/{index}.jsonl")
                    ])
                    .unwrap();
            }
        }
        tx.commit().unwrap();
        let measure = |predicate: &str| {
            let sql = format!("select count(*) from sessions s where {predicate}");
            let expected: i64 = db.conn.query_row(&sql, [], |row| row.get(0)).unwrap();
            let mut elapsed = Vec::new();
            for _ in 0..9 {
                let started = Instant::now();
                assert_eq!(
                    db.conn
                        .query_row::<i64, _, _>(&sql, [], |row| row.get(0))
                        .unwrap(),
                    expected
                );
                elapsed.push(started.elapsed().as_micros());
            }
            elapsed.sort_unstable();
            let plan = db
                .conn
                .prepare(&format!("explain query plan {sql}"))
                .unwrap()
                .query_map([], |row| row.get::<_, String>(3))
                .unwrap()
                .collect::<rusqlite::Result<Vec<_>>>()
                .unwrap()
                .join(" | ");
            assert!(
                !plan.contains("messages") && !plan.contains("transcripts"),
                "{plan}"
            );
            (
                elapsed[elapsed.len() / 2],
                elapsed[elapsed.len() - 1],
                expected,
                plan,
            )
        };
        let terminal = measure(
            "coalesce(s.updated_at, s.created_at) >= '2025-12-15T00:00:00+00:00' and coalesce(s.updated_at, s.created_at) <= '2025-12-31T23:59:59+00:00'",
        );
        let overlap = measure(
            "coalesce(s.updated_at, s.created_at) >= '2025-12-01T00:00:00+00:00' and coalesce(s.created_at, s.updated_at) <= '2025-12-31T23:59:59+00:00'",
        );
        eprintln!(
            "session_temporal_predicate_benchmark sessions=100000 terminal_median_us={} terminal_p95_us={} terminal_matches={} overlap_median_us={} overlap_p95_us={} overlap_matches={} terminal_plan={:?} overlap_plan={:?}",
            terminal.0, terminal.1, terminal.2, overlap.0, overlap.1, overlap.2, terminal.3, overlap.3
        );
    }

    #[test]
    fn message_update_keeps_fts_in_sync() {
        // External-content messages_fts must track in-place UPDATEs, not just
        // insert/delete — otherwise a future `update messages set content=...` would
        // leave stale terms in the index and miss new ones.
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute(
                "insert into sessions (id, provider, provider_session_id, preview_text, \
                 source_path, parse_version, discovery_source) \
                 values ('s1','claude','s1','','/p','1','test')",
                [],
            )
            .unwrap();
        db.conn
            .execute(
                "insert into messages (id, session_id, provider, seq, role, content) \
                 values (1,'s1','claude',0,'user','alpha original')",
                [],
            )
            .unwrap();
        let count = |term: &str| -> i64 {
            db.conn
                .query_row(
                    "select count(*) from messages_fts where messages_fts match ?1",
                    params![term],
                    |r| r.get(0),
                )
                .unwrap()
        };
        assert_eq!(count("original"), 1, "inserted content is searchable");
        db.conn
            .execute("update messages set content='beta updated' where id=1", [])
            .unwrap();
        assert_eq!(count("updated"), 1, "new content searchable after update");
        assert_eq!(count("original"), 0, "stale term dropped after update");
    }

    /// `sessions_fts` was maintained on every session write and read by nothing since session
    /// search began scoring the complete corpus (2026-07-22). This build empties the copy an
    /// earlier build filled exactly once, keeps an empty table for the layout check of an aise
    /// before 1.0.0rc2 sharing the index, writes nothing into it, and leaves an older writer's
    /// refill alone so two builds on one machine cannot take turns filling and emptying it.
    #[test]
    fn open_retires_the_unread_session_fts_copy_once_and_keeps_the_empty_table_for_older_builds() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("index.db");
        drop(Db::open(&path).unwrap());
        let fill = || {
            rusqlite::Connection::open(&path)
                .unwrap()
                .execute_batch(
                    "insert into sessions_fts(rowid, title, summary, preview_text, transcript_text)
                     values (1, 'older build wrote this', '', '', '');",
                )
                .unwrap();
        };
        let fts_rows = |db: &Db| -> i64 {
            db.conn
                .query_row("select count(*) from sessions_fts", [], |row| row.get(0))
                .unwrap()
        };
        // A fresh database: the table exists, empty, and the retirement is recorded.
        let db = Db::open(&path).unwrap();
        assert_eq!(fts_rows(&db), 0);
        assert!(
            crate::indexer::current_schema_layout_problem(&db.conn)
                .unwrap()
                .is_none(),
            "the empty table satisfies the layout check an older build performs"
        );
        seed_messages(&db, &[("user", "hello")]);
        assert_eq!(fts_rows(&db), 0, "no write path fills it");
        db.clear_all().unwrap();
        drop(db);
        // An older build sharing the index refills it; this build leaves that alone.
        fill();
        let reopened = Db::open(&path).unwrap();
        assert_eq!(
            fts_rows(&reopened),
            1,
            "a refill by an older writer is left alone after the one-time retirement"
        );
        drop(reopened);
        // A database an earlier build filled and this build has never opened: emptied once.
        rusqlite::Connection::open(&path)
            .unwrap()
            .execute_batch("delete from index_metadata where key = 'sessions_fts_retired';")
            .unwrap();
        let retired = Db::open(&path).unwrap();
        assert_eq!(
            fts_rows(&retired),
            0,
            "the earlier build's copy is emptied once"
        );
    }

    #[test]
    fn resolve_session_errors_are_actionable() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let insert = |id: &str| {
            db.conn
                .execute(
                    "insert into sessions (id, provider, provider_session_id, preview_text, \
                     source_path, parse_version, discovery_source) \
                     values (?1,'claude',?1,'','/p','1','test')",
                    params![id],
                )
                .unwrap();
        };
        insert("claude:abc123");
        insert("claude:abc456");

        // Unknown id → points at the commands that list/find sessions.
        let err = db.resolve_session("zzz").unwrap_err().to_string();
        assert!(err.contains("no session matches"));
        assert!(err.contains("aise list") || err.contains("aise search"));
        let err = db.resolve_session_record("zzz").unwrap_err().to_string();
        assert!(err.contains("no session matches"));
        assert!(err.contains("aise list") || err.contains("aise search"));

        // Ambiguous prefix → names the matching candidates so the user can disambiguate.
        let err = db.resolve_session("claude:abc").unwrap_err().to_string();
        assert!(err.contains("ambiguous"));
        assert!(
            err.contains("claude:abc123") && err.contains("claude:abc456"),
            "ambiguous error must list candidates: {err}"
        );
        let err = db
            .resolve_session_record("claude:abc")
            .unwrap_err()
            .to_string();
        assert!(err.contains("ambiguous"));
        assert!(
            err.contains("claude:abc123") && err.contains("claude:abc456"),
            "ambiguous error must list candidates: {err}"
        );
    }

    #[test]
    fn exact_session_resolution_uses_indexes_and_bare_collisions_name_canonical_candidates() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        for provider in [Provider::Claude, Provider::Codex] {
            db.conn
                .execute(
                    "insert into sessions (id, provider, provider_session_id, preview_text, \
                     source_path, parse_version, discovery_source) \
                     values (?1, ?2, 'shared-native-id', '', '/p', '1', 'test')",
                    params![
                        format!("{}:shared-native-id", provider.as_str()),
                        provider.as_str()
                    ],
                )
                .unwrap();
        }

        for canonical in ["claude:shared-native-id", "codex:shared-native-id"] {
            assert_eq!(db.resolve_session_record(canonical).unwrap().id, canonical);
        }
        let collision = db
            .resolve_session_record("shared-native-id")
            .unwrap_err()
            .to_string();
        assert!(collision.contains("ambiguous"), "{collision}");
        assert!(collision.contains("claude:shared-native-id"), "{collision}");
        assert!(collision.contains("codex:shared-native-id"), "{collision}");

        let mut statement = db
            .conn
            .prepare(&format!(
                "explain query plan {RESOLVE_SESSION_RECORD_EXACT_SQL}"
            ))
            .unwrap();
        let plan = statement
            .query_map(["claude:shared-native-id"], |row| row.get::<_, String>(3))
            .unwrap()
            .collect::<rusqlite::Result<Vec<_>>>()
            .unwrap()
            .join("\n");
        assert!(plan.contains("SEARCH"), "{plan}");
        assert!(!plan.contains("SCAN s"), "{plan}");
    }

    #[test]
    fn session_prefix_resolution_treats_sql_wildcards_as_literal_text() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        for id in ["claude:percent", "claude:under_score"] {
            db.conn
                .execute(
                    "insert into sessions (id, provider, provider_session_id, preview_text, \
                     source_path, parse_version, discovery_source) \
                     values (?1, 'claude', ?1, '', '/p', '1', 'test')",
                    params![id],
                )
                .unwrap();
        }
        for literal in ["%", "_"] {
            let error = db.resolve_session_record(literal).unwrap_err().to_string();
            assert!(error.contains("no session matches"), "{error}");
        }
    }

    #[test]
    fn open_adds_typed_message_columns_to_version_one_database() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("index.db");
        {
            let legacy = Connection::open(&path).unwrap();
            legacy
                .execute_batch(
                    "create table messages (
                        id integer primary key,
                        session_id text not null,
                        provider text not null,
                        seq integer not null,
                        role text not null,
                        ts text,
                        tool_name text,
                        is_compaction integer not null default 0,
                        content text not null
                    );
                    insert into messages
                        (session_id, provider, seq, role, content)
                    values ('claude:legacy', 'claude', 0, 'user', 'legacy text');
                    pragma user_version = 1;",
                )
                .unwrap();
        }

        let db = Db::open(&path).unwrap();
        let columns = db
            .conn
            .prepare("pragma table_info(messages)")
            .unwrap()
            .query_map([], |row| row.get::<_, String>(1))
            .unwrap()
            .collect::<rusqlite::Result<Vec<_>>>()
            .unwrap();
        assert!(columns.iter().any(|column| column == "kind"));
        assert!(columns.iter().any(|column| column == "tool_call_id"));
        assert!(columns.iter().any(|column| column == "authorship"));
        assert!(columns
            .iter()
            .any(|column| column == "correlation_authority"));
        assert!(columns.iter().any(|column| column == "correlation_scope"));
        assert!(columns.iter().any(|column| column == "correlation_id"));
        assert!(columns.iter().any(|column| column == "record_relation"));
        let legacy_authorship: String = db
            .conn
            .query_row("select authorship from messages limit 1", [], |row| {
                row.get(0)
            })
            .unwrap();
        assert_eq!(legacy_authorship, "unknown");
        let parts_table_exists: bool = db
            .conn
            .query_row(
                "select exists(
                    select 1 from sqlite_schema
                    where type = 'table' and name = 'message_content_parts'
                )",
                [],
                |row| row.get(0),
            )
            .unwrap();
        assert!(parts_table_exists);
        assert!(db.needs_backfill().unwrap());
    }

    #[test]
    fn message_provenance_round_trips_without_copying_part_text() {
        use crate::models::{
            ContentPartAuthorship, ContentPartOrigin, MessageAuthorship, MessageContentPart,
            MessageCorrelationAuthority, MessageCorrelationIdentity, MessageProvenance,
            MessageRecordRelation,
        };

        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let mut parsed = crate::util::minimal_record(
            Provider::GeminiCli,
            Path::new("/fixture/mixed.json"),
            String::new(),
        );
        parsed.session.id = "gemini-cli:mixed".to_string();
        parsed.session.provider_session_id = "mixed".to_string();
        parsed.messages = vec![crate::models::Message {
            seq: 0,
            role: Role::User,
            ts: None,
            tool_name: None,
            kind: crate::models::MessageKind::Conversation,
            tool_call_id: None,
            is_compaction: false,
            content: "askAI".to_string(),
            provenance: MessageProvenance {
                authorship: MessageAuthorship::Mixed,
                record_relation: MessageRecordRelation::Mirror,
                correlation_identity: Some(MessageCorrelationIdentity {
                    authority: MessageCorrelationAuthority::Google,
                    scope: "conversation_event".to_string(),
                    id: "event-7".to_string(),
                }),
                content_parts: vec![
                    MessageContentPart {
                        ordinal: 0,
                        start_char: 0,
                        end_char: 3,
                        authorship: ContentPartAuthorship::Human,
                        origin: ContentPartOrigin::DirectInput,
                    },
                    MessageContentPart {
                        ordinal: 1,
                        start_char: 3,
                        end_char: 5,
                        authorship: ContentPartAuthorship::Generated,
                        origin: ContentPartOrigin::QuotedContent,
                    },
                ],
            },
        }];

        db.upsert_session(&parsed, 0, 0).unwrap();
        let stored: (String, String, String, String, String) = db
            .conn
            .query_row(
                "select authorship, correlation_authority, correlation_scope,
                        correlation_id, record_relation
                 from messages where session_id = ?1 and seq = 0",
                [&parsed.session.id],
                |row| {
                    Ok((
                        row.get(0)?,
                        row.get(1)?,
                        row.get(2)?,
                        row.get(3)?,
                        row.get(4)?,
                    ))
                },
            )
            .unwrap();
        assert_eq!(
            stored,
            (
                "mixed".to_string(),
                "google".to_string(),
                "conversation_event".to_string(),
                "event-7".to_string(),
                "mirror".to_string(),
            )
        );
        let parts = db
            .conn
            .prepare(
                "select ordinal, start_char, end_char, authorship, origin
                 from message_content_parts order by ordinal",
            )
            .unwrap()
            .query_map([], |row| {
                Ok((
                    row.get::<_, i64>(0)?,
                    row.get::<_, i64>(1)?,
                    row.get::<_, i64>(2)?,
                    row.get::<_, String>(3)?,
                    row.get::<_, String>(4)?,
                ))
            })
            .unwrap()
            .collect::<rusqlite::Result<Vec<_>>>()
            .unwrap();
        assert_eq!(
            parts,
            vec![
                (0, 0, 3, "human".to_string(), "direct_input".to_string()),
                (
                    1,
                    3,
                    5,
                    "generated".to_string(),
                    "quoted_content".to_string()
                ),
            ]
        );
        let part_columns = db
            .conn
            .prepare("pragma table_info(message_content_parts)")
            .unwrap()
            .query_map([], |row| row.get::<_, String>(1))
            .unwrap()
            .collect::<rusqlite::Result<Vec<_>>>()
            .unwrap();
        assert!(!part_columns.iter().any(|column| column == "content"));
    }

    #[test]
    fn invalid_message_provenance_rolls_back_the_whole_session_upsert() {
        use crate::models::{MessageAuthorship, MessageProvenance};

        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let mut parsed = crate::util::minimal_record(
            Provider::Claude,
            Path::new("/fixture/invalid.jsonl"),
            String::new(),
        );
        parsed.session.id = "claude:invalid-provenance".to_string();
        parsed.session.provider_session_id = "invalid-provenance".to_string();
        parsed.messages = vec![crate::models::Message {
            seq: 0,
            role: Role::User,
            ts: None,
            tool_name: None,
            kind: crate::models::MessageKind::Conversation,
            tool_call_id: None,
            is_compaction: false,
            content: "text".to_string(),
            provenance: MessageProvenance {
                authorship: MessageAuthorship::Mixed,
                ..Default::default()
            },
        }];

        let error = db.upsert_session(&parsed, 0, 0).unwrap_err().to_string();
        assert!(error.contains("message sequence 0"), "{error}");
        assert!(error.contains("claude:invalid-provenance"), "{error}");
        assert!(error.contains("requires content_parts"), "{error}");
        assert_eq!(
            db.conn
                .query_row(
                    "select count(*) from sessions where id = ?1",
                    [&parsed.session.id],
                    |row| row.get::<_, i64>(0),
                )
                .unwrap(),
            0,
            "the transaction must not publish a session whose message provenance is invalid"
        );
    }

    #[test]
    fn replacing_a_mixed_message_cascades_its_part_ranges() {
        use crate::models::{
            ContentPartAuthorship, ContentPartOrigin, MessageAuthorship, MessageContentPart,
            MessageProvenance,
        };

        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let mut parsed = parsed_with_messages("claude:parts-cascade", &["ab"]);
        parsed.messages[0].provenance = MessageProvenance {
            authorship: MessageAuthorship::Mixed,
            content_parts: vec![
                MessageContentPart {
                    ordinal: 0,
                    start_char: 0,
                    end_char: 1,
                    authorship: ContentPartAuthorship::Human,
                    origin: ContentPartOrigin::DirectInput,
                },
                MessageContentPart {
                    ordinal: 1,
                    start_char: 1,
                    end_char: 2,
                    authorship: ContentPartAuthorship::Generated,
                    origin: ContentPartOrigin::QuotedContent,
                },
            ],
            ..Default::default()
        };
        db.upsert_session(&parsed, 0, 0).unwrap();
        assert_eq!(
            db.conn
                .query_row("select count(*) from message_content_parts", [], |row| {
                    row.get::<_, i64>(0)
                })
                .unwrap(),
            2
        );

        parsed.messages[0].provenance = MessageProvenance {
            authorship: MessageAuthorship::Human,
            ..Default::default()
        };
        db.replace_session(&parsed, 1, 1).unwrap();
        assert_eq!(
            db.conn
                .query_row("select count(*) from message_content_parts", [], |row| {
                    row.get::<_, i64>(0)
                })
                .unwrap(),
            0
        );
    }

    #[test]
    fn provenance_queries_use_session_and_behavioral_analysis_indexes() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        for (sql, expected_index) in [
            (
                "select seq from messages
                 where session_id = 'claude:s' and authorship = 'human'
                   and record_relation = 'original'
                 order by seq",
                "idx_messages_session_authorship_relation_seq",
            ),
            (
                "select session_id, seq from messages
                 where authorship = 'human' and record_relation = 'original'
                 order by ts desc, session_id, seq",
                "idx_messages_authorship_relation_ts",
            ),
        ] {
            let plan = db
                .conn
                .prepare(&format!("explain query plan {sql}"))
                .unwrap()
                .query_map([], |row| row.get::<_, String>(3))
                .unwrap()
                .collect::<rusqlite::Result<Vec<_>>>()
                .unwrap()
                .join("\n");
            assert!(plan.contains(expected_index), "{plan}");
            assert!(!plan.contains("SCAN messages"), "{plan}");
        }

        for sql in [
            ANALYSIS_MESSAGE_COUNTS_SQL,
            ANALYSIS_ATTRIBUTABLE_HUMAN_MESSAGES_SQL,
        ] {
            let plan = db
                .conn
                .prepare(&format!("explain query plan {sql}"))
                .unwrap()
                .query_map(["claude:s"], |row| row.get::<_, String>(3))
                .unwrap()
                .collect::<rusqlite::Result<Vec<_>>>()
                .unwrap()
                .join("\n");
            assert!(
                plan.contains("idx_messages_session_authorship_relation_seq"),
                "analysis must select candidate messages through the composite provenance index:\n{plan}"
            );
            assert!(
                !plan.contains("SCAN m"),
                "analysis must not full-scan messages for one session:\n{plan}"
            );
        }
    }

    #[test]
    fn correction_candidate_and_part_queries_use_provenance_indexes() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let candidates = format!(
            "explain query plan {CORRECTION_CANDIDATES_SQL}
             order by m.ts desc, m.session_id asc, m.seq asc"
        );
        let candidate_plan = db
            .conn
            .prepare(&candidates)
            .unwrap()
            .query_map([], |row| row.get::<_, String>(3))
            .unwrap()
            .collect::<rusqlite::Result<Vec<_>>>()
            .unwrap()
            .join("\n");
        assert!(
            candidate_plan.contains("idx_messages_authorship_relation_ts"),
            "{candidate_plan}"
        );
        assert!(!candidate_plan.contains("SCAN m"), "{candidate_plan}");

        let parts = format!(
            "explain query plan {CORRECTION_HUMAN_PARTS_SQL}
             order by m.id, p.ordinal"
        );
        let parts_plan = db
            .conn
            .prepare(&parts)
            .unwrap()
            .query_map([], |row| row.get::<_, String>(3))
            .unwrap()
            .collect::<rusqlite::Result<Vec<_>>>()
            .unwrap()
            .join("\n");
        assert!(
            parts_plan.contains("idx_messages_authorship_relation_ts"),
            "{parts_plan}"
        );
        assert!(
            parts_plan.contains("SEARCH p USING PRIMARY KEY"),
            "{parts_plan}"
        );
        assert!(!parts_plan.contains("SCAN m"), "{parts_plan}");
        assert!(!parts_plan.contains("SCAN p"), "{parts_plan}");
    }

    #[test]
    fn tool_argument_search_uses_explicit_json_pointer_and_excludes_results() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_messages(&db, &[("tool", "call"), ("tool", "cargo test output")]);
        db.conn
            .execute_batch(
                r#"update messages set
                       kind = 'tool_call', tool_name = 'exec_command',
                       content = '{"args":{"cmd":"cargo test","request":{"path":"src/lib.rs"}},"kind":"tool_call","tool_name":"exec_command"}'
                   where seq = 0;
                   update messages set kind = 'tool_result', tool_name = 'exec_command'
                   where seq = 1;"#,
            )
            .unwrap();

        let hits = db
            .search_messages(
                "cargo test",
                &MessageFilters {
                    field: Some(SearchField::ToolArgument),
                    argument_path: Some("/cmd".to_string()),
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(hits.len(), 1);
        assert_eq!(hits[0].seq, 0);

        let nested = db
            .search_messages(
                "src/lib.rs",
                &MessageFilters {
                    field: Some(SearchField::ToolArgument),
                    argument_path: Some("/request/path".to_string()),
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(nested.len(), 1);

        db.conn
            .execute(
                "insert into messages (
                     session_id, provider, seq, role, kind, content
                 ) values (
                     'claude:s1', 'claude', 2, 'user', 'conversation',
                     '{\"args\":{\"cmd\":\"cargo test\"}}'
                 )",
                [],
            )
            .unwrap();
        for (query, match_mode) in [
            ("", MessageSearchMode::Literal),
            ("cargo test", MessageSearchMode::Literal),
            (r"cargo t.st", MessageSearchMode::Regex),
            ("crgo tst", MessageSearchMode::Fuzzy),
        ] {
            let hits = db
                .search_messages(
                    query,
                    &MessageFilters {
                        kinds: Some(vec![
                            crate::models::MessageKind::Conversation,
                            crate::models::MessageKind::ToolCall,
                        ]),
                        field: Some(SearchField::ToolArgument),
                        argument_path: Some("/cmd".to_string()),
                        match_mode,
                        limit: 10,
                        ..Default::default()
                    },
                )
                .unwrap();
            assert_eq!(
                hits.iter().map(|hit| hit.seq).collect::<Vec<_>>(),
                vec![0],
                "tool-argument {match_mode:?} search must intersect an explicit kind union with tool_call"
            );
        }

        db.conn
            .execute_batch(
                r#"with recursive n(value) as (
                       values(1) union all select value + 1 from n where value < 100
                   )
                   insert into messages (
                       session_id, provider, seq, role, tool_name, kind, content
                   )
                   select 'claude:s1', 'claude', 10 + value, 'tool', 'exec_command',
                          'tool_call',
                          printf('{"args":{"cmd":"unrelated payload %d"}}', value)
                     from n;"#,
            )
            .unwrap();
        for (query, match_mode) in [
            ("cargo test", MessageSearchMode::Literal),
            (r"cargo t.st", MessageSearchMode::Regex),
        ] {
            let filters = MessageFilters {
                field: Some(SearchField::ToolArgument),
                argument_path: Some("/cmd".to_string()),
                match_mode,
                ..Default::default()
            };
            let (hits, explain) = db
                .search_messages_with_explain(query, &filters, true)
                .unwrap();
            assert_eq!(hits.iter().map(|hit| hit.seq).collect::<Vec<_>>(), vec![0]);
            let explain = explain.unwrap();
            assert!(
                explain.prefilter.is_some(),
                "tool-argument {match_mode:?} search should prefilter raw tool-call JSON: {explain:?}"
            );
            // The receipt keeps the published meaning of its two counts: `corpus` is the
            // structural denominator (every tool-call row the filters admit, 101 here) and
            // `candidates` is the prefilter output still needing verification (a superset of
            // the one hit, never more than the corpus). Reporting the authoritative match count
            // in both fields made every prefiltered tool-argument search read as 100 %
            // selectivity with the "low selectivity" hint attached.
            assert!(
                explain.corpus >= 101,
                "corpus is the structural tool-call denominator: {explain:?}"
            );
            let candidates = explain.candidates.unwrap();
            assert!(
                candidates >= hits.len() as i64 && candidates <= explain.corpus,
                "candidates are the prefilter superset of the hits: {explain:?}"
            );
            let summary = explain.summary(true);
            assert!(
                !summary.contains("low selectivity"),
                "one hit in a hundred is not low selectivity: {summary}"
            );
        }

        db.conn
            .execute(
                "update messages set content = ?1 where seq = 0",
                [crate::util::tool_call_message_content(
                    "exec_command",
                    serde_json::json!({"cmd": "quoted \"target\" and slash \\ value"}),
                )],
            )
            .unwrap();
        for (query, expected, expect_prefilter) in [
            ("quoted \"target\"", vec![0], true),
            (r#"quoted \"target\""#, Vec::new(), true),
            ("slash \\ value", vec![0], true),
            ("d\\ ", Vec::new(), false),
        ] {
            let filters = MessageFilters {
                field: Some(SearchField::ToolArgument),
                argument_path: Some("/cmd".to_string()),
                ..Default::default()
            };
            let (hits, explain) = db
                .search_messages_with_explain(query, &filters, true)
                .unwrap();
            assert_eq!(
                hits.iter().map(|hit| hit.seq).collect::<Vec<_>>(),
                expected,
                "JSON escaping must not create a trigram false negative for {query:?}"
            );
            assert_eq!(
                explain.unwrap().prefilter.is_some(),
                expect_prefilter,
                "only JSON-stable required trigrams may prefilter {query:?}"
            );
        }

        db.conn
            .execute(
                "update messages set content = ?1 where seq = 0",
                [crate::util::tool_call_message_content(
                    "exec_command",
                    serde_json::json!({"cmd": "cargo test"}),
                )],
            )
            .unwrap();

        // Incremental insert/update/delete triggers must keep derived-field prefilter membership
        // in sync just as they do for ordinary content search.
        db.conn
            .execute(
                "insert into messages (
                     session_id, provider, seq, role, tool_name, kind, content
                 ) values ('claude:s1', 'claude', 500, 'tool', 'exec_command', 'tool_call', ?1)",
                [crate::util::tool_call_message_content(
                    "exec_command",
                    serde_json::json!({"cmd": "incremental trigram target"}),
                )],
            )
            .unwrap();
        let incremental_filters = MessageFilters {
            field: Some(SearchField::ToolArgument),
            argument_path: Some("/cmd".to_string()),
            ..Default::default()
        };
        let find_incremental = |query: &str| {
            db.search_messages(query, &incremental_filters)
                .unwrap()
                .into_iter()
                .map(|hit| hit.seq)
                .collect::<Vec<_>>()
        };
        assert_eq!(find_incremental("incremental trigram target"), vec![500]);
        db.conn
            .execute(
                "update messages set content = ?1 where seq = 500",
                [crate::util::tool_call_message_content(
                    "exec_command",
                    serde_json::json!({"cmd": "replacement trigram target"}),
                )],
            )
            .unwrap();
        assert!(find_incremental("incremental trigram target").is_empty());
        assert_eq!(find_incremental("replacement trigram target"), vec![500]);
        db.conn
            .execute("delete from messages where seq = 500", [])
            .unwrap();
        assert!(find_incremental("replacement trigram target").is_empty());

        let fuzzy_filters = MessageFilters {
            field: Some(SearchField::ToolArgument),
            argument_path: Some("/cmd".to_string()),
            match_mode: MessageSearchMode::Fuzzy,
            limit: 5,
            ..Default::default()
        };
        let (fuzzy, explain) = db
            .search_messages_with_explain("crgo tst", &fuzzy_filters, true)
            .unwrap();
        assert_eq!(fuzzy.len(), 1);
        assert_eq!(fuzzy[0].seq, 0);
        let explain = explain.unwrap();
        assert_eq!(
            explain.prefilter_skipped.as_deref(),
            Some("complete filtered corpus scored, retaining at most min(offset + limit, corpus) ranked rows")
        );
        assert!(
            explain.candidates.unwrap() < explain.corpus,
            "only matching tool-argument projections should count as fuzzy candidates: {explain:?}"
        );

        let plan = db
            .conn
            .prepare(
                "explain query plan select session_id, seq from messages
                 where kind = 'tool_call' order by session_id, seq",
            )
            .unwrap()
            .query_map([], |row| row.get::<_, String>(3))
            .unwrap()
            .collect::<rusqlite::Result<Vec<_>>>()
            .unwrap()
            .join("\n");
        assert!(plan.contains("idx_messages_tool_calls"), "{plan}");

        let error = db
            .search_messages(
                "cargo",
                &MessageFilters {
                    field: Some(SearchField::ToolArgument),
                    argument_path: Some("cmd".to_string()),
                    ..Default::default()
                },
            )
            .unwrap_err()
            .to_string();
        assert!(error.contains("RFC 6901"));
    }

    #[test]
    fn tool_argument_trigram_prefilter_preserves_direct_scan_order_and_pages() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_messages(&db, &[("tool", "placeholder")]);
        db.conn
            .execute_batch(
                r#"update messages set kind = 'tool_call', tool_name = 'exec_command',
                       content = '{"args":{"cmd":"cargo test --workspace"},"kind":"tool_call","tool_name":"exec_command"}'
                   where seq = 0;
                   with recursive n(value) as (
                       values(1) union all select value + 1 from n where value < 250
                   )
                   insert into messages (
                       session_id, provider, seq, role, tool_name, kind, content
                   )
                   select 'claude:s1', 'claude', value, 'tool', 'exec_command', 'tool_call',
                          case when value in (70, 140, 210)
                               then printf('{"args":{"cmd":"cargo test target %d"},"kind":"tool_call","tool_name":"exec_command"}', value)
                               else printf('{"args":{"cmd":"unrelated payload %d"},"kind":"tool_call","tool_name":"exec_command"}', value)
                          end
                     from n;"#,
            )
            .unwrap();

        for (query, mode) in [
            ("cargo test", MessageSearchMode::Literal),
            (r"cargo t.st", MessageSearchMode::Regex),
        ] {
            for (limit, offset) in [(0, 0), (2, 0), (2, 1), (1, 3)] {
                let filters = MessageFilters {
                    field: Some(SearchField::ToolArgument),
                    argument_path: Some("/cmd".to_string()),
                    match_mode: mode,
                    limit,
                    offset,
                    ..Default::default()
                };
                let accelerated = db.search_messages(query, &filters).unwrap();
                let predicate = match mode {
                    MessageSearchMode::Literal => {
                        "unicode_lower_contains(rust_json_pointer('/cmd', m.content), ?1)"
                    }
                    MessageSearchMode::Regex => {
                        "rust_regexp(?1, rust_json_pointer('/cmd', m.content))"
                    }
                    MessageSearchMode::Fuzzy => unreachable!(),
                };
                let mut sql = format!(
                    "select m.session_id, m.seq from messages m \
                     where m.kind = 'tool_call' and {predicate} \
                     order by m.session_id, m.seq"
                );
                if limit > 0 {
                    sql.push_str(" limit ?2 offset ?3");
                } else if offset > 0 {
                    sql.push_str(" limit -1 offset ?3");
                }
                // `unicode_lower_contains` takes an already-folded needle, so the oracle folds it
                // the way every production caller does. Lowercasing here would make the
                // comparison run against a rule aise does not ship, and the sigma spellings are
                // exactly where the two disagree.
                let query_arg = if mode == MessageSearchMode::Literal {
                    fold_caseless(query)
                } else {
                    query.to_string()
                };
                let mut statement = db.conn.prepare(&sql).unwrap();
                let direct = if limit > 0 {
                    statement
                        .query_map(params![query_arg, limit as i64, offset as i64], |row| {
                            Ok((row.get::<_, String>(0)?, row.get::<_, i64>(1)?))
                        })
                        .unwrap()
                        .collect::<rusqlite::Result<Vec<_>>>()
                        .unwrap()
                } else if offset > 0 {
                    statement
                        .query_map(params![query_arg, limit as i64, offset as i64], |row| {
                            Ok((row.get::<_, String>(0)?, row.get::<_, i64>(1)?))
                        })
                        .unwrap()
                        .collect::<rusqlite::Result<Vec<_>>>()
                        .unwrap()
                } else {
                    statement
                        .query_map([query_arg], |row| {
                            Ok((row.get::<_, String>(0)?, row.get::<_, i64>(1)?))
                        })
                        .unwrap()
                        .collect::<rusqlite::Result<Vec<_>>>()
                        .unwrap()
                };
                assert_eq!(
                    hit_keys(accelerated),
                    direct,
                    "accelerated {mode:?} page limit={limit} offset={offset} must equal the independent direct projection scan"
                );
            }
        }
    }

    /// Deterministic, opt-in latency measurement for the raw-JSON candidate prefilter. The
    /// ordinary test above owns correctness; this reports median warm latency and digest parity
    /// without making a scheduler-sensitive timing assertion.
    ///
    /// Complexity model: N rows of J JSON bytes each and C candidates. Direct scan is O(N*J);
    /// accelerated verification is postings lookup plus O(C*J), with O(H) returned-result memory
    /// in both cases. Run with `cargo test -p ai-session-search --release
    /// tool_argument_trigram_prefilter_benchmark -- --ignored --nocapture`.
    #[test]
    #[ignore = "deterministic release-mode performance measurement"]
    fn tool_argument_trigram_prefilter_benchmark() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_messages(&db, &[("tool", "placeholder")]);
        let tx = db.conn.unchecked_transaction().unwrap();
        {
            let mut insert = tx
                .prepare(
                    "insert into messages (session_id, provider, seq, role, tool_name, kind, content) \
                     values ('claude:s1', 'claude', ?1, 'tool', 'exec_command', 'tool_call', ?2)",
                )
                .unwrap();
            for seq in 1..=25_000_i64 {
                let cmd = if seq % 5_000 == 0 {
                    format!("selective trigram benchmark target {seq}")
                } else {
                    format!("ordinary deterministic payload {seq} with JSON parsing padding")
                };
                insert
                    .execute(params![
                        seq,
                        crate::util::tool_call_message_content(
                            "exec_command",
                            serde_json::json!({"cmd": cmd})
                        )
                    ])
                    .unwrap();
            }
        }
        tx.commit().unwrap();
        let filters = MessageFilters {
            field: Some(SearchField::ToolArgument),
            argument_path: Some("/cmd".to_string()),
            ..Default::default()
        };
        let query = "selective trigram benchmark target";
        let accelerated = || db.search_messages(query, &filters).unwrap();
        let direct = || {
            let mut statement = db
                .conn
                .prepare(
                    "select m.session_id, m.seq from messages m \
                     where m.kind = 'tool_call' and \
                           unicode_lower_contains(rust_json_pointer('/cmd', m.content), ?1) \
                     order by m.session_id, m.seq",
                )
                .unwrap();
            statement
                // Folded for the same reason the oracle above folds: the scalar's needle
                // argument arrives folded from every production caller.
                .query_map([fold_caseless(query)], |row| {
                    Ok((row.get::<_, String>(0)?, row.get::<_, i64>(1)?))
                })
                .unwrap()
                .collect::<rusqlite::Result<Vec<_>>>()
                .unwrap()
        };
        let accelerated_keys = hit_keys(accelerated());
        let direct_keys = direct();
        assert_eq!(accelerated_keys, direct_keys);
        let digest = crate::hashing::sha256(&serde_json::to_vec(&direct_keys).unwrap());
        let mut accelerated_us = Vec::new();
        let mut direct_us = Vec::new();
        for _ in 0..7 {
            let started = Instant::now();
            assert_eq!(hit_keys(accelerated()), direct_keys);
            accelerated_us.push(started.elapsed().as_micros());
            let started = Instant::now();
            assert_eq!(direct(), direct_keys);
            direct_us.push(started.elapsed().as_micros());
        }
        accelerated_us.sort_unstable();
        direct_us.sort_unstable();
        let (_, explain) = db
            .search_messages_with_explain(query, &filters, true)
            .unwrap();
        let explain = explain.unwrap();
        eprintln!(
            "tool_argument_prefilter_benchmark rows={} candidates={} hits={} accelerated_median_us={} accelerated_p95_us={} direct_median_us={} direct_p95_us={} digest=sha256:{}",
            explain.corpus,
            explain.candidates.unwrap(),
            direct_keys.len(),
            accelerated_us[accelerated_us.len() / 2],
            accelerated_us[accelerated_us.len() - 1],
            direct_us[direct_us.len() / 2],
            direct_us[direct_us.len() - 1],
            digest
        );
    }

    #[test]
    fn fuzzy_tool_argument_search_uses_workers_without_changing_scores_or_order() {
        let root = tempfile::tempdir().unwrap();
        let seed = |db: &Db| {
            seed_messages(db, &[("tool", "placeholder")]);
            let tx = db.conn.unchecked_transaction().unwrap();
            {
                let mut insert = tx
                    .prepare(
                        "insert into messages (
                             session_id, provider, seq, role, tool_name, kind, content
                         ) values ('claude:s1', 'claude', ?1, 'tool', 'exec_command',
                                   'tool_call', ?2)",
                    )
                    .unwrap();
                for seq in 1..=1_100_i64 {
                    let cmd = if seq % 137 == 0 {
                        format!("cargo test workspace target {seq}")
                    } else {
                        format!("ordinary tool argument payload {seq}")
                    };
                    insert
                        .execute(params![
                            seq,
                            crate::util::tool_call_message_content(
                                "exec_command",
                                serde_json::json!({"cmd": cmd})
                            )
                        ])
                        .unwrap();
                }
            }
            tx.commit().unwrap();
        };
        let one = Db::open_with_threads(
            &root.path().join("one.db"),
            TEST_BUSY_TIMEOUT_MS,
            NonZeroUsize::new(1).unwrap(),
        )
        .unwrap();
        let four = Db::open_with_threads(
            &root.path().join("four.db"),
            TEST_BUSY_TIMEOUT_MS,
            NonZeroUsize::new(4).unwrap(),
        )
        .unwrap();
        seed(&one);
        seed(&four);
        let filters = MessageFilters {
            field: Some(SearchField::ToolArgument),
            argument_path: Some("/cmd".to_string()),
            match_mode: MessageSearchMode::Fuzzy,
            limit: 20,
            ..Default::default()
        };
        let identity = |hits: Vec<MessageHit>| {
            hits.into_iter()
                .map(|hit| (hit.session_id, hit.seq, hit.fuzzy_score))
                .collect::<Vec<_>>()
        };
        assert_eq!(one.worker_pool_build_count(), 0);
        assert_eq!(four.worker_pool_build_count(), 0);
        let expected = identity(one.search_messages("crgo tst wrkspce", &filters).unwrap());
        let actual = identity(four.search_messages("crgo tst wrkspce", &filters).unwrap());
        assert_eq!(actual, expected);
        assert_eq!(one.worker_pool_build_count(), 1);
        assert_eq!(four.worker_pool_build_count(), 1);
    }

    #[test]
    #[ignore = "deterministic release-mode derived fuzzy performance measurement"]
    fn fuzzy_tool_argument_parallel_scoring_benchmark() {
        let root = tempfile::tempdir().unwrap();
        let path = root.path().join("index.db");
        {
            let db =
                Db::open_with_threads(&path, TEST_BUSY_TIMEOUT_MS, NonZeroUsize::new(1).unwrap())
                    .unwrap();
            seed_messages(&db, &[("tool", "placeholder")]);
            let tx = db.conn.unchecked_transaction().unwrap();
            {
                let mut insert = tx
                    .prepare(
                        "insert into messages (
                             session_id, provider, seq, role, tool_name, kind, content
                         ) values ('claude:s1', 'claude', ?1, 'tool', 'exec_command',
                                   'tool_call', ?2)",
                    )
                    .unwrap();
                for seq in 1..=30_000_i64 {
                    let cmd = if seq % 3_000 == 0 {
                        format!("cargo test workspace target {seq}")
                    } else {
                        format!("ordinary deterministic tool argument payload {seq}")
                    };
                    insert
                        .execute(params![
                            seq,
                            crate::util::tool_call_message_content(
                                "exec_command",
                                serde_json::json!({"cmd": cmd})
                            )
                        ])
                        .unwrap();
                }
            }
            tx.commit().unwrap();
        }
        let filters = MessageFilters {
            field: Some(SearchField::ToolArgument),
            argument_path: Some("/cmd".to_string()),
            match_mode: MessageSearchMode::Fuzzy,
            limit: 50,
            ..Default::default()
        };
        let measure = |threads| {
            let db = Db::open_with_threads(
                &path,
                TEST_BUSY_TIMEOUT_MS,
                NonZeroUsize::new(threads).unwrap(),
            )
            .unwrap();
            let search = || db.search_messages("crgo tst wrkspce", &filters).unwrap();
            let expected = serde_json::to_vec(&search()).unwrap();
            let digest = crate::hashing::sha256(&expected);
            let mut elapsed = Vec::new();
            for _ in 0..7 {
                let started = Instant::now();
                assert_eq!(serde_json::to_vec(&search()).unwrap(), expected);
                elapsed.push(started.elapsed().as_micros());
            }
            elapsed.sort_unstable();
            (
                elapsed[elapsed.len() / 2],
                elapsed[elapsed.len() - 1],
                digest,
            )
        };
        let one = measure(1);
        let four = measure(4);
        assert_eq!(one.2, four.2);
        eprintln!(
            "tool_argument_fuzzy_parallel_benchmark rows=30000 one_worker_median_us={} one_worker_p95_us={} four_worker_median_us={} four_worker_p95_us={} digest=sha256:{}",
            one.0, one.1, four.0, four.1, one.2
        );
    }

    #[test]
    fn message_search_three_modes_by_three_fields_share_one_result_contract() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_messages(
            &db,
            &[
                ("tool", "placeholder"),
                ("tool", "distractor"),
                ("tool", "second target"),
            ],
        );
        db.conn
            .execute_batch(
                r#"update messages set
                       kind = 'tool_call', tool_name = 'exec_command',
                       content = '{"args":{"cmd":"cargo test --workspace"},"kind":"tool_call","tool_name":"exec_command"}'
                   where seq = 0;
                   update messages set
                       kind = 'tool_call', tool_name = 'read_file',
                       content = '{"args":{"cmd":"open notes.md"},"kind":"tool_call","tool_name":"read_file"}'
                   where seq = 1;
                   update messages set
                       kind = 'tool_call', tool_name = 'exec_command',
                       content = '{"args":{"cmd":"cargo test --workspace"},"kind":"tool_call","tool_name":"exec_command"}'
                   where seq = 2;"#,
            )
            .unwrap();

        let cases = [
            (
                SearchField::Content,
                MessageSearchMode::Literal,
                "cargo test",
            ),
            (
                SearchField::Content,
                MessageSearchMode::Regex,
                r"cargo\s+test",
            ),
            (SearchField::Content, MessageSearchMode::Fuzzy, "crgo tst"),
            (SearchField::ToolName, MessageSearchMode::Literal, "exec"),
            (SearchField::ToolName, MessageSearchMode::Regex, r"^exec_"),
            (SearchField::ToolName, MessageSearchMode::Fuzzy, "excmd"),
            (
                SearchField::ToolArgument,
                MessageSearchMode::Literal,
                "cargo test",
            ),
            (
                SearchField::ToolArgument,
                MessageSearchMode::Regex,
                r"cargo\s+test",
            ),
            (
                SearchField::ToolArgument,
                MessageSearchMode::Fuzzy,
                "crgo tst",
            ),
        ];

        for (field, match_mode, query) in cases {
            let (hits, explain) = db
                .search_messages_with_explain(
                    query,
                    &MessageFilters {
                        kinds: Some(vec![crate::models::MessageKind::ToolCall]),
                        field: Some(field),
                        argument_path: (field == SearchField::ToolArgument)
                            .then(|| "/cmd".to_string()),
                        match_mode,
                        limit: 10,
                        ..Default::default()
                    },
                    true,
                )
                .unwrap_or_else(|error| panic!("{field:?}/{match_mode:?}: {error:#}"));
            if match_mode == MessageSearchMode::Fuzzy {
                assert_eq!(
                    hits[0].fuzzy_score, hits[1].fuzzy_score,
                    "identical projected values must exercise the stable identity tie-break"
                );
            }
            assert_eq!(
                hit_keys(hits),
                vec![("claude:s1".into(), 0), ("claude:s1".into(), 2)],
                "{field:?}/{match_mode:?}"
            );
            assert!(explain.is_some(), "{field:?}/{match_mode:?}");
            let page = db
                .search_messages(
                    query,
                    &MessageFilters {
                        kinds: Some(vec![crate::models::MessageKind::ToolCall]),
                        field: Some(field),
                        argument_path: (field == SearchField::ToolArgument)
                            .then(|| "/cmd".to_string()),
                        match_mode,
                        limit: 1,
                        offset: 1,
                        ..Default::default()
                    },
                )
                .unwrap_or_else(|error| panic!("paged {field:?}/{match_mode:?}: {error:#}"));
            assert_eq!(
                hit_keys(page),
                vec![("claude:s1".into(), 2)],
                "paged {field:?}/{match_mode:?}"
            );
        }
    }

    #[test]
    fn non_fuzzy_message_batches_match_materialized_search_across_fields_and_offsets() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_messages(
            &db,
            &[
                ("user", "alpha needle"),
                ("tool", "placeholder"),
                ("user", "omega needle"),
            ],
        );
        db.conn
            .execute(
                "update messages
                    set kind = 'tool_call',
                        tool_name = 'exec_command',
                        content = '{\"args\":{\"cmd\":\"cargo test needle\"}}'
                  where seq = 1",
                [],
            )
            .unwrap();

        for (field, match_mode, query, argument_path) in [
            (
                SearchField::Content,
                MessageSearchMode::Literal,
                "needle",
                None,
            ),
            (
                SearchField::Content,
                MessageSearchMode::Regex,
                "n[e]+dle",
                None,
            ),
            (SearchField::Content, MessageSearchMode::Literal, "", None),
            (
                SearchField::ToolName,
                MessageSearchMode::Literal,
                "exec",
                None,
            ),
            (
                SearchField::ToolArgument,
                MessageSearchMode::Literal,
                "cargo test",
                Some("/cmd".to_string()),
            ),
        ] {
            let filters = MessageFilters {
                field: Some(field),
                argument_path,
                match_mode,
                limit: 0,
                offset: 1,
                ..Default::default()
            };
            let materialized = db
                .search_messages_ordered(query, &filters, MessageOrder::OldestFirst)
                .unwrap();
            for batch_size in [1, 2, 17] {
                let mut batched = Vec::new();
                let outcome = db
                    .visit_messages_in_batches(
                        query,
                        &filters,
                        true,
                        MessageOrder::OldestFirst,
                        NonZeroUsize::new(batch_size).unwrap(),
                        |batch| {
                            assert!(batch.len() <= batch_size);
                            batched.extend(batch);
                            Ok(MessageBatchControl::Continue)
                        },
                    )
                    .unwrap_or_else(|error| {
                        panic!("{field:?}/{match_mode:?}/batch={batch_size}: {error:#}")
                    });
                assert!(outcome.exhausted);
                assert_eq!(outcome.rows_visited, materialized.len());
                assert!(outcome.explain.is_some());
                assert_eq!(
                    hit_keys(batched),
                    hit_keys(materialized.clone()),
                    "{field:?}/{match_mode:?}/batch={batch_size}"
                );
            }
        }
    }

    #[test]
    fn newest_edge_batches_stream_the_post_offset_selection_in_chronological_order() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_messages(
            &db,
            &[
                ("user", "needle zero"),
                ("user", "needle one"),
                ("user", "needle two"),
                ("user", "needle three"),
                ("user", "needle four"),
            ],
        );
        let filters = MessageFilters {
            session_id: Some("claude:s1".into()),
            limit: 0,
            offset: 2,
            ..Default::default()
        };
        let (mut materialized, materialized_explain) = db
            .search_messages_with_explain_order("needle", &filters, true, MessageOrder::NewestFirst)
            .unwrap();
        materialized.reverse();

        for batch_size in [1, 2, 17] {
            let mut batched = Vec::new();
            let outcome = db
                .visit_messages_in_batches(
                    "needle",
                    &filters,
                    true,
                    MessageOrder::NewestFirst,
                    NonZeroUsize::new(batch_size).unwrap(),
                    |batch| {
                        batched.extend(batch);
                        Ok(MessageBatchControl::Continue)
                    },
                )
                .unwrap();
            assert!(outcome.exhausted);
            assert_eq!(hit_keys(batched), hit_keys(materialized.clone()));
            assert_eq!(
                outcome.explain.as_ref().map(|explain| explain.corpus),
                materialized_explain.as_ref().map(|explain| explain.corpus)
            );
            assert_eq!(
                outcome
                    .explain
                    .as_ref()
                    .and_then(|explain| explain.candidates),
                materialized_explain
                    .as_ref()
                    .and_then(|explain| explain.candidates)
            );
        }
    }

    #[test]
    fn non_fuzzy_message_batches_hold_one_snapshot_and_stop_without_draining() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("index.db");
        let db = Db::open(&path).unwrap();
        let writer = Db::open(&path).unwrap();
        seed_messages(
            &db,
            &[
                ("user", "needle zero"),
                ("user", "needle one"),
                ("user", "needle two"),
            ],
        );
        let filters = MessageFilters {
            limit: 0,
            ..Default::default()
        };
        let mut seen = Vec::new();
        let snapshot = db
            .visit_messages_in_batches(
                "needle",
                &filters,
                false,
                MessageOrder::OldestFirst,
                NonZeroUsize::new(1).unwrap(),
                |batch| {
                    seen.extend(batch.into_iter().map(|hit| hit.seq));
                    if seen.len() == 1 {
                        writer
                            .conn
                            .execute(
                                "insert into messages (
                                     session_id, provider, seq, role, content
                                 ) values ('claude:s1', 'claude', 3, 'user', 'needle late')",
                                [],
                            )
                            .unwrap();
                    }
                    Ok(MessageBatchControl::Continue)
                },
            )
            .unwrap();
        assert!(snapshot.exhausted);
        assert_eq!(seen, [0, 1, 2]);
        assert_eq!(db.search_messages("needle", &filters).unwrap().len(), 4);

        let mut delivered = 0;
        let stopped = db
            .visit_messages_in_batches(
                "needle",
                &filters,
                false,
                MessageOrder::OldestFirst,
                NonZeroUsize::new(2).unwrap(),
                |batch| {
                    delivered += batch.len();
                    Ok(MessageBatchControl::Stop)
                },
            )
            .unwrap();
        assert_eq!(delivered, 2);
        assert_eq!(stopped.rows_visited, 2);
        assert!(!stopped.exhausted);
        assert!(stopped.explain.is_none());
        let checkpoint_busy: i64 = writer
            .conn
            .query_row("pragma wal_checkpoint(passive)", [], |row| row.get(0))
            .expect("early stop drops the read transaction without draining unread rows");
        assert_eq!(checkpoint_busy, 0);
    }

    #[test]
    fn non_fuzzy_message_batches_finish_legacy_index_maintenance_before_the_snapshot() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        enable_v3_custom_trigram_compatibility(&db);
        seed_messages(&db, &[("user", "socket failed with ECONNRESET today")]);
        let filters = MessageFilters {
            match_mode: MessageSearchMode::Regex,
            ..Default::default()
        };
        let mut seen = Vec::new();

        let outcome = db
            .visit_messages_in_batches(
                "ECONNRESET",
                &filters,
                false,
                MessageOrder::OldestFirst,
                NonZeroUsize::new(1).unwrap(),
                |batch| {
                    seen.extend(batch);
                    Ok(MessageBatchControl::Continue)
                },
            )
            .unwrap();

        assert!(outcome.exhausted);
        assert_eq!(seen.len(), 1);
        assert!(seen[0].content.contains("ECONNRESET"));
        assert!(
            crate::trigram_index::base_max_id(&db.conn).unwrap() > 0,
            "legacy trigram maintenance must finish before the read transaction starts"
        );

        let error = db
            .visit_messages_in_batches(
                "ECONNRESET",
                &filters,
                true,
                MessageOrder::OldestFirst,
                NonZeroUsize::new(1).unwrap(),
                |_| Ok(MessageBatchControl::Continue),
            )
            .unwrap_err()
            .to_string();
        assert!(
            error.contains("planner counts and results share one snapshot"),
            "{error}"
        );
    }

    #[test]
    fn message_search_validation_is_identical_for_all_three_fields() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        for field in [
            SearchField::Content,
            SearchField::ToolName,
            SearchField::ToolArgument,
        ] {
            let filters = |match_mode, limit, offset| MessageFilters {
                field: Some(field),
                argument_path: (field == SearchField::ToolArgument).then(|| "/cmd".into()),
                match_mode,
                limit,
                offset,
                ..Default::default()
            };
            let malformed = db
                .search_messages("[", &filters(MessageSearchMode::Regex, 10, 0))
                .unwrap_err()
                .to_string();
            assert!(
                malformed.contains("invalid regex"),
                "{field:?}: {malformed}"
            );

            let short = db
                .search_messages("ab", &filters(MessageSearchMode::Fuzzy, 10, 0))
                .unwrap_err()
                .to_string();
            assert!(
                short.contains("at least 3 characters"),
                "{field:?}: {short}"
            );

            let unlimited = db
                .search_messages("abc", &filters(MessageSearchMode::Fuzzy, 0, 0))
                .unwrap_err()
                .to_string();
            assert!(
                unlimited.contains("finite non-zero limit"),
                "{field:?}: {unlimited}"
            );

            let large_offset =
                db.search_messages("abc", &filters(MessageSearchMode::Fuzzy, 2, 9_999));
            assert!(
                large_offset.is_ok(),
                "{field:?}: finite fuzzy offsets have no arbitrary result window: {large_offset:?}"
            );
        }
    }

    #[test]
    fn tool_argument_search_handles_json_shapes_unicode_punctuation_and_large_values() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_messages(
            &db,
            &[
                ("tool", "malformed"),
                ("tool", "missing args"),
                ("tool", "scalar args"),
                ("tool", "null"),
                ("tool", "array"),
                ("tool", "nested"),
                ("tool", "large"),
            ],
        );
        let large = format!("{} cargo test --workspace", "x".repeat(128 * 1024));
        let rows = [
            "{malformed".to_string(),
            r#"{"kind":"tool_call"}"#.to_string(),
            r#"{"args":"scalar","kind":"tool_call"}"#.to_string(),
            r#"{"args":{"cmd":null},"kind":"tool_call"}"#.to_string(),
            r#"{"args":{"cmd":["café","C++","--path"]},"kind":"tool_call"}"#.to_string(),
            r#"{"args":{"request":{"path":"src/quoted file.rs"}},"kind":"tool_call"}"#.to_string(),
            serde_json::json!({"args": {"cmd": large}, "kind": "tool_call"}).to_string(),
        ];
        for (seq, content) in rows.iter().enumerate() {
            db.conn
                .execute(
                    "update messages set kind='tool_call', tool_name='ÄTool::C++', content=?1
                     where seq=?2",
                    params![content, seq as i64],
                )
                .unwrap();
        }
        let argument = |path: &str, mode| MessageFilters {
            field: Some(SearchField::ToolArgument),
            argument_path: Some(path.into()),
            match_mode: mode,
            limit: 10,
            ..Default::default()
        };

        assert_eq!(
            hit_keys(
                db.search_messages("café", &argument("/cmd", MessageSearchMode::Literal))
                    .unwrap()
            ),
            vec![("claude:s1".into(), 4)]
        );
        assert_eq!(
            hit_keys(
                db.search_messages(
                    r#"C\+\+.*--path"#,
                    &argument("/cmd", MessageSearchMode::Regex),
                )
                .unwrap()
            ),
            vec![("claude:s1".into(), 4)]
        );
        assert_eq!(
            hit_keys(
                db.search_messages(
                    "quoted file.rs",
                    &argument("/request/path", MessageSearchMode::Literal),
                )
                .unwrap()
            ),
            vec![("claude:s1".into(), 5)]
        );
        assert_eq!(
            hit_keys(
                db.search_messages("null", &argument("/cmd", MessageSearchMode::Literal))
                    .unwrap()
            ),
            vec![("claude:s1".into(), 3)]
        );
        assert_eq!(
            hit_keys(
                db.search_messages(
                    "cargo test --workspace",
                    &argument("/cmd", MessageSearchMode::Literal),
                )
                .unwrap()
            ),
            vec![("claude:s1".into(), 6)]
        );
        assert!(
            db.search_messages("scalar", &argument("/cmd", MessageSearchMode::Literal))
                .unwrap()
                .is_empty(),
            "a pointer below scalar args and malformed/missing envelopes must project NULL"
        );

        for mode in [MessageSearchMode::Literal, MessageSearchMode::Regex] {
            let query = if mode == MessageSearchMode::Literal {
                "ätool::c++"
            } else {
                r#"(?i)^ätool::c\+\+$"#
            };
            assert_eq!(
                db.search_messages(
                    query,
                    &MessageFilters {
                        field: Some(SearchField::ToolName),
                        match_mode: mode,
                        limit: 10,
                        ..Default::default()
                    },
                )
                .unwrap()
                .len(),
                7,
                "{mode:?} must preserve Unicode and punctuation in tool names"
            );
        }
    }

    #[test]
    fn fuzzy_content_reports_complete_filtered_corpus_scoring() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute(
                "insert into sessions (
                     id, provider, provider_session_id, preview_text, source_path,
                     parse_version, discovery_source
                 ) values ('s1','claude','s1','','/p','1','test')",
                [],
            )
            .unwrap();
        let tx = db.conn.unchecked_transaction().unwrap();
        {
            let mut insert = tx
                .prepare(
                    "insert into messages(session_id, provider, seq, role, content)
                     values ('s1','claude',?1,'user',?2)",
                )
                .unwrap();
            for seq in 0..1_205_i64 {
                insert
                    .execute(params![seq, format!("abc candidate {seq:04}")])
                    .unwrap();
            }
        }
        tx.commit().unwrap();

        let (hits, explain) = db
            .search_messages_with_explain(
                "abc",
                &MessageFilters {
                    match_mode: MessageSearchMode::Fuzzy,
                    limit: 1,
                    ..Default::default()
                },
                true,
            )
            .unwrap();

        assert_eq!(hits.len(), 1);
        let explain = explain.unwrap();
        assert_eq!(
            explain.prefilter_skipped.as_deref(),
            Some("complete filtered corpus scored, retaining at most min(offset + limit, corpus) ranked rows")
        );
        assert_eq!(explain.candidates, Some(1_205));
        assert_eq!(explain.corpus, 1_205);
    }

    #[test]
    fn v4_prefilter_work_stays_selective_across_one_two_four_x_corpora() {
        for corpus in [200_i64, 400, 800] {
            let dir = tempfile::tempdir().unwrap();
            let db = Db::open(&dir.path().join("index.db")).unwrap();
            db.conn
                .execute(
                    "insert into sessions (
                         id, provider, provider_session_id, preview_text, source_path,
                         parse_version, discovery_source
                     ) values ('s1','claude','s1','','/p','1','test')",
                    [],
                )
                .unwrap();
            let tx = db.conn.unchecked_transaction().unwrap();
            {
                let mut insert = tx
                    .prepare(
                        "insert into messages(session_id, provider, seq, role, content)
                         values ('s1','claude',?1,'user',?2)",
                    )
                    .unwrap();
                insert
                    .execute(params![0_i64, "rare fuzzy anchor C++ --path"])
                    .unwrap();
                for seq in 1..corpus {
                    insert
                        .execute(params![seq, format!("unrelated filler row {seq:04}")])
                        .unwrap();
                }
            }
            tx.commit().unwrap();

            for (mode, query) in [
                (MessageSearchMode::Literal, "fuzzy anchor C++"),
                (MessageSearchMode::Regex, r"fuzzy\s+anchor\s+C\+\+"),
                (MessageSearchMode::Fuzzy, "fzzy anchr C++"),
            ] {
                let (hits, explain) = db
                    .search_messages_with_explain(
                        query,
                        &MessageFilters {
                            match_mode: mode,
                            limit: 10,
                            ..Default::default()
                        },
                        true,
                    )
                    .unwrap();
                assert_eq!(hit_keys(hits), vec![("s1".into(), 0)], "{corpus}/{mode:?}");
                let explain = explain.unwrap();
                assert_eq!(explain.corpus, corpus, "{corpus}/{mode:?}");
                assert!(
                    explain.candidates.is_some_and(|count| count < corpus / 4),
                    "candidate work must stay selective as the unrelated corpus scales: \
                     corpus={corpus} mode={mode:?} explain={explain:?}"
                );
            }
        }
    }

    #[test]
    fn message_kind_call_id_and_offset_share_one_query_contract() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_messages(&db, &[("tool", "first call"), ("tool", "first result")]);
        db.conn
            .execute_batch(
                "update messages set kind = 'tool_call', tool_call_id = 'call-1' where seq = 0;
                 update messages set kind = 'tool_result', tool_call_id = 'call-1' where seq = 1;",
            )
            .unwrap();

        let calls = db
            .search_messages(
                "",
                &MessageFilters {
                    kinds: Some(vec![crate::models::MessageKind::ToolCall]),
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(calls.len(), 1);
        assert_eq!(calls[0].kind, crate::models::MessageKind::ToolCall);
        assert_eq!(calls[0].tool_call_id.as_deref(), Some("call-1"));

        let page = db
            .search_messages(
                "",
                &MessageFilters {
                    limit: 1,
                    offset: 1,
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(page.len(), 1);
        assert_eq!(page[0].seq, 1);
        assert_eq!(page[0].kind, crate::models::MessageKind::ToolResult);
    }

    #[test]
    fn message_context_rejects_negative_window_bounds() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let error = db
            .message_context("missing", 0, -1, 0)
            .unwrap_err()
            .to_string();
        assert!(error.contains("before must be non-negative"), "{error}");
        let error = db
            .message_context("missing", 0, 0, -1)
            .unwrap_err()
            .to_string();
        assert!(error.contains("after must be non-negative"), "{error}");
    }

    #[test]
    fn query_timeout_interrupts_expensive_work_and_resets_the_handler() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();

        let error = with_sqlite_query_timeout(
            &db.conn,
            std::num::NonZeroU64::new(1),
            "read-only SQL query",
            "increase timeout_ms or pass 0 for no timeout",
            || {
                db.conn
                    .query_row(
                        "with recursive n(x) as (values(0) union all select x + 1 from n where x < 100000000) select sum(x) from n",
                        [],
                        |row| row.get::<_, i64>(0),
                    )
                    .map_err(Into::into)
            },
        )
        .unwrap_err()
        .to_string();
        assert!(error.contains("timed out after 1 ms"), "{error}");

        assert_eq!(
            db.conn
                .query_row("select 1", [], |row| row.get::<_, i64>(0))
                .unwrap(),
            1,
            "the RAII guard must clear SQLite's progress handler after interruption"
        );
    }

    #[test]
    fn persistent_interrupt_cancels_a_statement_started_after_the_flag_is_set() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let cancellation = Arc::new(AtomicBool::new(false));
        db.interrupt_while(Arc::clone(&cancellation))
            .expect("arming cancellation is a precondition of this test");

        // Setting the flag before SQLite starts the statement reproduces the race that a one-shot
        // InterruptHandle cannot cover: interrupt() is a no-op when no statement is active.
        cancellation.store(true, Ordering::Release);
        let error = db
            .conn
            .query_row(
                "with recursive n(value) as (
                     values(1)
                     union all
                     select value + 1 from n where value < 1000000
                 )
                 select sum(value) from n",
                [],
                |row| row.get::<_, i64>(0),
            )
            .unwrap_err();
        assert!(matches!(
            error,
            rusqlite::Error::SqliteFailure(inner, _)
                if inner.code == rusqlite::ErrorCode::OperationInterrupted
        ));
    }

    #[test]
    fn query_cancellation_registered_after_cancel_still_interrupts_the_next_statement() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let cancellation = QueryCancellation::new();

        cancellation.cancel();
        db.install_query_cancellation(&cancellation)
            .expect("arming cancellation is a precondition of this test");

        let error = db
            .conn
            .query_row(
                "with recursive n(value) as (
                     values(1)
                     union all
                     select value + 1 from n where value < 1000000
                 )
                 select sum(value) from n",
                [],
                |row| row.get::<_, i64>(0),
            )
            .unwrap_err();
        assert!(matches!(
            error,
            rusqlite::Error::SqliteFailure(inner, _)
                if inner.code == rusqlite::ErrorCode::OperationInterrupted
        ));
    }

    #[test]
    fn message_batch_allocation_failure_names_the_unit_and_recovery() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_messages(&db, &[("user", "needle")]);
        let error = db
            .visit_messages_in_batches(
                "needle",
                &MessageFilters {
                    limit: 0,
                    ..Default::default()
                },
                false,
                MessageOrder::OldestFirst,
                NonZeroUsize::new(usize::MAX).unwrap(),
                |_| Ok(MessageBatchControl::Continue),
            )
            .unwrap_err()
            .to_string();
        assert!(error.contains("batch_rows"));
        assert!(error.contains(&usize::MAX.to_string()));
        assert!(error.contains("pass a smaller positive row count"));
    }

    #[test]
    fn query_timeout_never_panics_when_deadline_exceeds_platform_instant_range() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();

        let result = with_sqlite_query_timeout(
            &db.conn,
            std::num::NonZeroU64::new(u64::MAX),
            "read-only SQL query",
            "increase timeout_ms or pass 0 for no timeout",
            || {
                db.conn
                    .query_row("select 1", [], |row| row.get::<_, i64>(0))
                    .map_err(Into::into)
            },
        );

        match result {
            Ok(value) => assert_eq!(value, 1),
            Err(error) => assert!(
                error.to_string().contains("timeout_ms is too large"),
                "{error}"
            ),
        }
        assert_eq!(
            db.conn
                .query_row("select 2", [], |row| row.get::<_, i64>(0))
                .unwrap(),
            2,
            "an unrepresentable timeout must not leave a progress handler installed"
        );
    }

    #[test]
    fn message_context_windows_batch_preserves_anchor_order_and_empty_windows() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_messages(
            &db,
            &[
                ("user", "zero"),
                ("assistant", "one"),
                ("user", "two"),
                ("assistant", "three"),
            ],
        );
        let anchors = vec![
            ("claude:s1".to_string(), 3),
            ("missing".to_string(), 10),
            ("claude:s1".to_string(), 0),
        ];

        let windows = db.message_context_windows(&anchors, 1, 1).unwrap();

        assert_eq!(windows.len(), 3);
        assert_eq!(
            windows[0].iter().map(|hit| hit.seq).collect::<Vec<_>>(),
            vec![2, 3]
        );
        assert!(windows[1].is_empty());
        assert_eq!(
            windows[2].iter().map(|hit| hit.seq).collect::<Vec<_>>(),
            vec![0, 1]
        );
    }

    #[test]
    fn session_time_profile_is_bounded_and_uses_typed_message_metadata() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_messages(
            &db,
            &[
                ("user", "start"),
                ("tool", "call"),
                ("tool", "result"),
                ("assistant", "end"),
            ],
        );
        db.conn
            .execute_batch(
                "update messages set ts = '2026-07-10T10:00:00Z' where seq = 0;
                 update messages set ts = '2026-07-10T10:00:05Z', kind = 'tool_call' where seq = 1;
                 update messages set ts = '2026-07-10T10:00:20Z', kind = 'tool_result' where seq = 2;",
            )
            .unwrap();

        let profile = db.session_time_profile("claude:s1").unwrap();
        assert_eq!(profile.messages, 4);
        assert_eq!(profile.timestamped_messages, 3);
        assert_eq!(profile.undated_messages, 1);
        assert_eq!(profile.observed_span_seconds, Some(20));
        assert_eq!(profile.max_message_gap_seconds, Some(15));
        assert_eq!((profile.tool_calls, profile.tool_results), (1, 1));
    }

    #[test]
    fn session_time_profile_uses_intermediate_events_across_months() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_messages(
            &db,
            &[
                ("user", "january"),
                ("assistant", "february"),
                ("user", "april"),
                ("assistant", "undated tail"),
            ],
        );
        db.conn
            .execute_batch(
                "update sessions
                    set created_at = '2026-04-30T00:00:00Z',
                        updated_at = '2026-04-30T00:00:01Z',
                        last_message_at = '2026-04-30T00:00:01Z'
                  where id = 'claude:s1';
                 update messages set ts = '2026-01-01T00:00:00.100Z' where seq = 0;
                 update messages set ts = '2026-02-01T00:00:00.200Z' where seq = 1;
                 update messages set ts = '2026-04-30T00:00:00.300Z' where seq = 2;
                 update messages set ts = null where seq = 3;",
            )
            .unwrap();

        let profile = db.session_time_profile("claude:s1").unwrap();

        assert_eq!(profile.timestamped_messages, 3);
        assert_eq!(profile.undated_messages, 1);
        assert_eq!(
            profile.first_timestamp.unwrap().to_rfc3339(),
            "2026-01-01T00:00:00.100+00:00"
        );
        assert_eq!(
            profile.last_timestamp.unwrap().to_rfc3339(),
            "2026-04-30T00:00:00.300+00:00"
        );
        assert_eq!(profile.observed_span_seconds, Some(10_281_600));
        assert_eq!(profile.max_message_gap_seconds, Some(7_603_200));
    }

    #[test]
    fn parser_health_uses_shared_provider_versions_and_consistent_totals() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.mark_schema_current().unwrap();
        db.conn
            .execute_batch(
                "insert into sessions(id, provider, provider_session_id, preview_text, source_path, parse_version, parse_warning, discovery_source) values
                 ('claude:current','claude','current','','/a','claude-v4',null,'jsonl'),
                 ('claude:stale','claude','stale','','/b','claude-v1','old parser','jsonl');",
            )
            .unwrap();
        db.conn
            .execute(
                "insert into sessions(id, provider, provider_session_id, preview_text, source_path, parse_version, discovery_source)
                 values ('codex:current','codex','current','','/c',?1,'jsonl')",
                [crate::util::provider_parse_version(Provider::Codex)],
            )
            .unwrap();

        let health = db.parser_health().unwrap();
        assert!(health.schema_current);
        assert_eq!(health.indexed_sessions, 3);
        assert_eq!(health.current_sessions, 2);
        assert_eq!(health.stale_sessions, 1);
        assert_eq!(health.parse_warnings, 1);
        let claude = health
            .providers
            .iter()
            .find(|item| item.provider == Provider::Claude)
            .unwrap();
        assert_eq!(claude.expected_parse_version, "claude-v4");
        assert_eq!((claude.current_sessions, claude.stale_sessions), (1, 1));
        assert_eq!(
            db.stale_session_sources().unwrap(),
            vec![(Provider::Claude, "/b".to_string())]
        );
    }

    #[test]
    fn complete_parse_replaces_superseded_identity_for_the_same_source() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let source = std::path::Path::new("/fixture/changing-identity.jsonl");
        let mut old = crate::util::minimal_record(Provider::ClaudeDesktop, source, String::new());
        old.session.id = "claude-desktop:old".into();
        old.session.provider_session_id = "old".into();
        old.session.parse_version = "claude-desktop-local-agent-v1".into();
        old.messages = vec![crate::models::Message {
            seq: 0,
            role: Role::User,
            kind: crate::models::MessageKind::Conversation,
            ts: None,
            tool_name: None,
            tool_call_id: None,
            is_compaction: false,
            content: "obsolete".into(),
            provenance: crate::models::MessageProvenance::default(),
        }];
        db.upsert_session(&old, 1, 1).unwrap();

        let mut current =
            crate::util::minimal_record(Provider::ClaudeDesktop, source, String::new());
        current.session.id = "claude-desktop:current".into();
        current.session.provider_session_id = "current".into();
        current.messages = vec![crate::models::Message {
            seq: 0,
            role: Role::User,
            kind: crate::models::MessageKind::Conversation,
            ts: None,
            tool_name: None,
            tool_call_id: None,
            is_compaction: false,
            content: "replacement".into(),
            provenance: crate::models::MessageProvenance::default(),
        }];
        db.upsert_session(&current, 2, 2).unwrap();

        assert!(db.resolve_session_record("claude-desktop:old").is_err());
        assert_eq!(
            db.resolve_session_record("claude-desktop:current")
                .unwrap()
                .source_path,
            source.to_string_lossy()
        );
        assert!(db
            .search_messages("obsolete", &MessageFilters::default())
            .unwrap()
            .is_empty());
        assert!(db
            .is_file_current(
                Provider::ClaudeDesktop,
                &source.to_string_lossy(),
                2,
                2,
                crate::util::provider_parse_version(Provider::ClaudeDesktop),
            )
            .unwrap());
    }

    #[test]
    fn source_checkpoint_version_backfill_requires_a_matching_source_path() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let source = dir.path().join("session.jsonl");
        let parsed = crate::util::minimal_record(Provider::Claude, &source, String::new());
        db.upsert_session(&parsed, 10, 20).unwrap();
        db.conn
            .execute("update files_seen set parse_version = ''", [])
            .unwrap();

        db.backfill_source_parse_versions().unwrap();
        assert!(db
            .is_file_current(
                Provider::Claude,
                &source.to_string_lossy(),
                10,
                20,
                crate::util::provider_parse_version(Provider::Claude),
            )
            .unwrap());

        db.conn
            .execute_batch(
                "update sessions set source_path = '/different/source.jsonl';
                 update files_seen set parse_version = '';",
            )
            .unwrap();
        db.backfill_source_parse_versions().unwrap();
        assert!(!db
            .is_file_current(
                Provider::Claude,
                &source.to_string_lossy(),
                10,
                20,
                crate::util::provider_parse_version(Provider::Claude),
            )
            .unwrap());
    }

    #[test]
    fn complete_parse_reconciles_verified_source_aliases() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let alias = std::path::Path::new("/fixture/alias/session.jsonl");
        let canonical = std::path::Path::new("/fixture/canonical/session.jsonl");
        let mut old = crate::util::minimal_record(Provider::Claude, alias, String::new());
        old.session.id = "claude:old-alias".into();
        old.session.provider_session_id = "old-alias".into();
        db.upsert_session(&old, 1, 1).unwrap();
        let mut current = crate::util::minimal_record(Provider::Claude, canonical, String::new());
        current.session.id = "claude:current".into();
        current.session.provider_session_id = "current".into();

        db.upsert_session_reconciling_sources(
            &current,
            2,
            2,
            &[alias.to_string_lossy().into_owned()],
            true,
        )
        .unwrap();

        assert!(db.resolve_session_record("claude:old-alias").is_err());
        assert_eq!(db.indexed_source_identities().unwrap().len(), 1);
        assert_eq!(
            db.indexed_source_identities().unwrap()[0].1,
            canonical.to_string_lossy()
        );
    }

    #[test]
    fn schema_backfill_flag_round_trips() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn.pragma_update(None, "user_version", 2).unwrap();
        assert!(db.needs_backfill().unwrap());
        db.mark_schema_current().unwrap();
        assert!(
            db.needs_backfill().unwrap(),
            "parser rows are backfilled, but the pre-v4 FTS layout is not yet current"
        );
        assert_eq!(db.schema_version().unwrap(), PRE_FTS_PARSER_SCHEMA_VERSION);
        db.migrate_message_search_schema_exclusive().unwrap();
        assert!(!db.needs_backfill().unwrap());
        assert_eq!(db.schema_version().unwrap(), SCHEMA_VERSION);
    }

    #[test]
    fn mark_schema_current_preserves_the_v4_fts_gate_before_promoting_schema_5() {
        // Recurrence guard for the v4-stamped-but-broken hybrid schema. `mark_schema_current` runs
        // on the reindex fast path; it must NEVER stamp SCHEMA_VERSION over a database that has not
        // already reached it. Only the atomic fresh-install (init) and the atomic offline migration
        // — each of which builds the v4 message-search layout in the SAME transaction as the stamp —
        // may promote to v4. If a future edit makes this method stamp SCHEMA_VERSION unconditionally,
        // a pre-v4 or partially-built index would be declared "current" without its trigram objects
        // and dead-lock every command at open. This test fails loudly if that invariant is broken.
        let dir = tempfile::tempdir().unwrap();
        for start in [0_i64, 1, 2, PRE_FTS_PARSER_SCHEMA_VERSION] {
            let path = dir.path().join(format!("v{start}.db"));
            let db = Db::open(&path).unwrap();
            db.conn.pragma_update(None, "user_version", start).unwrap();
            db.mark_schema_current().unwrap();
            assert!(
                db.schema_version().unwrap() < SCHEMA_VERSION,
                "start={start}: mark_schema_current must not promote a pre-v{SCHEMA_VERSION} index to current",
            );
        }
        let v4 = Db::open(&dir.path().join("v4.db")).unwrap();
        v4.conn.pragma_update(None, "user_version", 4).unwrap();
        v4.mark_schema_current().unwrap();
        assert_eq!(v4.schema_version().unwrap(), SCHEMA_VERSION);
    }

    #[test]
    fn clear_all_is_atomic_and_rolls_back_on_failure() {
        // clear_all must be all-or-nothing: a failure partway through must not leave sessions whose
        // messages were already deleted (a stale message_count with zero messages). Force the final
        // delete to fail by dropping files_seen; the transaction must roll the earlier deletes back.
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions (id, provider, provider_session_id, preview_text, source_path,
                     parse_version, discovery_source)
                     values ('s', 'claude', 's', '', '/s.jsonl', 'test', 'fixture');
                 insert into messages (session_id, provider, seq, role, kind, tool_name, content)
                     values ('s', 'claude', 0, 'user', 'message', null, 'keep me');",
            )
            .unwrap();
        db.conn.execute_batch("drop table files_seen;").unwrap();

        assert!(
            db.clear_all().is_err(),
            "clear_all should surface the failing delete"
        );
        let (sessions, messages): (i64, i64) = db
            .conn
            .query_row(
                "select (select count(*) from sessions), (select count(*) from messages)",
                [],
                |row| Ok((row.get(0)?, row.get(1)?)),
            )
            .unwrap();
        assert_eq!(
            (sessions, messages),
            (1, 1),
            "clear_all must roll back all deletes when one fails"
        );
    }

    #[test]
    fn direct_db_open_self_enforces_v4_layout_after_triggers_dropped() {
        // A direct Db::open (embedder path, bypassing SessionSearch's coordinator) on a v4 database
        // whose dual triggers were dropped must self-enforce the layout: after open, inserting a
        // message must maintain messages_trigram rather than silently falling back to word-only
        // indexing (which would make substring/fuzzy search return incomplete results).
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("index.db");
        {
            let db = Db::open(&path).unwrap();
            db.conn
                .execute_batch(
                    "insert into sessions (id, provider, provider_session_id, preview_text,
                         source_path, parse_version, discovery_source)
                         values ('s', 'claude', 's', '', '/s.jsonl', 'test', 'fixture');
                     insert into messages (session_id, provider, seq, role, kind, tool_name, content)
                         values ('s', 'claude', 0, 'user', 'message', null, 'existing-row');
                     drop trigger messages_ai;
                     drop trigger messages_ad;
                     drop trigger messages_au;",
                )
                .unwrap();
        }

        // Reopen directly via Db::open — init() must heal the drifted v4 layout.
        let db = Db::open(&path).unwrap();
        assert!(
            crate::indexer::current_schema_layout_problem(&db.conn)
                .unwrap()
                .is_none(),
            "Db::open must self-enforce a consistent v4 layout"
        );
        // The restored dual trigger must index a NEW insert into messages_trigram. messages_trigram
        // is a detail=none FTS5 table (no phrase/MATCH queries), so observe maintenance through its
        // fts5vocab term table: inserting content with trigrams absent from the existing rows must
        // grow the distinct-term count.
        let terms_before: i64 = db
            .conn
            .query_row("select count(*) from messages_trigram_terms", [], |row| {
                row.get(0)
            })
            .unwrap();
        db.conn
            .execute_batch(
                "insert into messages (session_id, provider, seq, role, kind, tool_name, content)
                     values ('s', 'claude', 1, 'user', 'message', null, 'freshtrigramrow');",
            )
            .unwrap();
        let terms_after: i64 = db
            .conn
            .query_row("select count(*) from messages_trigram_terms", [], |row| {
                row.get(0)
            })
            .unwrap();
        assert!(
            terms_after > terms_before,
            "new insert must be maintained in messages_trigram (terms {terms_before} -> {terms_after})"
        );
    }

    #[test]
    fn open_drops_legacy_fts5_trigram_and_self_heals() {
        // An in-development index may carry the old FTS5 messages_trigram; opening with the current
        // binary must drop it and stand up the custom trigram_index — no out-of-repo transition code
        // needed. (Proves resetting SCHEMA_VERSION to 1 is safe for such indexes: init() fixes the
        // schema objects on open regardless of user_version.)
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("index.db");
        {
            let db = Db::open(&path).unwrap();
            db.conn
                .execute_batch(
                    "drop trigger messages_ai;
                     drop trigger messages_ad;
                     drop trigger messages_au;
                     drop table messages_trigram_terms;
                     drop table messages_trigram_vocab;
                     drop table messages_trigram;
                     create virtual table messages_trigram using fts5(content, \
                     content='messages', content_rowid='id', tokenize='trigram', detail='none');",
                )
                .unwrap();
            crate::fts::install_released_message_word_index(&db.conn).unwrap();
            db.conn.pragma_update(None, "user_version", 3).unwrap();
        }
        let db = Db::open(&path).unwrap();
        let legacy: i64 = db
            .conn
            .query_row(
                "select count(*) from sqlite_master where name='messages_trigram'",
                [],
                |r| r.get(0),
            )
            .unwrap();
        assert_eq!(legacy, 0, "legacy FTS5 messages_trigram dropped on open");
        let custom: i64 = db
            .conn
            .query_row(
                "select count(*) from sqlite_master where name='trigram_postings'",
                [],
                |r| r.get(0),
            )
            .unwrap();
        assert_eq!(custom, 1, "custom trigram_postings present after open");
        seed_messages(&db, &[("user", "an econnreset row")]);
        let hits = db
            .search_messages(
                "econnreset",
                &MessageFilters {
                    match_mode: MessageSearchMode::Regex,
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(hits.len(), 1, "regex search works after the self-heal");
    }

    #[test]
    fn messages_indexes_drop_redundant_singles_and_keep_composites() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("index.db");
        let count_index = |db: &Db, name: &str| -> i64 {
            db.conn
                .query_row(
                    "select count(*) from sqlite_master where type='index' and name=?1",
                    [name],
                    |row| row.get(0),
                )
                .unwrap()
        };

        // Simulate an older branch build that created the now-redundant standalone indexes.
        {
            let db = Db::open(&path).unwrap();
            db.conn
                .execute_batch(
                    "create index if not exists idx_messages_session on messages(session_id);
                     create index if not exists idx_messages_role on messages(role);",
                )
                .unwrap();
            assert_eq!(count_index(&db, "idx_messages_session"), 1, "precondition");
            assert_eq!(count_index(&db, "idx_messages_role"), 1, "precondition");
        }

        // Reopening runs init(), whose `drop index if exists` removes the redundant singles
        // (the composites subsume them by leftmost-prefix) and leaves the final index shape.
        let db = Db::open(&path).unwrap();
        assert_eq!(
            count_index(&db, "idx_messages_session"),
            0,
            "redundant (session_id) dropped"
        );
        assert_eq!(
            count_index(&db, "idx_messages_role"),
            0,
            "redundant (role) dropped"
        );
        for idx in [
            "idx_messages_session_seq",
            "idx_messages_role_ts",
            "idx_messages_ts",
        ] {
            assert_eq!(count_index(&db, idx), 1, "{idx} must exist");
        }
    }

    #[test]
    fn hot_message_queries_use_indexes_not_full_scans() {
        // Performance regression guard: the hot message queries must be served by an index
        // (or the FTS virtual table), never a full `SCAN` of the multi-GB messages table.
        // We populate enough rows and run ANALYZE so the planner's choice is statistics-
        // driven and deterministic, matching production rather than a tiny-table heuristic.
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions(id, provider, provider_session_id, preview_text, \
                   source_path, parse_version, discovery_source) \
                 values('claude:s1','claude','s1','','/x','claude-v1','jsonl');",
            )
            .unwrap();
        {
            let tx = db.conn.unchecked_transaction().unwrap();
            {
                let mut stmt = tx
                    .prepare(
                        "insert into messages(session_id, provider, seq, role, ts, content) \
                         values('claude:s1','claude',?1,?2,?3,?4)",
                    )
                    .unwrap();
                for i in 0..2000i64 {
                    let role = if i % 7 == 0 { "user" } else { "assistant" };
                    let ts = format!("2026-06-{:02}T00:00:00+00:00", (i % 28) + 1);
                    stmt.execute(params![i, role, ts, format!("message number {i} alpha")])
                        .unwrap();
                }
            }
            tx.commit().unwrap();
        }
        db.conn.execute_batch("analyze").unwrap();

        // Join the EXPLAIN QUERY PLAN `detail` column (index 3) for each query.
        let plan = |sql: &str| -> String {
            let mut stmt = db
                .conn
                .prepare(&format!("explain query plan {sql}"))
                .unwrap();
            let rows = stmt.query_map([], |r| r.get::<_, String>(3)).unwrap();
            rows.filter_map(Result::ok).collect::<Vec<_>>().join(" | ")
        };

        // 1. Content search is driven by the messages_fts index (MATCH): the FTS virtual
        //    table supplies matching rowids and the messages rows are fetched by INTEGER
        //    PRIMARY KEY — never a full scan of the messages table.
        let p = plan(
            "select m.id from messages_fts f join messages m on m.id = f.rowid \
             where messages_fts match 'alpha'",
        );
        assert!(
            p.contains("VIRTUAL TABLE INDEX"),
            "content search must be driven by the messages_fts index: {p}"
        );
        assert!(
            p.contains("USING INTEGER PRIMARY KEY") && !p.contains("SCAN m "),
            "messages rows must be reached by rowid from the FTS matches, not scanned: {p}"
        );

        // 2. role [+ order by ts] (corrections / planning / stats) → idx_messages_role_ts.
        let p = plan("select content from messages where role = 'user' order by ts desc");
        assert!(
            p.contains("idx_messages_role_ts"),
            "role/ts query must use the composite: {p}"
        );

        // 3. session_id + seq range (message get / context) → idx_messages_session_seq.
        let p = plan(
            "select content from messages where session_id = 'claude:s1' \
             and seq between 10 and 20 order by seq",
        );
        assert!(
            p.contains("idx_messages_session_seq"),
            "session/seq query must use the composite: {p}"
        );

        // 4. provider + session-sequence page (the common CLI/MCP scoped-page path) must not
        // scan and sort the whole messages table before honoring LIMIT.
        let p = plan(
            "select content from messages where provider = 'claude' \
             order by session_id, seq limit 2",
        );
        assert!(
            p.contains("idx_messages_provider_session_seq") && !p.contains("USE TEMP B-TREE"),
            "provider-scoped pages must use the ordered provider composite without a sort: {p}"
        );
    }

    #[test]
    fn messages_fts_is_rebuilt_when_empty_but_messages_exist() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("index.db");
        // Populate one message (triggers fill messages_fts), then simulate an index that
        // predates messages_fts by dropping the FTS shadow + its sync triggers.
        {
            let db = Db::open(&path).unwrap();
            db.conn
                .execute_batch(
                    "insert into sessions(id, provider, provider_session_id, preview_text, \
                       source_path, parse_version, discovery_source) \
                     values('claude:s1','claude','s1','','/x','claude-v1','jsonl'); \
                     insert into messages(session_id, provider, seq, role, content) \
                     values('claude:s1','claude',0,'user','findthisneedle');",
                )
                .unwrap();
            let hit: i64 = db
                .conn
                .query_row(
                    "select count(*) from messages_fts where messages_fts match 'findthisneedle'",
                    [],
                    |r| r.get(0),
                )
                .unwrap();
            assert_eq!(hit, 1, "precondition: triggers index the inserted message");
            db.conn
                .execute_batch(
                    "drop trigger messages_ai; drop trigger messages_ad; drop trigger messages_au; \
                     drop table messages_fts;",
                )
                .unwrap();
        }
        // Reopen: init() recreates messages_fts (empty) + triggers, and the integrity net
        // rebuilds it from the messages content table so search works again.
        let db = Db::open(&path).unwrap();
        let hit: i64 = db
            .conn
            .query_row(
                "select count(*) from messages_fts where messages_fts match 'findthisneedle'",
                [],
                |r| r.get(0),
            )
            .unwrap();
        assert_eq!(
            hit, 1,
            "messages_fts rebuilt on open when empty but messages exist"
        );
    }

    #[test]
    fn messages_fts_count_reports_index_documents_not_content_rows() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions(id, provider, provider_session_id, preview_text, \
                   source_path, parse_version, discovery_source) \
                 values('claude:s1','claude','s1','','/x','claude-v1','jsonl'); \
                 insert into messages(session_id, provider, seq, role, content) \
                 values('claude:s1','claude',0,'user','indexedtoken');",
            )
            .unwrap();
        assert_eq!(db.message_count().unwrap(), 1);
        assert_eq!(db.messages_fts_count().unwrap(), 1);

        // Simulate a broken/empty FTS index while leaving the external content table
        // (`messages`) populated. FTS5's external-content table view still reports the
        // content row; only the `_docsize` shadow exposes that no document is indexed.
        db.conn
            .execute("delete from messages_fts_docsize", [])
            .unwrap();
        let external_content_rows: i64 = db
            .conn
            .query_row("select count(*) from messages_fts", [], |r| r.get(0))
            .unwrap();
        assert_eq!(external_content_rows, 1);
        assert_eq!(
            db.messages_fts_count().unwrap(),
            0,
            "helper must report indexed docs, not external content rows"
        );
    }

    #[test]
    fn substring_search_matches_inside_tokens_via_custom_index() {
        // The trigram prefilter matches ARBITRARY substrings (inside a token, and multi-word
        // phrases), built lazily by the custom trigram index on first regex use. Exercised
        // end-to-end via the public search_messages regex path.
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_messages(
            &db,
            &[
                ("user", "the socket failed with ECONNRESET) today"),
                ("user", "you forgot the tests again"),
                ("assistant", "an unrelated message"),
            ],
        );
        let find = |needle: &str| -> usize {
            db.search_messages(
                needle,
                &MessageFilters {
                    match_mode: MessageSearchMode::Regex,
                    ..Default::default()
                },
            )
            .unwrap()
            .len()
        };
        // 'ECONNRESET' is INSIDE the token 'ECONNRESET)' — only a substring index finds it.
        assert_eq!(find("ECONNRESET"), 1, "substring inside a token");
        assert_eq!(find("you forgot"), 1, "multi-word phrase substring");
        assert_eq!(find("nonexistent_zz"), 0, "no false positives");
    }

    #[test]
    fn trigram_base_rebuild_restores_searchability_including_short_docs() {
        // Regression: building the custom trigram base from existing content makes EVERY row
        // searchable — including a <3-char message that produces zero trigrams (it must not break
        // the build or the base_max accounting, and must not silently drop the other rows).
        // Exercised via the public search path, which builds the base lazily on first regex use.
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        enable_v3_custom_trigram_compatibility(&db);
        seed_messages(
            &db,
            &[
                ("user", "alpha contains zebracode here"),
                ("user", "bravo contains zebracode too"),
                ("user", "charlie has zebracode as well"),
                ("user", "ok"), // zero-trigram short doc must not break the build
            ],
        );
        let hits = db
            .search_messages(
                "zebracode",
                &MessageFilters {
                    match_mode: MessageSearchMode::Regex,
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(
            hits.len(),
            3,
            "every zebracode row searchable after base build"
        );
        assert_eq!(
            crate::trigram_index::base_max_id(&db.conn).unwrap(),
            4,
            "base covers all messages including the zero-trigram short doc"
        );
    }

    #[test]
    fn messages_fts_updates_are_transactional_with_messages() {
        // #235 RAII / crash-safety: the messages_fts trigger updates are atomic with the message
        // rows. A rolled-back message insert must leave NEITHER a message row NOR an FTS entry — the
        // trigger writes participate in the surrounding transaction and unwind on rollback.
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions(id, provider, provider_session_id, preview_text, \
                   source_path, parse_version, discovery_source) \
                 values('claude:s1','claude','s1','','/x','claude-v1','jsonl');",
            )
            .unwrap();
        let before = db.messages_fts_count().unwrap();
        {
            // Open a transaction, insert a message (the ai trigger indexes it into messages_fts),
            // then DROP the tx without committing → rollback.
            let tx = db.conn.unchecked_transaction().unwrap();
            tx.execute(
                "insert into messages(session_id, provider, seq, role, content) \
                 values('claude:s1','claude',0,'user','rollbackme token here')",
                [],
            )
            .unwrap();
        }
        assert_eq!(
            db.messages_fts_count().unwrap(),
            before,
            "rolled-back insert leaves no messages_fts entry"
        );
        let hit: i64 = db
            .conn
            .query_row(
                "select count(*) from messages_fts where messages_fts match 'rollbackme'",
                [],
                |r| r.get(0),
            )
            .unwrap();
        assert_eq!(
            hit, 0,
            "rolled-back content is not searchable via messages_fts"
        );
    }

    #[test]
    fn storage_allocation_reports_freed_pages_without_scanning_content() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "create table allocation_probe (payload blob not null);
                 insert into allocation_probe(payload) values(zeroblob(2097152));
                 delete from allocation_probe;",
            )
            .unwrap();

        let allocation = db.storage_allocation().unwrap();
        assert!(allocation.total_bytes >= allocation.reclaimable_bytes);
        assert!(
            allocation.reclaimable_bytes > 0,
            "deleted overflow pages must be reported as reclaimable"
        );
    }

    #[test]
    fn replacement_freelist_compaction_preserves_rows_fts_and_search_results() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let large_suffix = " allocation-padding".repeat(32_768);

        for index in 0..6 {
            let id = format!("claude:allocation-{index}");
            let content = format!("original-token-{index}{large_suffix}");
            let mut parsed = parsed_with_messages(&id, &[&content]);
            parsed.session.provider_session_id = format!("allocation-{index}");
            parsed.session.source_path = format!("/allocation/{index}.jsonl");
            db.replace_session(&parsed, index, index).unwrap();
        }
        assert_eq!(db.message_count().unwrap(), 6);
        assert_eq!(db.messages_fts_count().unwrap(), 6);

        for index in 0..3 {
            let id = format!("claude:allocation-{index}");
            let content = format!("replacement-token-{index}");
            let mut parsed = parsed_with_messages(&id, &[&content]);
            parsed.session.provider_session_id = format!("allocation-{index}");
            parsed.session.source_path = format!("/allocation/{index}.jsonl");
            db.replace_session(&parsed, 10 + index, 10 + index).unwrap();
        }
        db.optimize_fts().unwrap();

        let before = db.storage_allocation().unwrap();
        assert!(before.reclaimable_bytes > 0);
        assert_eq!(db.message_count().unwrap(), 6);
        assert_eq!(db.messages_fts_count().unwrap(), 6);
        for index in 0..3 {
            assert_eq!(
                db.search_messages(
                    &format!("replacement-token-{index}"),
                    &MessageFilters::default(),
                )
                .unwrap()
                .len(),
                1
            );
        }

        db.vacuum().unwrap();
        db.checkpoint_truncate().unwrap();

        let after = db.storage_allocation().unwrap();
        assert_eq!(after.reclaimable_bytes, 0);
        assert!(after.total_bytes < before.total_bytes);
        assert_eq!(db.message_count().unwrap(), 6);
        assert_eq!(db.messages_fts_count().unwrap(), 6);
        for index in 0..3 {
            assert_eq!(
                db.search_messages(
                    &format!("replacement-token-{index}"),
                    &MessageFilters::default(),
                )
                .unwrap()
                .len(),
                1
            );
        }
    }

    #[test]
    fn session_replacement_rolls_back_every_index_when_sqlite_is_full() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let mut original = parsed_with_messages("claude:s1", &["original durable token"]);
        original.session.title = Some("original title".into());
        db.replace_session(&original, 1, 1).unwrap();
        db.checkpoint_truncate().unwrap();

        let original_max_pages: i64 = db
            .conn
            .query_row("pragma max_page_count", [], |row| row.get(0))
            .unwrap();
        let current_pages: i64 = db
            .conn
            .query_row("pragma page_count", [], |row| row.get(0))
            .unwrap();
        let free_pages: i64 = db
            .conn
            .query_row("pragma freelist_count", [], |row| row.get(0))
            .unwrap();
        let page_size: i64 = db
            .conn
            .query_row("pragma page_size", [], |row| row.get(0))
            .unwrap();
        db.conn
            .pragma_update(None, "max_page_count", current_pages)
            .unwrap();

        let mut replacement = original.clone();
        replacement.session.title = Some("replacement title".into());
        const REQUIRED_GROWTH_PAGES: i64 = 2;
        const REPLACEMENT_TOKEN: &str = "replacement-full-token ";
        let required_bytes = (free_pages + REQUIRED_GROWTH_PAGES) * page_size;
        let repeats = required_bytes as usize / REPLACEMENT_TOKEN.len() + 1;
        replacement.transcript_text = REPLACEMENT_TOKEN.repeat(repeats);
        replacement.messages[0].content = replacement.transcript_text.clone();
        let error = db.replace_session(&replacement, 2, 2).unwrap_err();

        db.conn
            .pragma_update(None, "max_page_count", original_max_pages)
            .unwrap();
        assert!(error.chain().any(|cause| {
            cause
                .downcast_ref::<rusqlite::Error>()
                .and_then(rusqlite::Error::sqlite_error_code)
                == Some(ErrorCode::DiskFull)
        }));

        let persisted = db.resolve_session("claude:s1").unwrap();
        assert_eq!(persisted.session.title.as_deref(), Some("original title"));
        assert_eq!(persisted.transcript_text, "original durable token");
        assert_eq!(
            db.search_messages("original durable token", &MessageFilters::default())
                .unwrap()
                .len(),
            1
        );
        assert!(db
            .search_messages("replacement-full-token", &MessageFilters::default())
            .unwrap()
            .is_empty());
    }

    #[test]
    fn generated_trigram_query_is_a_superset_in_the_custom_index() {
        // P0b (closes the R1 gap): build the ACTUAL custom trigram index and assert its candidate
        // set (via the structured trigram_prefilter_groups) is a SUPERSET of regex matches.
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions(id, provider, provider_session_id, preview_text, \
                   source_path, parse_version, discovery_source) \
                 values('claude:s1','claude','s1','','/x','claude-v1','jsonl');",
            )
            .unwrap();
        let rows = [
            "you forgot the tests",
            "well You Forgot it",
            "no, that's wrong",
            "we also need more coverage",
            "socket hang up ECONNRESET here",
            "please stop doing that",
            "totally unrelated message",
            "scatter the cats", // contains 'cat' as a substring but no word boundary
        ];
        {
            let tx = db.conn.unchecked_transaction().unwrap();
            {
                let mut stmt = tx
                    .prepare(
                        "insert into messages(session_id, provider, seq, role, content) \
                         values('claude:s1','claude',?1,'user',?2)",
                    )
                    .unwrap();
                for (i, row) in rows.iter().enumerate() {
                    stmt.execute(params![i as i64, row]).unwrap();
                }
            }
            tx.commit().unwrap();
        }
        crate::trigram_index::build(&db.conn, &db.runtime).unwrap();
        let patterns = [
            r"\byou forgot\b",
            r"\bno,?\s+that'?s\b",
            r"\balso need\b",
            "ECONNRESET",
            r"\bstop doing\b",
            r"\bcat\b", // matches none (no boundary), but candidate "scatter the cats" is a superset
        ];
        for pat in patterns {
            let regex = regex::Regex::new(&format!("(?i){pat}")).unwrap();
            // Ground truth: ids whose content the regex matches.
            let expected: Vec<i64> = {
                let mut stmt = db.conn.prepare("select id, content from messages").unwrap();
                let iter = stmt
                    .query_map([], |row| {
                        Ok((row.get::<_, i64>(0)?, row.get::<_, String>(1)?))
                    })
                    .unwrap();
                iter.filter_map(Result::ok)
                    .filter(|(_, c)| regex.is_match(c))
                    .map(|(id, _)| id)
                    .collect()
            };
            if let Some(groups) = crate::trigram::trigram_prefilter_groups(pat) {
                let candidates = crate::trigram_index::candidates(&db.conn, &groups).unwrap();
                for id in &expected {
                    assert!(
                        candidates.contains(id),
                        "SUPERSET VIOLATION: {pat:?} -> {groups:?} missed id {id}",
                    );
                }
            }
            // When None, the caller falls back to a scan, which is trivially a superset.
        }
    }

    #[test]
    fn detail_mode_comparison_like_on_external_content() {
        // #230: empirically compare the trigram methods for an EXTERNAL-CONTENT table over
        // `messages`, to ground the #231 decision with real numbers (NOT the multi-GB real DB):
        //   (A) detail='full' + MATCH phrase  — the original baseline (positions stored; biggest).
        //   (B) detail='none' + content LIKE  — works on external content (FTS5 fetches the value
        //       from `messages` to reject false-positives; the SQLite forum notes LIKE/GLOB *fails*
        //       on fully *contentless* tables, which ours is not).
        //   (C) detail='none' + AND-of-trigrams MATCH — THE METHOD WE ADOPTED. The prefilter never
        //       needs adjacency (the regex re-verifies), so trigrams are ANDed as independent terms
        //       instead of a phrase; that reads only doclists, so detail='none' (no positions) is
        //       sufficient and ~3-5x smaller. This test asserts (C) returns the right rows on a
        //       real detail='none' external-content table and reports the size delta vs (A).
        let dir = tempfile::tempdir().unwrap();
        let size_of = |variant: &str, detail_clause: &str| -> (i64, rusqlite::Connection) {
            let conn =
                rusqlite::Connection::open(dir.path().join(format!("{variant}.db"))).unwrap();
            conn.execute_batch(
                "create table messages(id integer primary key, content text not null);",
            )
            .unwrap();
            {
                let tx = conn.unchecked_transaction().unwrap();
                {
                    let mut stmt = tx
                        .prepare("insert into messages(content) values(?1)")
                        .unwrap();
                    stmt.execute(["the socket failed with ECONNRESET) today"])
                        .unwrap();
                    stmt.execute(["you forgot the tests again"]).unwrap();
                    stmt.execute(["an unrelated assistant message"]).unwrap();
                    // Filler so the index-size delta between the two detail modes is measurable.
                    for i in 0..3000 {
                        stmt.execute([format!(
                            "filler row {i} lorem ipsum dolor sit amet consectetur adipiscing"
                        )])
                        .unwrap();
                    }
                }
                tx.commit().unwrap();
            }
            conn.execute_batch(&format!(
                "create virtual table tri using fts5(content, content='messages', \
                   content_rowid='id', tokenize='trigram'{detail_clause}); \
                 insert into tri(tri) values('rebuild');",
            ))
            .unwrap();
            let pages: i64 = conn
                .query_row("pragma page_count", [], |r| r.get(0))
                .unwrap();
            let page_size: i64 = conn
                .query_row("pragma page_size", [], |r| r.get(0))
                .unwrap();
            (pages * page_size, conn)
        };

        let (full_bytes, full) = size_of("full", "");
        let (none_bytes, none) = size_of("none", ", detail='none'");

        // (A) detail='full' + MATCH: substring inside a token + multi-word phrase.
        let full_match = |q: &str| -> i64 {
            full.query_row("select count(*) from tri where tri match ?1", [q], |r| {
                r.get(0)
            })
            .unwrap()
        };
        assert_eq!(
            full_match("\"econnreset\""),
            1,
            "detail=full MATCH substring-in-token"
        );
        assert_eq!(
            full_match("\"you forgot\""),
            1,
            "detail=full MATCH multi-word phrase"
        );

        // (B) THE key question: detail='none' + LIKE on EXTERNAL content. If FTS5 fetches the
        // value from `messages` to verify, these return the correct row; if it behaves like a
        // contentless table, they return 0 and detail='none'+LIKE is NOT viable here.
        let none_like = |needle: &str| -> i64 {
            none.query_row(
                "select count(*) from tri where content like ?1 escape '\\'",
                [format!("%{needle}%")],
                |r| r.get(0),
            )
            .unwrap()
        };
        assert_eq!(
            none_like("econnreset"),
            1,
            "detail=none LIKE substring-in-token MUST work on external content",
        );
        assert_eq!(
            none_like("you forgot"),
            1,
            "detail=none LIKE multi-word phrase MUST work on external content",
        );
        // A non-existent substring must return nothing (guards against a silent full match).
        assert_eq!(
            none_like("zzqqxx_absent"),
            0,
            "detail=none LIKE rejects absent substring"
        );

        // (C) detail='none' + AND-of-trigrams MATCH — THE PRODUCTION METHOD. Build the query the
        // way `trigram_prefilter` does (boolean AND of the needle's 3-grams, no phrase) and run it
        // against the real detail='none' table. It must return the matching row(s) (a SUPERSET the
        // caller's regex then verifies) and reject an absent needle — proving detail='none' is
        // sufficient for our prefilter without the positions that detail='full' would store.
        let none_match = |needle: &str| -> i64 {
            let query = crate::trigram::trigram_prefilter(needle)
                .unwrap_or_else(|| panic!("needle {needle:?} must be prefilterable"));
            none.query_row(
                "select count(*) from tri where tri match ?1",
                [query],
                |r| r.get(0),
            )
            .unwrap()
        };
        assert!(
            none_match("econnreset") >= 1,
            "detail=none AND-of-trigrams MATCH finds substring-in-token on external content",
        );
        assert!(
            none_match("you forgot") >= 1,
            "detail=none AND-of-trigrams MATCH finds multi-word substring on external content",
        );
        assert_eq!(
            none_match("zzqqwwxx"),
            0,
            "detail=none AND-of-trigrams MATCH rejects an absent needle",
        );

        // (D) Confirm LIKE actually engages the trigram index rather than scanning `messages`.
        let plan: String = {
            let mut stmt = none
                .prepare(
                    "explain query plan select rowid from tri \
                     where content like '%econnreset%' escape '\\'",
                )
                .unwrap();
            let rows = stmt
                .query_map([], |r| r.get::<_, String>(3))
                .unwrap()
                .filter_map(Result::ok)
                .collect::<Vec<_>>()
                .join(" | ");
            rows
        };
        // (E) Report the measured deltas for the #231 decision.
        eprintln!(
            "[#230] index size: detail=full={}KB  detail=none={}KB  (full is {:.1}x none)",
            full_bytes / 1024,
            none_bytes / 1024,
            full_bytes as f64 / none_bytes.max(1) as f64,
        );
        eprintln!("[#230] detail=none LIKE query plan: {plan}");
        assert!(
            !plan.to_lowercase().contains("scan messages"),
            "detail=none LIKE should not linear-scan the messages table; plan was: {plan}",
        );
    }

    #[test]
    fn regex_search_composes_with_role_and_session_scope() {
        // Each search scans only its needed SUBSET: a --regex query restricts via role / session
        // filters (the trigram prefilter is a SUPERSET the Rust regex re-verifies). Exercised via
        // the public search_messages path, which uses the custom trigram index (built lazily).
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions(id, provider, provider_session_id, preview_text, \
                   source_path, parse_version, discovery_source) values \
                   ('claude:a','claude','a','','/x','v1','jsonl'), \
                   ('claude:b','claude','b','','/x','v1','jsonl');",
            )
            .unwrap();
        {
            let tx = db.conn.unchecked_transaction().unwrap();
            {
                let mut stmt = tx
                    .prepare(
                        "insert into messages(session_id, provider, seq, role, content) \
                         values(?1,'claude',?2,?3,?4)",
                    )
                    .unwrap();
                stmt.execute(params!["claude:a", 0, "user", "needle_xyz in a user"])
                    .unwrap();
                stmt.execute(params![
                    "claude:a",
                    1,
                    "assistant",
                    "needle_xyz in a assistant"
                ])
                .unwrap();
                stmt.execute(params!["claude:b", 0, "user", "needle_xyz in b user"])
                    .unwrap();
            }
            tx.commit().unwrap();
        }
        let count = |role: Option<Role>, session_id: Option<&str>| -> usize {
            db.search_messages(
                "needle_xyz",
                &MessageFilters {
                    match_mode: MessageSearchMode::Regex,
                    role,
                    session_id: session_id.map(str::to_string),
                    ..Default::default()
                },
            )
            .unwrap()
            .len()
        };
        assert_eq!(count(None, None), 3, "unscoped: all three rows");
        assert_eq!(
            count(Some(Role::User), None),
            2,
            "role scope narrows to user rows"
        );
        assert_eq!(
            count(None, Some("claude:a")),
            2,
            "session scope narrows to session a"
        );
        assert_eq!(
            count(Some(Role::User), Some("claude:a")),
            1,
            "role+session scope composes",
        );
    }

    #[test]
    fn trigram_search_correct_across_all_providers() {
        // #234: the trigram index + the real trigram_prefilter() generator return correct results
        // for every harness's content SHAPE — dense JSON (claude tool), code+markdown (codex),
        // short text (pi), unicode (antigravity), and through provider scoping.
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        for p in [
            "claude",
            "claude-desktop",
            "codex",
            "cursor",
            "antigravity",
            "pi",
        ] {
            db.conn
                .execute(
                    "insert into sessions(id, provider, provider_session_id, preview_text, \
                       source_path, parse_version, discovery_source) \
                     values(?1, ?2, 's', '', '/x', 'v1', 'jsonl')",
                    params![format!("{p}:s"), p],
                )
                .unwrap();
        }
        // Each provider-shaped message contains 'ECONNRESET' inside a token; only the cursor one
        // also contains the correction phrase 'you forgot'.
        let rows: &[(&str, &str, &str)] = &[
            (
                "claude",
                "tool",
                r#"{"type":"tool_result","content":"net error ECONNRESET) deploy"}"#,
            ),
            (
                "claude-desktop",
                "assistant",
                "Desktop local agent saw ECONNRESET too",
            ),
            (
                "codex",
                "assistant",
                "```rust\nconnect()?; // ECONNRESET retry\n```",
            ),
            ("cursor", "user", "hey you forgot the ECONNRESET retry path"),
            (
                "antigravity",
                "assistant",
                "MODEL: ECONNRESET observed — naïve café résumé",
            ),
            ("pi", "user", "ECONNRESET again"),
        ];
        {
            let tx = db.conn.unchecked_transaction().unwrap();
            {
                let mut stmt = tx
                    .prepare(
                        "insert into messages(session_id, provider, seq, role, content) \
                         values(?1,?2,?3,?4,?5)",
                    )
                    .unwrap();
                for (i, (p, role, content)) in rows.iter().enumerate() {
                    stmt.execute(params![format!("{p}:s"), p, i as i64, role, content])
                        .unwrap();
                }
            }
            tx.commit().unwrap();
        }
        // Substring 'ECONNRESET' (inside JSON / code / plain / unicode) hits ALL providers via the
        // public regex search (custom trigram index, lazily built on first use).
        let providers_for = |query: &str, filters: MessageFilters| -> Vec<String> {
            let mut got: Vec<String> = db
                .search_messages(query, &filters)
                .unwrap()
                .into_iter()
                .map(|h| h.provider.as_str().to_string())
                .collect();
            got.sort();
            got
        };
        let all = providers_for(
            "ECONNRESET",
            MessageFilters {
                match_mode: MessageSearchMode::Regex,
                ..Default::default()
            },
        );
        assert_eq!(
            all.len(),
            6,
            "every provider's ECONNRESET found regardless of content shape"
        );
        let claude = providers_for(
            "ECONNRESET",
            MessageFilters {
                match_mode: MessageSearchMode::Regex,
                providers: Some(vec![Provider::Claude]),
                ..Default::default()
            },
        );
        assert_eq!(
            claude,
            vec!["claude"],
            "provider scope restricts to the claude message"
        );
        let claude_desktop = providers_for(
            "ECONNRESET",
            MessageFilters {
                match_mode: MessageSearchMode::Regex,
                providers: Some(vec![Provider::ClaudeDesktop]),
                ..Default::default()
            },
        );
        assert_eq!(
            claude_desktop,
            vec!["claude-desktop"],
            "provider scope restricts to the claude-desktop message"
        );
        // The correction phrase 'you forgot' appears only in the cursor message.
        let forgot = providers_for(
            r"\byou forgot\b",
            MessageFilters {
                match_mode: MessageSearchMode::Regex,
                ..Default::default()
            },
        );
        assert_eq!(
            forgot,
            vec!["cursor"],
            "you-forgot regex selects exactly cursor"
        );
    }

    /// Insert one claude session + the given (seq, role, content) rows for the wiring tests.
    #[cfg(test)]
    fn seed_messages(db: &Db, rows: &[(&str, &str)]) {
        db.conn
            .execute_batch(
                "insert into sessions(id, provider, provider_session_id, preview_text, \
                   source_path, parse_version, discovery_source) \
                 values('claude:s1','claude','s1','','/x','v1','jsonl');",
            )
            .unwrap();
        let tx = db.conn.unchecked_transaction().unwrap();
        {
            let mut stmt = tx
                .prepare(
                    "insert into messages(session_id, provider, seq, role, content) \
                     values('claude:s1','claude',?1,?2,?3)",
                )
                .unwrap();
            for (i, (role, content)) in rows.iter().enumerate() {
                stmt.execute(params![i as i64, role, content]).unwrap();
            }
        }
        tx.commit().unwrap();
    }

    #[test]
    fn purge_injected_messages_removes_only_leading_marker_user_rows() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_messages(
            &db,
            &[
                (
                    "user",
                    "<local-command-stdout>Set model to Opus</local-command-stdout>",
                ), // purge
                ("user", "<local-command-stderr>boom</local-command-stderr>"), // purge
                (
                    "user",
                    "<environment_context>\n<current_date>2026</current_date>",
                ), // purge
                (
                    "user",
                    "<turn_aborted>\nThe user interrupted the previous turn on purpose.",
                ), // purge
                ("user", "fix the failing login test before release"),         // KEEP (prompt)
                ("user", "what does <local-command-stdout> mean in the logs"), // KEEP (not leading)
                (
                    "user",
                    "what does <turn_aborted> mean in a Codex transcript",
                ), // KEEP (not leading)
                (
                    "assistant",
                    "<local-command-stdout>tool output</local-command-stdout>",
                ), // KEEP (not user)
            ],
        );
        let before = db.message_count().unwrap();
        let purged = db.purge_injected_messages().unwrap();
        assert_eq!(purged, 4, "the four leading-marker USER rows are deleted");
        assert_eq!(db.message_count().unwrap(), before - 4);
        // FTS + trigram stay in sync via the delete triggers.
        assert_eq!(
            db.messages_fts_count().unwrap(),
            db.message_count().unwrap()
        );
        let users: Vec<String> = db
            .search_messages(
                "",
                &MessageFilters {
                    role: Some(Role::User),
                    ..Default::default()
                },
            )
            .unwrap()
            .into_iter()
            .map(|h| h.content)
            .collect();
        assert!(
            users
                .iter()
                .any(|c| c.contains("fix the failing login test")),
            "real prompt kept"
        );
        assert!(
            users
                .iter()
                .any(|c| c.starts_with("what does <local-command-stdout>")),
            "a non-leading mention is kept"
        );
        assert_eq!(
            users.len(),
            3,
            "exactly the three legitimate user messages remain"
        );
    }

    #[test]
    fn regex_search_lazily_builds_custom_trigram_base_and_is_correct() {
        // The --regex path must call ensure_trigram_base() so an UNBUILT custom index (e.g. right
        // after a fresh reindex that does no trigram work) does not silently drop matches: the
        // search builds the base on first use and returns the correct row.
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        enable_v3_custom_trigram_compatibility(&db);
        seed_messages(&db, &[("user", "socket failed with ECONNRESET) today")]);
        // Precondition: the custom base index has not been built yet (lazy by construction).
        assert_eq!(
            crate::trigram_index::base_max_id(&db.conn).unwrap(),
            0,
            "precondition: custom trigram base not built before first regex use"
        );
        let filters = MessageFilters {
            match_mode: MessageSearchMode::Regex,
            ..Default::default()
        };
        let hits = db.search_messages("ECONNRESET", &filters).unwrap();
        assert_eq!(
            hits.len(),
            1,
            "regex search returns the match despite an unbuilt index"
        );
        assert!(
            crate::trigram_index::base_max_id(&db.conn).unwrap() > 0,
            "regex search lazily built the custom trigram base index"
        );
    }

    #[test]
    fn lazy_trigram_build_busy_writer_falls_back_to_delta_scan() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("index.db");
        let writer = Db::open(&path).unwrap();
        let reader = Db::open_with_busy_timeout(&path, TEST_NO_WAIT_BUSY_TIMEOUT_MS).unwrap();
        seed_messages(
            &writer,
            &[
                (
                    "user",
                    "the deploy hit ECONNRESET while the trigram base was empty",
                ),
                ("assistant", "ack"),
            ],
        );
        assert_eq!(
            crate::trigram_index::base_max_id(&reader.conn).unwrap(),
            0,
            "precondition: custom trigram base starts empty"
        );

        writer.conn.execute_batch("begin immediate").unwrap();
        let filters = MessageFilters {
            match_mode: MessageSearchMode::Regex,
            ..Default::default()
        };
        let hits = reader.search_messages("ECONNRESET", &filters).unwrap();
        writer.conn.execute_batch("rollback").unwrap();

        assert_eq!(hits.len(), 1, "busy lazy build must not drop regex hits");
        assert_eq!(
            crate::trigram_index::base_max_id(&reader.conn).unwrap(),
            0,
            "busy fallback serves the existing base and leaves rebuild for a later query"
        );
    }

    #[test]
    fn progress_reporter_fires_on_lazy_build_only_and_is_silent_when_unset() {
        use std::sync::atomic::{AtomicU32, Ordering};
        use std::sync::Arc;
        // Unset reporter: the library builds silently (no panic, no I/O), returns base_max.
        let dir = tempfile::tempdir().unwrap();
        let silent = Db::open(&dir.path().join("a.db")).unwrap();
        enable_v3_custom_trigram_compatibility(&silent);
        seed_messages(&silent, &[("user", "econnreset here")]);
        assert_eq!(silent.ensure_trigram_base().unwrap(), 1);

        // Injected reporter: fires exactly once, when (and only when) a build happens.
        let dir2 = tempfile::tempdir().unwrap();
        let mut db = Db::open(&dir2.path().join("b.db")).unwrap();
        enable_v3_custom_trigram_compatibility(&db);
        let calls = Arc::new(AtomicU32::new(0));
        let counter = Arc::clone(&calls);
        db.set_progress_reporter(move |_msg| {
            counter.fetch_add(1, Ordering::Relaxed);
        });
        seed_messages(&db, &[("user", "econnreset here")]);
        assert_eq!(db.ensure_trigram_base().unwrap(), 1);
        assert_eq!(
            calls.load(Ordering::Relaxed),
            1,
            "reporter fires once for the one-time build"
        );
        db.ensure_trigram_base().unwrap();
        assert_eq!(
            calls.load(Ordering::Relaxed),
            1,
            "no report when the base is already current"
        );
    }

    #[test]
    fn search_messages_regex_prunes_lookaround_and_falls_back() {
        // #223 correctness: the prefilter only NARROWS; the Rust regex still verifies, so a
        // trigram candidate the full regex rejects (look-around) is pruned. Non-prefilterable
        // patterns (no >=3-char literal) fall back to a scan and stay correct.
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_messages(
            &db,
            &[
                ("user", "socket failed with ECONNRESET) today"),
                ("user", "you forgot the tests"),
                ("assistant", "scatter the cats"), // contains 'cat' but NOT \bcat\b
                ("user", "a cat sat here"),        // matches \bcat\b
                ("assistant", "totally unrelated text 1234"),
            ],
        );
        let run = |pattern: &str| -> Vec<String> {
            let filters = MessageFilters {
                match_mode: MessageSearchMode::Regex,
                ..Default::default()
            };
            let mut got: Vec<String> = db
                .search_messages(pattern, &filters)
                .unwrap()
                .into_iter()
                .map(|h| h.content)
                .collect();
            got.sort();
            got
        };
        assert_eq!(
            run(r"\bcat\b"),
            vec!["a cat sat here".to_string()],
            "look-around pruned"
        );
        assert_eq!(
            run("ECONNRESET"),
            vec!["socket failed with ECONNRESET) today".to_string()],
            "substring inside a token",
        );
        assert_eq!(
            run(r"\byou forgot\b"),
            vec!["you forgot the tests".to_string()],
            "phrase"
        );
        assert_eq!(
            run(r"\d{4}"),
            vec!["totally unrelated text 1234".to_string()],
            "non-prefilterable pattern falls back to scan, still correct",
        );
        assert!(run(r"[0-9]{9}").is_empty(), "non-prefilterable, no match");
    }

    #[test]
    fn search_messages_provider_filter_scopes() {
        // #223 --provider scope: the new provider filter restricts results to one harness.
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        for p in ["claude", "codex"] {
            db.conn
                .execute(
                    "insert into sessions(id, provider, provider_session_id, preview_text, \
                       source_path, parse_version, discovery_source) \
                     values(?1, ?2, 's', '', '/x', 'v1', 'jsonl')",
                    params![format!("{p}:s"), p],
                )
                .unwrap();
            db.conn
                .execute(
                    "insert into messages(session_id, provider, seq, role, content) \
                     values(?1, ?2, 0, 'user', 'shared ECONNRESET token')",
                    params![format!("{p}:s"), p],
                )
                .unwrap();
        }
        let scoped = |provider: Option<Provider>| -> usize {
            let filters = MessageFilters {
                match_mode: MessageSearchMode::Regex,
                providers: provider.map(|provider| vec![provider]),
                ..Default::default()
            };
            db.search_messages("ECONNRESET", &filters).unwrap().len()
        };
        assert_eq!(scoped(None), 2, "unscoped: both providers");
        assert_eq!(scoped(Some(Provider::Claude)), 1, "scoped to claude");
        assert_eq!(scoped(Some(Provider::Codex)), 1, "scoped to codex");
    }

    // S14: a subagent transcript's `role='user'` rows are the SPAWNING AGENT's delegation prompt,
    // not anything a person typed. Subagents outnumber user-started sessions ~5:1, and the
    // built-in patterns match ordinary orchestrator text directly, so counting them turns routine
    // delegation into "the user corrected me". Narrowing by role alone is not enough.
    #[test]
    fn find_corrections_requires_human_authorship_after_session_kind_selection() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions(id, provider, provider_session_id, preview_text, \
                   source_path, parse_version, discovery_source) \
                 values('claude:human','claude','human','','/x','v1','jsonl'); \
                 insert into sessions(id, provider, provider_session_id, preview_text, \
                   source_path, parse_version, discovery_source, parent_session_id) \
                 values('claude:spawned','claude','spawned','','/x','v1','jsonl','claude:human');",
            )
            .unwrap();
        db.conn
            .execute_batch(
                "insert into messages(
                     session_id, provider, seq, role, content, authorship, record_relation
                 ) values
                   ('claude:human','claude',0,'user','don''t forget to check the tests',
                    'human','original'),
                   ('claude:spawned','claude',0,'user','don''t forget to check the tests',
                    'agent','original'),
                   ('claude:spawned','claude',1,'user','you forgot the human follow-up',
                    'human','original');",
            )
            .unwrap();

        let policies = default_policies();
        let matches_of = |filters: &MessageFilters| -> Vec<(String, i64)> {
            let mut matches: Vec<(String, i64)> = db
                .find_corrections(&policies, filters)
                .unwrap()
                .into_iter()
                .map(|hit| (hit.session_id, hit.message_seq))
                .collect();
            matches.sort();
            matches
        };

        assert_eq!(
            matches_of(&MessageFilters::default()),
            [("claude:human".to_string(), 0)],
            "by default a correction is what a person said, so the delegation prompt is excluded"
        );
        assert_eq!(
            matches_of(&MessageFilters {
                session_kinds: Some(vec![crate::models::SessionKind::Subagent]),
                ..Default::default()
            }),
            [("claude:spawned".to_string(), 1)],
            "session scope reopens genuine human content without reclassifying an agent prompt"
        );
        assert_eq!(
            matches_of(&MessageFilters {
                session_kinds: Some(vec![
                    crate::models::SessionKind::User,
                    crate::models::SessionKind::Subagent,
                ]),
                ..Default::default()
            }),
            [
                ("claude:human".to_string(), 0),
                ("claude:spawned".to_string(), 1),
            ],
            "the union contains attributable human content from both session classes"
        );
        assert!(
            matches_of(&MessageFilters {
                session_kinds: Some(Vec::new()),
                ..Default::default()
            })
            .is_empty(),
            "an empty class set matches nothing rather than silently matching all"
        );
    }

    // S10: `offset` was accepted and silently dropped -- a parameter that validated, echoed, and
    // never reached the behavior, which is the failure mode that returns success.
    #[test]
    fn find_corrections_honors_offset_before_limit_in_newest_first_order() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions(id, provider, provider_session_id, preview_text, \
                   source_path, parse_version, discovery_source) \
                 values('claude:s1','claude','s1','','/x','v1','jsonl');",
            )
            .unwrap();
        for seq in 0..5i64 {
            db.conn
                .execute(
                    "insert into messages(
                         session_id, provider, seq, role, ts, content,
                         authorship, record_relation
                     ) values(
                         'claude:s1','claude',?1,'user',?2,?3,'human','original'
                     )",
                    params![
                        seq,
                        format!("2026-01-0{}T00:00:00Z", seq + 1),
                        format!("you forgot item {seq}")
                    ],
                )
                .unwrap();
        }

        let policies = default_policies();
        let contents = |offset: usize, limit: usize| -> Vec<String> {
            db.find_corrections(
                &policies,
                &MessageFilters {
                    offset,
                    limit,
                    ..Default::default()
                },
            )
            .unwrap()
            .into_iter()
            .map(|hit| hit.content)
            .collect()
        };

        // Newest first, so item 4 leads.
        assert_eq!(contents(0, 2), ["you forgot item 4", "you forgot item 3"]);
        assert_eq!(
            contents(2, 2),
            ["you forgot item 2", "you forgot item 1"],
            "offset skips the newest N, then limit takes: one page, not a different sort"
        );
        assert_eq!(
            contents(3, 0),
            ["you forgot item 1", "you forgot item 0"],
            "offset applies even when limit is 0 (unbounded)"
        );
        assert!(
            contents(99, 0).is_empty(),
            "an offset past the end is empty, not a panic or a wrap-around"
        );
    }

    #[test]
    fn find_corrections_pages_timestamp_ties_and_nulls_in_one_stable_total_order() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        for session_id in ["claude:a", "claude:b"] {
            db.conn
                .execute(
                    "insert into sessions(id, provider, provider_session_id, preview_text, \
                       source_path, parse_version, discovery_source) \
                     values(?1,'claude',?1,'','/x','v1','jsonl')",
                    [session_id],
                )
                .unwrap();
        }
        for (session_id, seq, timestamp, content) in [
            (
                "claude:b",
                0_i64,
                Some("2026-01-01T00:00:00Z"),
                "you forgot b0",
            ),
            ("claude:a", 1, Some("2026-01-01T00:00:00Z"), "you forgot a1"),
            ("claude:a", 0, Some("2026-01-01T00:00:00Z"), "you forgot a0"),
            ("claude:b", 1, None, "you forgot b1-null"),
            ("claude:a", 2, None, "you forgot a2-null"),
        ] {
            db.conn
                .execute(
                    "insert into messages(
                         session_id, provider, seq, role, ts, content,
                         authorship, record_relation
                     ) values(?1,'claude',?2,'user',?3,?4,'human','original')",
                    params![session_id, seq, timestamp, content],
                )
                .unwrap();
        }

        let policies = default_policies();
        let page = |offset: usize, limit: usize| {
            db.find_corrections(
                &policies,
                &MessageFilters {
                    offset,
                    limit,
                    ..Default::default()
                },
            )
            .unwrap()
            .into_iter()
            .map(|hit| hit.content)
            .collect::<Vec<_>>()
        };
        let first = page(0, 2);
        let second = page(2, 2);
        let third = page(4, 2);
        let combined = first
            .iter()
            .chain(&second)
            .chain(&third)
            .cloned()
            .collect::<Vec<_>>();

        assert_eq!(
            combined,
            [
                "you forgot a0",
                "you forgot a1",
                "you forgot b0",
                "you forgot a2-null",
                "you forgot b1-null",
            ],
            "equal and missing timestamps use session id then sequence as stable tie-breakers"
        );
        assert_eq!(combined, page(0, 0), "pages must partition the full result");
    }

    #[test]
    fn find_corrections_scans_user_rows_and_classifies() {
        // #224 (revised): corrections scans only `role='user'` rows directly — no trigram prefilter
        // (see `find_corrections` doc: the role filter is the selective one, the prefilter would
        // only add cost). Verify it classifies each user row against the ordered patterns and
        // ignores non-user roles even when their content matches a pattern.
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions(id, provider, provider_session_id, preview_text, \
                   source_path, parse_version, discovery_source) \
                 values('claude:s1','claude','s1','','/x','v1','jsonl');",
            )
            .unwrap();
        let rows = [
            ("user", "you forgot the unit tests again"), // skip_step
            ("user", "we also need integration coverage"), // incomplete
            ("user", "looks great, ship it"),            // no correction
            ("assistant", "you forgot nothing, here is the fix"), // role=assistant → ignored
            ("user", "the deploy hit econnreset once more"), // no correction
        ];
        {
            let tx = db.conn.unchecked_transaction().unwrap();
            {
                let mut stmt = tx
                    .prepare(
                        "insert into messages(
                             session_id, provider, seq, role, content, authorship, record_relation
                         ) values('claude:s1','claude',?1,?2,?3,'human','original')",
                    )
                    .unwrap();
                for (i, (role, content)) in rows.iter().enumerate() {
                    stmt.execute(params![i as i64, role, content]).unwrap();
                }
            }
            tx.commit().unwrap();
        }
        let policies = test_policies(&[
            ("skip_step", &[r"\byou forgot\b"]),
            ("incomplete", &[r"\balso need\b"]),
        ]);
        let scan = db
            .find_corrections(&policies, &MessageFilters::default())
            .unwrap();
        assert_eq!(
            scan.len(),
            2,
            "exactly the two user corrections, assistant ignored"
        );
        assert!(scan.iter().any(|c| c.category == "skip_step"));
        assert!(scan.iter().any(|c| c.category == "incomplete"));
        // The assistant row matches the skip_step regex but is role=assistant → must be excluded.
        assert!(
            !scan
                .iter()
                .any(|c| c.content.contains("you forgot nothing")),
            "assistant-role match excluded by the role='user' filter",
        );
    }

    #[test]
    fn find_corrections_classifies_only_original_human_content_with_absolute_coordinates() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions (
                     id, provider, provider_session_id, preview_text,
                     source_path, parse_version, discovery_source
                 ) values (
                     'claude:provenance', 'claude', 'provenance', '',
                     '/provenance', 'claude-v4', 'test'
                 );
                 insert into messages (
                     id, session_id, provider, seq, role, kind, content,
                     authorship, record_relation
                 ) values
                   (201, 'claude:provenance', 'claude', 0, 'user', 'conversation',
                    'human original you forgot', 'human', 'original'),
                   (202, 'claude:provenance', 'claude', 1, 'user', 'conversation',
                    'agent original you forgot', 'agent', 'original'),
                   (203, 'claude:provenance', 'claude', 2, 'user', 'conversation',
                    'human mirror you forgot', 'human', 'mirror');",
            )
            .unwrap();

        let generated_prefix = "agent you forgot | ";
        let human_request = "human α you forgot the tests";
        let mixed_content = format!("{generated_prefix}{human_request}");
        db.conn
            .execute(
                "insert into messages (
                     id, session_id, provider, seq, role, kind, content,
                     authorship, record_relation
                 ) values (
                     204, 'claude:provenance', 'claude', 3, 'user', 'conversation', ?1,
                     'mixed', 'original'
                 )",
                [&mixed_content],
            )
            .unwrap();
        let generated_end = generated_prefix.chars().count() as i64;
        let mixed_end = mixed_content.chars().count() as i64;
        db.conn
            .execute(
                "insert into message_content_parts (
                     message_id, ordinal, start_char, end_char, authorship, origin
                 ) values
                   (204, 0, 0, ?1, 'generated', 'generated_summary'),
                   (204, 1, ?1, ?2, 'human', 'direct_input')",
                params![generated_end, mixed_end],
            )
            .unwrap();

        let left = "left";
        let generated_bridge = " generated bridge ";
        let right = "right";
        let split_content = format!("{left}{generated_bridge}{right}");
        db.conn
            .execute(
                "insert into messages (
                     id, session_id, provider, seq, role, kind, content,
                     authorship, record_relation
                 ) values (
                     205, 'claude:provenance', 'claude', 4, 'user', 'conversation', ?1,
                     'mixed', 'original'
                 )",
                [&split_content],
            )
            .unwrap();
        let left_end = left.chars().count() as i64;
        let bridge_end = (left.chars().count() + generated_bridge.chars().count()) as i64;
        let split_end = split_content.chars().count() as i64;
        db.conn
            .execute(
                "insert into message_content_parts (
                     message_id, ordinal, start_char, end_char, authorship, origin
                 ) values
                   (205, 0, 0, ?1, 'human', 'direct_input'),
                   (205, 1, ?1, ?2, 'generated', 'generated_summary'),
                   (205, 2, ?2, ?3, 'human', 'direct_input')",
                params![left_end, bridge_end, split_end],
            )
            .unwrap();

        let policies = test_policies(&[
            ("skip_step", &[r"\byou forgot\b"]),
            ("cross_part", &[r"\bleft\s*right\b"]),
        ]);
        let hits = db
            .find_corrections(&policies, &MessageFilters::default())
            .unwrap();

        assert_eq!(
            hits.iter().map(|hit| hit.message_seq).collect::<Vec<_>>(),
            [0, 3],
            "agent-authored originals, mirrors, and artificial cross-part matches are excluded"
        );
        let mixed_hit = &hits[1];
        assert_eq!(mixed_hit.content, mixed_content);
        assert_eq!(mixed_hit.matched_text, "you forgot");
        let expected_start = generated_prefix.chars().count() + "human α ".chars().count();
        assert_eq!(mixed_hit.match_start_char, expected_start);
        assert_eq!(
            mixed_hit.match_end_char_exclusive,
            expected_start + "you forgot".chars().count(),
            "mixed-message coordinates remain absolute in the original full content"
        );
    }

    #[test]
    fn find_corrections_reads_candidates_and_parts_from_one_snapshot() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("index.db");
        let db = Db::open(&path).unwrap();
        let writer = Db::open(&path).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions (
                     id, provider, provider_session_id, preview_text,
                     source_path, parse_version, discovery_source
                 ) values (
                     'claude:snapshot', 'claude', 'snapshot', '',
                     '/snapshot', 'claude-v4', 'test'
                 );
                 insert into messages (
                     id, session_id, provider, seq, role, kind, content,
                     authorship, record_relation
                 ) values (
                     301, 'claude:snapshot', 'claude', 0, 'user', 'conversation',
                     'human you forgot', 'mixed', 'original'
                 );
                 insert into message_content_parts (
                     message_id, ordinal, start_char, end_char, authorship, origin
                 ) values (
                     301, 0, 0, 16, 'human', 'direct_input'
                 );",
            )
            .unwrap();

        let policies = test_policies(&[("skip_step", &[r"\byou forgot\b"])]);
        let hits = db
            .find_corrections_with_after_candidates(&policies, &MessageFilters::default(), || {
                writer
                    .conn
                    .execute_batch(
                        "begin immediate;
                             update messages
                             set content = 'generated you forgot | human okay'
                             where id = 301;
                             delete from message_content_parts where message_id = 301;
                             insert into message_content_parts (
                                 message_id, ordinal, start_char, end_char, authorship, origin
                             ) values
                               (301, 0, 0, 23, 'generated', 'generated_summary'),
                               (301, 1, 23, 33, 'human', 'direct_input');
                             commit;",
                    )
                    .unwrap();
            })
            .unwrap();

        assert_eq!(hits.len(), 1);
        assert_eq!(hits[0].content, "human you forgot");
        assert_eq!(hits[0].matched_text, "you forgot");
        assert_eq!(
            writer
                .conn
                .query_row("select content from messages where id = 301", [], |row| {
                    row.get::<_, String>(0)
                })
                .unwrap(),
            "generated you forgot | human okay",
            "the writer committed while the reader retained the older snapshot"
        );
    }

    #[test]
    fn find_corrections_honors_provider_scope() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        for provider in [Provider::Claude, Provider::Codex] {
            let session_id = format!("{}:s1", provider.as_str());
            db.conn
                .execute(
                    "insert into sessions(id, provider, provider_session_id, preview_text, \
                       source_path, parse_version, discovery_source) \
                     values(?1, ?2, 's1', '', '/x', 'v1', 'jsonl')",
                    params![session_id, provider.as_str()],
                )
                .unwrap();
            db.conn
                .execute(
                    "insert into messages(
                         session_id, provider, seq, role, content, authorship, record_relation
                     ) values(
                         ?1, ?2, 0, 'user', 'you forgot the provider filter', 'human', 'original'
                     )",
                    params![session_id, provider.as_str()],
                )
                .unwrap();
        }
        let policies = test_policies(&[("skip_step", &[r"\byou forgot\b"])]);

        let hits = db
            .find_corrections(
                &policies,
                &MessageFilters {
                    providers: Some(vec![Provider::Claude]),
                    ..Default::default()
                },
            )
            .unwrap();

        assert_eq!(hits.len(), 1);
        assert_eq!(hits[0].provider, Provider::Claude);
        assert_eq!(hits[0].session_id, "claude:s1");
    }

    #[test]
    fn find_corrections_parallel_matches_sequential() {
        // The parallel (rayon) classification must produce EXACTLY the sequential result: same
        // matches, in the same `order by ts desc`, with the same limit semantics. We seed 600 user
        // rows across many threads' worth of work; row i matches iff i % 5 == 0, and its content
        // embeds i so we can assert the precise descending order. (Order-preservation under
        // rayon's `collect` is the property most at risk from parallelism — this pins it.)
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .execute_batch(
                "insert into sessions(id, provider, provider_session_id, preview_text, \
                   source_path, parse_version, discovery_source) \
                 values('claude:s1','claude','s1','','/x','v1','jsonl');",
            )
            .unwrap();
        let base = chrono::DateTime::parse_from_rfc3339("2026-01-01T00:00:00Z").unwrap();
        let n = 600i64;
        {
            let tx = db.conn.unchecked_transaction().unwrap();
            {
                let mut stmt = tx
                    .prepare(
                        "insert into messages(
                             session_id, provider, seq, role, ts, content,
                             authorship, record_relation
                         ) values(
                             'claude:s1','claude',?1,'user',?2,?3,'human','original'
                         )",
                    )
                    .unwrap();
                for i in 0..n {
                    let ts = (base + chrono::Duration::seconds(i)).to_rfc3339();
                    let content = if i % 5 == 0 {
                        format!("row-{i} you forgot the tests")
                    } else {
                        format!("row-{i} all good here")
                    };
                    stmt.execute(params![i, ts, content]).unwrap();
                }
            }
            tx.commit().unwrap();
        }
        let policies = test_policies(&[("skip_step", &[r"\byou forgot\b"])]);

        // Expected: every 5th row, in DESCENDING i order (ts desc), starting at the largest
        // multiple of 5 below n.
        let expected: Vec<i64> = (0..n).rev().filter(|i| i % 5 == 0).collect();

        let all = db
            .find_corrections(&policies, &MessageFilters::default())
            .unwrap();
        assert_eq!(all.len(), expected.len(), "match count");
        for (hit, want_i) in all.iter().zip(&expected) {
            assert_eq!(hit.category, "skip_step");
            assert_eq!(hit.matched_text, "you forgot");
            assert!(
                hit.content.starts_with(&format!("row-{want_i} ")),
                "order mismatch: got {:?}, expected row-{want_i}",
                hit.content
            );
        }

        // Limit keeps the first N in the same ts-desc order (identical to a sequential early-break).
        let limited = db
            .find_corrections(
                &policies,
                &MessageFilters {
                    limit: 10,
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(limited.len(), 10);
        for (hit, want_i) in limited.iter().zip(expected.iter().take(10)) {
            assert!(hit.content.starts_with(&format!("row-{want_i} ")));
        }
    }

    #[test]
    fn regex_search_corpus_gate_is_result_equivalent() {
        // #272: the trigram-prefilter corpus-size gate must change SPEED, never RESULTS. With a
        // role filter present the corpus is below the threshold, so the gate SKIPS the prefilter
        // (direct regex scan); with no structural filter it USES the prefilter (trigram path).
        // Both must agree: the role-filtered result equals the no-filter result restricted to
        // that role. (The fixture is tiny, so `narrows_corpus()` is what selects the branch.)
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_messages(
            &db,
            &[
                ("user", "the deploy hit ECONNRESET in prod"),
                ("assistant", "ECONNRESET means the socket closed"),
                ("tool", "stderr: ECONNRESET at line 42"),
                ("user", "an unrelated note about apples"),
            ],
        );
        let search = |role: Option<Role>| -> Vec<(Role, String)> {
            let filters = MessageFilters {
                match_mode: MessageSearchMode::Regex,
                role,
                ..Default::default()
            };
            db.search_messages("ECONNRESET", &filters)
                .unwrap()
                .into_iter()
                .map(|hit| (hit.role, hit.content))
                .collect()
        };
        // No structural filter → narrows_corpus()==false → prefilter (trigram) path.
        let all = search(None);
        assert_eq!(
            all.len(),
            3,
            "ECONNRESET in the user + assistant + tool rows"
        );
        // role filter → narrows_corpus()==true, corpus < threshold → prefilter SKIPPED (scan path).
        let user_only = search(Some(Role::User));
        let expected_user: Vec<(Role, String)> = all
            .iter()
            .filter(|(role, _)| *role == Role::User)
            .cloned()
            .collect();
        assert_eq!(
            user_only, expected_user,
            "gate's scan path agrees with the prefilter path restricted to role=user"
        );
        assert_eq!(user_only.len(), 1, "exactly the one user ECONNRESET row");
    }

    #[test]
    fn explain_message_search_counts_candidates_within_corpus() {
        let dir = tempfile::tempdir().unwrap();
        let mut db = Db::open(&dir.path().join("index.db")).unwrap();
        db.prefilter_min_corpus = 1;
        // Four user messages; only the first carries the rare literal "zebracode".
        db.upsert_session(
            &parsed_with_messages(
                "claude:s1",
                &[
                    "zebracode appears here once",
                    "common text alpha",
                    "common text bravo",
                    "common text charlie",
                ],
            ),
            1,
            100,
        )
        .unwrap();

        // Selective regex anchored on the rare literal: a trigram prefilter exists and
        // narrows the 4-row corpus to the single zebracode row before regex verification.
        let selective = MessageFilters {
            role: Some(Role::User),
            match_mode: MessageSearchMode::Regex,
            ..Default::default()
        };
        let ex = db
            .explain_message_search("(?i)zebra.ode", &selective)
            .unwrap();
        assert_eq!(
            ex.corpus, 4,
            "all four user messages form the selectivity denominator"
        );
        assert!(
            ex.prefilter.is_some(),
            "a >=3-char literal yields a trigram prefilter"
        );
        let candidates = ex
            .candidates
            .expect("the regex path reports a candidate count");
        assert!(
            candidates <= ex.corpus,
            "candidates are always a subset of the corpus"
        );
        assert_eq!(
            candidates, 1,
            "only the zebracode row survives the trigram prefilter"
        );

        // A regex with no >=3-char literal run ("a.b") has no usable anchor: no prefilter,
        // hence no candidate count — the regex would scan the whole corpus.
        let no_anchor = MessageFilters {
            role: Some(Role::User),
            match_mode: MessageSearchMode::Regex,
            ..Default::default()
        };
        let ex2 = db.explain_message_search("a.b", &no_anchor).unwrap();
        assert!(ex2.prefilter.is_none(), "no >=3-char anchor → no prefilter");
        assert!(
            ex2.candidates.is_none(),
            "no prefilter → no candidate count"
        );
        assert_eq!(ex2.corpus, 4);
    }

    #[test]
    fn schema_v4_search_explain_uses_sqlite_prefilter_without_legacy_threshold() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.upsert_session(
            &parsed_with_messages("claude:s1", &["zebracode appears here once"]),
            1,
            100,
        )
        .unwrap();

        let filters = MessageFilters {
            role: Some(Role::User),
            match_mode: MessageSearchMode::Regex,
            ..Default::default()
        };
        let (hits, explain) = db
            .search_messages_with_explain("zebracode", &filters, true)
            .unwrap();
        let explain = explain.expect("explain requested");

        assert_eq!(hits.len(), 1);
        assert!(explain.prefilter.is_some(), "anchor is available");
        assert_eq!(explain.candidates, Some(1));
        assert!(explain.prefilter_skipped.is_none());
    }

    #[test]
    fn internal_message_order_is_typed_scoped_and_reversible() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.upsert_session(
            &parsed_with_messages("claude:ordered", &["zero", "one", "two", "three", "four"]),
            1,
            1,
        )
        .unwrap();

        let newest = db
            .search_messages_ordered(
                "",
                &MessageFilters {
                    session_id: Some("claude:ordered".to_string()),
                    limit: 2,
                    ..Default::default()
                },
                MessageOrder::NewestFirst,
            )
            .unwrap();
        assert_eq!(
            newest.iter().map(|hit| hit.seq).collect::<Vec<_>>(),
            vec![4, 3]
        );

        let oldest = db
            .search_messages(
                "",
                &MessageFilters {
                    session_id: Some("claude:ordered".to_string()),
                    limit: 2,
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(
            oldest.iter().map(|hit| hit.seq).collect::<Vec<_>>(),
            vec![0, 1]
        );

        let error = db
            .search_messages_ordered("", &MessageFilters::default(), MessageOrder::NewestFirst)
            .unwrap_err();
        assert!(error
            .to_string()
            .contains("newest-first message order requires session_id"));
    }

    /// Build a claude `ParsedSession` whose messages are the given contents (seq = index).
    #[cfg(test)]
    fn parsed_with_messages(id: &str, contents: &[&str]) -> crate::models::ParsedSession {
        use crate::models::{Message, ParsedSession, SessionRecord};
        let messages = contents
            .iter()
            .enumerate()
            .map(|(i, c)| Message {
                seq: i as i64,
                role: Role::User,
                ts: None,
                tool_name: None,
                kind: crate::models::MessageKind::Conversation,
                tool_call_id: None,
                is_compaction: false,
                content: c.to_string(),
                provenance: crate::models::MessageProvenance::default(),
            })
            .collect();
        ParsedSession {
            session: SessionRecord {
                id: id.to_string(),
                provider: Provider::Claude,
                provider_session_id: "s".into(),
                title: None,
                summary: None,
                cwd: None,
                repo_root: None,
                created_at: None,
                updated_at: None,
                last_message_at: None,
                preview_text: String::new(),
                source_path: "/x".into(),
                message_count: Some(contents.len() as i64),
                parse_version: "v1".into(),
                raw_metadata_json: None,
                parse_warning: None,
                discovery_source: "jsonl".into(),
                // No spawn concept on this path: subagent runs are either excluded from
                // discovery or unmarked by this provider. See models.rs SessionRecord.
                parent_session_id: None,
                agent_label: None,
            },
            transcript_text: contents.join("\n\n"),
            messages,
            file_edits: Vec::new(),
        }
    }

    #[test]
    fn upsert_appends_only_new_messages_when_session_grows() {
        // Root-cause reindex perf: an append-only session that GREW must NOT delete + re-insert
        // (and re-trigram-index) its unchanged prefix — that re-indexed entire multi-hundred-MB
        // sessions on every incremental reindex. Detected with a SENTINEL tag on the existing
        // rows: it survives an append but not a delete+re-insert. (Row ids can't tell them apart
        // — SQLite reuses freed rowids after a delete-all.)
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let contents = |db: &Db| -> Vec<String> {
            let mut s = db
                .conn
                .prepare("select content from messages where session_id='claude:s1' order by seq")
                .unwrap();
            s.query_map([], |r| r.get(0))
                .unwrap()
                .filter_map(Result::ok)
                .collect()
        };
        let tagged = |db: &Db| -> i64 {
            db.conn
                .query_row(
                    "select count(*) from messages where session_id='claude:s1' \
                     and tool_name='SENTINEL'",
                    [],
                    |r| r.get(0),
                )
                .unwrap()
        };
        db.upsert_session(
            &parsed_with_messages("claude:s1", &["alpha", "bravo", "charlie"]),
            1,
            100,
        )
        .unwrap();
        // Tag the existing rows; a fresh re-insert (from the parse) would not carry the sentinel.
        db.conn
            .execute(
                "update messages set tool_name='SENTINEL' where session_id='claude:s1'",
                [],
            )
            .unwrap();

        // Append-only growth: same prefix + 2 new messages.
        db.upsert_session(
            &parsed_with_messages("claude:s1", &["alpha", "bravo", "charlie", "delta", "echo"]),
            2,
            200,
        )
        .unwrap();
        assert_eq!(
            contents(&db),
            ["alpha", "bravo", "charlie", "delta", "echo"]
        );
        assert_eq!(
            tagged(&db),
            3,
            "prefix rows RETAINED the sentinel (appended, not re-indexed)"
        );
        // The appended message is findable by regex search (custom index built lazily over the
        // grown corpus, or covered by the un-indexed delta direct-scan).
        let new_found = db
            .search_messages(
                "delta",
                &MessageFilters {
                    match_mode: MessageSearchMode::Regex,
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(new_found.len(), 1, "the appended message is searchable");

        // Shrink → full replace (safe fallback): sentinel gone, content correct.
        db.upsert_session(
            &parsed_with_messages("claude:s1", &["alpha", "bravo"]),
            3,
            60,
        )
        .unwrap();
        assert_eq!(
            contents(&db),
            ["alpha", "bravo"],
            "shrink re-replaces fully"
        );
        assert_eq!(tagged(&db), 0, "shrink did a full replace");

        // Grow with a CHANGED boundary message (in-place rewrite) → full replace, correct content.
        db.upsert_session(
            &parsed_with_messages("claude:s1", &["alpha", "boundary"]),
            4,
            70,
        )
        .unwrap();
        db.conn
            .execute(
                "update messages set tool_name='SENTINEL' where session_id='claude:s1'",
                [],
            )
            .unwrap();
        db.upsert_session(
            &parsed_with_messages("claude:s1", &["alpha", "CHANGED", "extra"]),
            5,
            90,
        )
        .unwrap();
        assert_eq!(
            contents(&db),
            ["alpha", "CHANGED", "extra"],
            "boundary content changed → full replace keeps content correct",
        );
        assert_eq!(tagged(&db), 0, "boundary mismatch forced a full replace");
    }

    #[test]
    fn replace_session_rewrites_matching_prefix_metadata_on_full_reindex() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();

        db.replace_session(
            &parsed_with_messages("claude:s1", &["alpha", "bravo"]),
            1,
            100,
        )
        .unwrap();
        db.conn
            .execute(
                "update messages set role='tool', tool_name='STALE' where session_id='claude:s1' and seq=0",
                [],
            )
            .unwrap();

        db.replace_session(
            &parsed_with_messages("claude:s1", &["alpha", "bravo", "charlie"]),
            2,
            150,
        )
        .unwrap();
        let row: (String, Option<String>) = db
            .conn
            .query_row(
                "select role, tool_name from messages where session_id='claude:s1' and seq=0",
                [],
                |r| Ok((r.get(0)?, r.get(1)?)),
            )
            .unwrap();
        assert_eq!(
            row,
            ("user".to_string(), None),
            "full replace must repair stale prefix metadata even when content is unchanged"
        );
    }

    #[test]
    fn tail_flow_appends_without_reparsing_prefix() {
        // Drive the incremental tail path directly (parse_reader → tail_parse → append_tail) and
        // PROVE it appends only the new rows: a deliberately corrupted prefix row — which a full
        // reparse would overwrite via the boundary-mismatch replace — must survive untouched.
        use crate::providers::claude::ClaudeAdapter;
        use std::io::Write;

        let dir = tempfile::tempdir().unwrap();
        let file = dir.path().join("probe.jsonl");
        let line = |ts: &str, role: &str, text: &str| {
            format!(
                "{{\"type\":\"{role}\",\"sessionId\":\"probe\",\"timestamp\":\"{ts}\",\
                 \"message\":{{\"role\":\"{role}\",\"content\":[{{\"type\":\"text\",\"text\":\"{text}\"}}]}}}}\n"
            )
        };
        let initial = format!(
            "{}{}",
            line("2026-06-01T10:00:00Z", "user", "first prompt"),
            line("2026-06-01T10:00:05Z", "assistant", "first reply"),
        );
        std::fs::write(&file, &initial).unwrap();

        let claude = ClaudeAdapter::new(vec![dir.path().to_path_buf()]);
        let source = crate::models::SourceFile {
            provider: Provider::Claude,
            path: file.clone(),
            mtime_ns: 1,
            size_bytes: std::fs::metadata(&file).unwrap().len() as i64,
        };
        let source_path = crate::util::normalize_path(&file);
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let mut parsed = claude.parse(&source);
        crate::util::backfill_session_dates(&mut parsed.session, source.mtime_ns);
        db.upsert_session(&parsed, source.mtime_ns, source.size_bytes)
            .unwrap();
        db.set_file_checkpoint(
            Provider::Claude,
            &source_path,
            crate::tail::complete_prefix_offset(&file).unwrap(),
            &crate::tail::prefix_fingerprint(&file).unwrap(),
        )
        .unwrap();
        assert_eq!(db.message_count().unwrap(), 2);

        db.conn
            .execute(
                "update messages set content='CORRUPTED_PROBE' \
                 where session_id='claude:probe' and seq=0",
                [],
            )
            .unwrap();

        // Append a third turn, then run the tail path against the stored checkpoint.
        std::fs::OpenOptions::new()
            .append(true)
            .open(&file)
            .unwrap()
            .write_all(line("2026-06-01T10:01:00Z", "user", "second prompt").as_bytes())
            .unwrap();
        let new_size = std::fs::metadata(&file).unwrap().len() as i64;
        let (offset, stored_fp) = db
            .file_checkpoint(
                Provider::Claude,
                &source_path,
                crate::util::provider_parse_version(Provider::Claude),
            )
            .unwrap()
            .unwrap();
        assert!(
            crate::tail::fingerprint_matches(&file, &stored_fp).unwrap(),
            "an append must keep the head fingerprint matching"
        );
        let tail = crate::tail::tail_parse(&file, offset, |cursor, path| {
            claude.parse_reader(cursor, path)
        })
        .unwrap()
        .expect("a new complete line was appended");
        db.append_tail(&tail, 2, new_size).unwrap();

        assert_eq!(
            db.message_count().unwrap(),
            3,
            "the appended turn is indexed"
        );
        let seq2: String = db
            .conn
            .query_row(
                "select content from messages where session_id='claude:probe' and seq=2",
                [],
                |row| row.get(0),
            )
            .unwrap();
        assert_eq!(
            seq2, "second prompt",
            "new message appended at the next seq"
        );
        let seq0: String = db
            .conn
            .query_row(
                "select content from messages where session_id='claude:probe' and seq=0",
                [],
                |row| row.get(0),
            )
            .unwrap();
        assert_eq!(
            seq0, "CORRUPTED_PROBE",
            "tail append must NOT reparse/replace the prefix rows"
        );
        assert_eq!(
            db.messages_fts_count().unwrap(),
            db.message_count().unwrap(),
            "FTS in sync"
        );
    }

    #[test]
    fn vocabulary_reports_term_frequencies() {
        // #226: fts5vocab term frequency — a term repeated across messages has the right doc and
        // total counts and sorts ahead of rarer terms; the trigram source yields 3-gram terms.
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_messages(
            &db,
            &[
                ("user", "alpha alpha bravo"), // alpha x2, bravo x1
                ("user", "alpha charlie"),     // alpha x1, charlie x1
            ],
        );
        let vocab = db.vocabulary(false, 0, None).unwrap();
        let alpha = vocab
            .iter()
            .find(|(t, _, _)| t == "alpha")
            .expect("alpha present");
        assert_eq!(alpha.1, 2, "alpha appears in 2 documents");
        assert_eq!(alpha.2, 3, "alpha occurs 3 times total");
        // Ordered by total count desc → alpha (3) is first.
        assert_eq!(vocab[0].0, "alpha", "most frequent term first");
        // Trigram vocab yields 3-grams (substring stats), e.g. "alp" from "alpha".
        let schema_before = schema_fingerprint(&db.conn);
        let row_vocab_exists: bool = db
            .conn
            .query_row(
                "select exists(
                     select 1 from sqlite_schema
                      where type = 'table' and name = 'messages_trigram_terms'
                 )",
                [],
                |row| row.get(0),
            )
            .unwrap();
        assert!(
            row_vocab_exists,
            "v4 must provide the row-level trigram vocabulary used for bounded output"
        );
        let tri = db.vocabulary(true, 0, None).unwrap();
        assert!(
            tri.iter().any(|(t, _, _)| t == "alp"),
            "trigram vocab has 3-gram terms"
        );
        assert_eq!(
            schema_fingerprint(&db.conn),
            schema_before,
            "reading v4 trigram vocabulary must not mutate any schema object"
        );
    }

    /// A vocabulary prefix reaches the term the index stored, whichever sigma the caller typed.
    ///
    /// FTS5 folds all three of `Σ`, `σ`, and `ς` onto `σ` as it tokenizes, which is the rule
    /// [`crate::util::fold_caseless`] applies and the rule [`str::to_lowercase`] does not:
    /// lowercasing writes a word-final `Σ` as `ς`, a spelling no term in either source is stored
    /// under. Folding the prefix by that rule asked for a term that cannot exist, so every
    /// spelling of a sigma-final prefix reported nothing at all while the term sat in the index.
    #[test]
    fn a_vocabulary_prefix_ending_in_sigma_finds_the_term_the_index_folded_it_to() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_messages(&db, &[("user", "ΟΔΟΣ ΟΔΟΣΣΑ")]);

        // One term, because tokenizing folded the two sigma spellings together.
        let stored: Vec<String> = db
            .vocabulary(false, 0, Some("οδοσ"))
            .unwrap()
            .into_iter()
            .map(|(term, _, _)| term)
            .collect();
        assert_eq!(
            stored,
            vec!["οδοσ".to_string(), "οδοσσα".to_string()],
            "the folded spelling is what the index stores"
        );

        for prefix in ["ΟΔΟΣ", "οδος", "Οδος"] {
            let terms: Vec<String> = db
                .vocabulary(false, 0, Some(prefix))
                .unwrap()
                .into_iter()
                .map(|(term, _, _)| term)
                .collect();
            assert_eq!(
                terms,
                vec!["οδοσ".to_string(), "οδοσσα".to_string()],
                "prefix {prefix:?} reaches the terms the index folded it to"
            );
        }
    }

    #[test]
    fn vocabulary_prefix_selects_only_terms_starting_with_it() {
        // Without a prefix the only way to ask about one term is to read every term and filter
        // outside SQLite: 1,591,051 rows and 22.7s against this author's index, versus 0.05s for
        // the equivalent term-range query. The prefix has to reach the query, not the output.
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_messages(
            &db,
            &[
                ("user", "alpha alpha bravo alphabet"),
                ("user", "alpha charlie alphabet"),
            ],
        );

        let terms = |prefix: Option<&str>, limit: usize| -> Vec<String> {
            db.vocabulary(false, limit, prefix)
                .unwrap()
                .into_iter()
                .map(|(term, _, _)| term)
                .collect()
        };

        let mut matched = terms(Some("alph"), 0);
        matched.sort();
        assert_eq!(
            matched,
            vec!["alpha".to_string(), "alphabet".to_string()],
            "a prefix keeps every term extending it and drops the rest"
        );
        assert_eq!(
            terms(Some("alphabet"), 0),
            vec!["alphabet".to_string()],
            "a prefix equal to a whole term still matches that term"
        );
        assert!(
            terms(Some("zulu"), 0).is_empty(),
            "an unindexed prefix reports nothing rather than falling back to every term"
        );

        // An empty prefix and an absent one both mean every term, so neither reads as a filter
        // that silently dropped rows.
        let mut every = terms(None, 0);
        let mut empty = terms(Some(""), 0);
        every.sort();
        empty.sort();
        assert_eq!(every, empty, "an empty prefix selects every term");

        // The limit counts terms that survive the prefix, so a caller cannot receive an empty page
        // out of a matching prefix just because commoner terms filled the limit first.
        assert_eq!(
            terms(Some("alph"), 1),
            vec!["alpha".to_string()],
            "limit applies after the prefix, most frequent first"
        );

        // Counts stay the term's counts over the whole index; a prefix selects rows, never rescopes
        // what each row counts.
        let alpha = db.vocabulary(false, 0, Some("alpha")).unwrap();
        let alpha = alpha
            .iter()
            .find(|(term, _, _)| term == "alpha")
            .expect("alpha present");
        assert_eq!((alpha.1, alpha.2), (2, 3), "2 documents, 3 occurrences");

        assert!(
            db.vocabulary(true, 0, Some("alp"))
                .unwrap()
                .iter()
                .all(|(term, _, _)| term.starts_with("alp")),
            "the prefix reaches the trigram source too, not only word tokens"
        );
    }

    #[test]
    fn schema_v4_rejects_custom_trigram_maintenance_without_mutation() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        let schema_before = schema_fingerprint(&db.conn);

        let error = db.ensure_trigram_base().unwrap_err().to_string();

        assert!(error.contains("unavailable on schema v4"), "{error}");
        assert_eq!(schema_fingerprint(&db.conn), schema_before);
    }

    #[test]
    fn ensure_trigram_base_self_heals_corrupt_metadata_instead_of_failing_every_search() {
        // trigram_postings/trigram_meta are entirely derived from `messages`, so corruption
        // there must self-heal (rebuild) rather than turn every subsequent regex/substring
        // search into a hard failure requiring a manual `aise reindex --full`.
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        enable_v3_custom_trigram_compatibility(&db);
        seed_messages(&db, &[("user", "socket failed with ECONNRESET today")]);

        // Corrupt trigram_meta the same way trigram_index::tests does: recreate it with an
        // incompatible shape (no `value` column) so the metadata read fails for a real reason.
        db.conn
            .execute_batch(
                "drop table trigram_meta; create table trigram_meta (key text primary key);",
            )
            .unwrap();

        let base_max = db
            .ensure_trigram_base()
            .expect("corruption must self-heal, not propagate an error");

        assert_eq!(
            base_max, 1,
            "self-heal rebuilds the base from the message table"
        );
        assert_eq!(
            crate::trigram_index::base_max_id(&db.conn).unwrap(),
            1,
            "trigram_meta is valid and queryable again after self-heal"
        );
        let groups = crate::trigram::trigram_prefilter_groups("ECONNRESET").unwrap();
        let cands = crate::trigram_index::candidates(&db.conn, &groups).unwrap();
        assert!(
            cands.contains(&1),
            "the rebuilt index actually finds the seeded message, not just an empty shell"
        );
    }

    #[test]
    fn ensure_trigram_base_does_not_repair_metadata_when_maintenance_is_disabled() {
        let dir = tempfile::tempdir().unwrap();
        let mut db = Db::open(&dir.path().join("index.db")).unwrap();
        enable_v3_custom_trigram_compatibility(&db);
        seed_messages(&db, &[("user", "socket failed with ECONNRESET today")]);
        db.conn
            .execute_batch(
                "drop table trigram_meta; create table trigram_meta (key text primary key);",
            )
            .unwrap();
        db.set_implicit_index_maintenance(false);

        let error = db.ensure_trigram_base().unwrap_err().to_string();
        assert!(
            error.contains("automatic maintenance is disabled"),
            "{error}"
        );
        assert!(
            !crate::trigram_index::schema_is_compatible(&db.conn).unwrap(),
            "a maintenance-disabled read must not replace the malformed table"
        );
    }

    #[test]
    fn read_only_open_does_not_repair_incompatible_trigram_tables() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("index.db");
        let db = Db::open(&path).unwrap();
        enable_v3_custom_trigram_compatibility(&db);
        seed_messages(&db, &[("user", "socket failed with ECONNRESET today")]);
        db.conn
            .execute_batch(
                "drop table trigram_meta; create table trigram_meta (key text primary key);",
            )
            .unwrap();
        let schema_before = schema_fingerprint(&db.conn);
        drop(db);

        let read_only = Db::open_existing_read_only_with_threads(
            &path,
            TEST_BUSY_TIMEOUT_MS,
            NonZeroUsize::MIN,
        )
        .unwrap();
        let error = read_only.ensure_trigram_base().unwrap_err().to_string();

        assert!(
            error.contains("automatic maintenance is disabled"),
            "{error}"
        );
        assert_eq!(
            schema_fingerprint(&read_only.conn),
            schema_before,
            "SQLite read-only mode must leave the incompatible derived schema unchanged"
        );
    }

    #[test]
    fn concurrent_read_only_connections_share_one_fixed_worker_runtime() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("index.db");
        drop(Db::open(&path).unwrap());
        let runtime = Arc::new(ExecutionRuntime::new(
            NonZeroUsize::new(2).expect("nonzero worker count"),
        ));

        let first = Db::open_existing_read_only_with_runtime(
            &path,
            TEST_BUSY_TIMEOUT_MS,
            Arc::clone(&runtime),
        )
        .unwrap();
        let second = Db::open_existing_read_only_with_runtime(
            &path,
            TEST_BUSY_TIMEOUT_MS,
            Arc::clone(&runtime),
        )
        .unwrap();

        assert!(Arc::ptr_eq(&first.runtime, &runtime));
        assert!(Arc::ptr_eq(&second.runtime, &runtime));
        assert_eq!(first.worker_threads(), 2);
        assert_eq!(second.worker_threads(), 2);
    }

    #[test]
    fn ensure_trigram_base_does_not_create_missing_tables_when_maintenance_is_disabled() {
        let dir = tempfile::tempdir().unwrap();
        let mut db = Db::open(&dir.path().join("index.db")).unwrap();
        enable_v3_custom_trigram_compatibility(&db);
        db.conn
            .execute_batch("drop table trigram_postings; drop table trigram_meta;")
            .unwrap();
        db.set_implicit_index_maintenance(false);

        let error = db.ensure_trigram_base().unwrap_err().to_string();
        assert!(
            error.contains("automatic maintenance is disabled"),
            "{error}"
        );
        let derived_tables: i64 = db
            .conn
            .query_row(
                "select count(*) from sqlite_master where name in ('trigram_postings', 'trigram_meta')",
                [],
                |row| row.get(0),
            )
            .unwrap();
        assert_eq!(
            derived_tables, 0,
            "a read-only probe must not create schema"
        );
    }

    #[test]
    fn ensure_trigram_base_rolls_back_schema_repair_when_rebuild_fails() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        enable_v3_custom_trigram_compatibility(&db);
        db.conn
            .execute_batch(
                "drop table trigram_meta;
                 create table trigram_meta (key text primary key);
                 drop table messages;",
            )
            .unwrap();

        let error = db.ensure_trigram_base().unwrap_err().to_string();
        assert!(error.contains("no such table: messages"), "{error}");
        assert!(
            !crate::trigram_index::schema_is_compatible(&db.conn).unwrap(),
            "the failed transaction must restore the original incompatible schema"
        );
    }

    #[test]
    fn ensure_trigram_base_busy_repair_leaves_incompatible_tables_untouched() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("index.db");
        let writer = Db::open(&path).unwrap();
        enable_v3_custom_trigram_compatibility(&writer);
        seed_messages(&writer, &[("user", "socket failed with ECONNRESET today")]);
        writer
            .conn
            .execute_batch(
                "drop table trigram_meta; create table trigram_meta (key text primary key);",
            )
            .unwrap();
        let schema_before = schema_fingerprint(&writer.conn);

        let contender = Db::open_with_busy_timeout(&path, TEST_NO_WAIT_BUSY_TIMEOUT_MS).unwrap();
        writer.conn.execute_batch("begin immediate").unwrap();
        let error = contender
            .ensure_trigram_base()
            .expect_err("a competing writer must prevent derived-table repair");
        writer.conn.execute_batch("rollback").unwrap();

        assert!(Db::is_sqlite_busy_error(&error), "{error:#}");
        assert!(
            !crate::trigram_index::schema_is_compatible(&contender.conn).unwrap(),
            "a failed repair attempt must not replace either derived table"
        );
        assert_eq!(
            schema_fingerprint(&contender.conn),
            schema_before,
            "the failed repair must preserve the entire preexisting schema"
        );
    }

    #[test]
    fn regex_prefilter_reaches_rows_by_primary_key_not_full_scan() {
        // #207: a prefilterable regex search resolves candidates through the custom trigram index
        // (staged into the `_trigram_cand` temp table) and reaches message rows by primary key —
        // never a full table scan of `messages`.
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        enable_v3_custom_trigram_compatibility(&db);
        seed_messages(&db, &[("user", "socket failed with ECONNRESET) today")]);
        // Build the base + stage candidates exactly as search_messages does, then check the plan of
        // the candidate-restricted scan.
        let base_max = db.ensure_trigram_base().unwrap();
        let groups = crate::trigram::trigram_prefilter_groups("ECONNRESET").unwrap();
        let cands = crate::trigram_index::candidates(&db.conn, &groups).unwrap();
        db.stage_candidates(base_max, &cands).unwrap();
        let plan = {
            let mut stmt = db
                .conn
                .prepare(
                    "explain query plan select m.id from messages m \
                     where m.id in (select id from _trigram_cand) order by m.session_id, m.seq",
                )
                .unwrap();
            stmt.query_map([], |r| r.get::<_, String>(3))
                .unwrap()
                .filter_map(Result::ok)
                .collect::<Vec<_>>()
                .join(" | ")
        };
        assert!(
            plan.contains("PRIMARY KEY") || plan.contains("USING INTEGER PRIMARY KEY"),
            "messages must be reached by primary key, not scanned: {plan}",
        );
        assert!(
            !plan.contains("SCAN m "),
            "no full scan of the messages table: {plan}",
        );
    }

    #[test]
    fn checkpoint_truncate_is_safe_and_preserves_data() {
        // #240: the WAL truncate-checkpoint runs without error and the index stays queryable
        // (it folds the WAL into the main DB; the substring index must still match afterward).
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_messages(&db, &[("user", "the deploy hit ECONNRESET) again")]);
        db.checkpoint_truncate().unwrap();
        // Idempotent: a second checkpoint on a quiescent DB is fine.
        db.checkpoint_truncate().unwrap();
        let hits = db
            .search_messages(
                "ECONNRESET",
                &MessageFilters {
                    match_mode: MessageSearchMode::Regex,
                    ..Default::default()
                },
            )
            .unwrap();
        assert_eq!(hits.len(), 1, "data intact and searchable after checkpoint");
    }

    #[test]
    fn schema_state_classification_is_total_and_preserves_readable_older_policy() {
        assert_eq!(
            SchemaState::from_version(SCHEMA_VERSION),
            SchemaState::Current
        );
        assert_eq!(
            SchemaState::from_version(SCHEMA_VERSION - 1),
            SchemaState::Older {
                current: SCHEMA_VERSION - 1,
                required: SCHEMA_VERSION,
            }
        );
        assert_eq!(
            SchemaState::from_version(SCHEMA_VERSION + 1),
            SchemaState::Newer {
                current: SCHEMA_VERSION + 1,
                supported: SCHEMA_VERSION,
            }
        );

        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        db.conn
            .pragma_update(None, "user_version", MIN_READABLE_SCHEMA_VERSION)
            .unwrap();
        assert!(db.needs_backfill().unwrap());
        assert!(db.schema_is_readable().unwrap());
    }

    #[test]
    fn corpus_threshold_probe_stops_at_the_decision_boundary() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_messages(
            &db,
            &[
                ("user", "one"),
                ("user", "two"),
                ("user", "three"),
                ("user", "four"),
                ("assistant", "five"),
            ],
        );
        let filters = MessageFilters {
            role: Some(Role::User),
            ..Default::default()
        };

        assert!(db.filtered_corpus_reaches(&filters, 3).unwrap());
        assert!(db.filtered_corpus_reaches(&filters, 4).unwrap());
        assert!(!db.filtered_corpus_reaches(&filters, 5).unwrap());
        assert_eq!(db.filtered_corpus_count(&filters).unwrap(), 4);
    }

    /// Seed one session with rows of every class the receipt count must handle: the classes
    /// excluded by default (harness notice, compaction), the ones returned by default, one tool
    /// row with a name, and one legacy `kind` this build does not know, which the default class
    /// predicate must still count (an inclusion list would silently drop it).
    fn seed_every_message_class(db: &Db) {
        seed_messages(db, &[("user", "one"), ("assistant", "two")]);
        db.conn
            .execute_batch(
                "update messages set kind = 'conversation', ts = '2026-08-01T00:00:00Z';
                 insert into messages(session_id, provider, seq, role, kind, ts, tool_name, content) values
                   ('claude:s1', 'claude', 10, 'user', 'harness_notice', '2026-08-02T00:00:00Z', null, 'notice'),
                   ('claude:s1', 'claude', 11, 'user', 'compaction', '2026-08-02T00:00:00Z', null, 'summary'),
                   ('claude:s1', 'claude', 12, 'assistant', 'message', '2026-08-03T00:00:00Z', null, 'legacy kind'),
                   ('claude:s1', 'claude', 13, 'assistant', 'tool_call', '2026-08-03T00:00:00Z', 'Bash', 'ls'),
                   ('claude:s1', 'claude', 14, 'tool', 'tool_result', '2026-08-03T00:00:00Z', 'Bash', 'ok');",
            )
            .unwrap();
    }

    fn corpus_count_filter_cases() -> Vec<(&'static str, MessageFilters)> {
        vec![
            ("default", MessageFilters::default()),
            (
                "role",
                MessageFilters {
                    role: Some(Role::User),
                    ..Default::default()
                },
            ),
            (
                "provider",
                MessageFilters {
                    providers: Some(vec![Provider::Claude]),
                    ..Default::default()
                },
            ),
            (
                "since",
                MessageFilters {
                    since: Some(utc("2026-08-02T12:00:00Z")),
                    ..Default::default()
                },
            ),
            (
                "session",
                MessageFilters {
                    session_id: Some("claude:s1".to_string()),
                    ..Default::default()
                },
            ),
            (
                "workspace_path",
                MessageFilters {
                    workspace_path_prefix: Some("/x".to_string()),
                    ..Default::default()
                },
            ),
            (
                "tool",
                MessageFilters {
                    tool: Some("bash".to_string()),
                    ..Default::default()
                },
            ),
            (
                "no_compaction",
                MessageFilters {
                    no_compaction: true,
                    ..Default::default()
                },
            ),
            (
                "explicit_excludable_kind",
                MessageFilters {
                    kinds: Some(vec![crate::models::MessageKind::HarnessNotice]),
                    ..Default::default()
                },
            ),
        ]
    }

    /// Explicit selections outside the excludable set count by reading rows (no index carries
    /// those classes); they must still be exact.
    fn explicit_row_scanning_kind_filters() -> MessageFilters {
        MessageFilters {
            kinds: Some(vec![
                crate::models::MessageKind::Conversation,
                crate::models::MessageKind::ToolCall,
            ]),
            ..Default::default()
        }
    }

    /// The single-statement count every corpus figure used to be: correct, and a full scan of
    /// the messages table because no index carried `kind`. Kept here as the oracle.
    fn naive_corpus_count(db: &Db, filters: &MessageFilters) -> i64 {
        let mut sql = String::from("select count(*) from messages m where 1 = 1");
        let mut args = Vec::new();
        append_message_filters(&mut sql, &mut args, filters, &db.access_scope);
        db.conn
            .query_row(&sql, rusqlite::params_from_iter(args.iter()), |row| {
                row.get(0)
            })
            .unwrap()
    }

    fn query_plan(db: &Db, sql: &str, args: &[rusqlite::types::Value]) -> String {
        let mut stmt = db
            .conn
            .prepare(&format!("explain query plan {sql}"))
            .unwrap();
        stmt.query_map(rusqlite::params_from_iter(args.iter()), |row| {
            row.get::<_, String>(3)
        })
        .unwrap()
        .filter_map(Result::ok)
        .collect::<Vec<_>>()
        .join(" | ")
    }

    #[test]
    fn corpus_count_equals_the_naive_count_for_every_class_predicate() {
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_every_message_class(&db);
        for (name, filters) in corpus_count_filter_cases() {
            assert_eq!(
                db.filtered_corpus_count(&filters).unwrap(),
                naive_corpus_count(&db, &filters),
                "{name}: the decomposed count must equal the single-statement count"
            );
        }
        let explicit = explicit_row_scanning_kind_filters();
        assert_eq!(
            db.filtered_corpus_count(&explicit).unwrap(),
            naive_corpus_count(&db, &explicit),
            "explicit non-excludable classes"
        );
        // Sanity: the default predicate keeps the legacy `message` row and drops only the notice.
        assert_eq!(
            db.filtered_corpus_count(&MessageFilters::default())
                .unwrap(),
            6
        );
    }

    #[test]
    fn corpus_count_statements_are_served_from_covering_indexes() {
        // A receipt (`receipt_level=summary|full`) must never cost a scan of the messages table:
        // on a 22.6 GB index that turned a 0.5 s search into 117 s (each row's page is read to
        // test `kind`). Every statement behind the corpus figure must be answered from an index
        // that carries every column it tests, for every single-family structural filter.
        let dir = tempfile::tempdir().unwrap();
        let db = Db::open(&dir.path().join("index.db")).unwrap();
        seed_every_message_class(&db);
        // The tool-argument receipt counts the same way over the tool-call rows, which the
        // partial `idx_messages_tool_calls` answers because its predicate is the literal text.
        let mut cases = corpus_count_filter_cases()
            .into_iter()
            .map(|(name, filters)| (name, "1 = 1", filters))
            .collect::<Vec<_>>();
        cases.push((
            "tool_argument",
            "m.kind = 'tool_call'",
            MessageFilters::default(),
        ));
        for (name, base, filters) in cases {
            let statements = db.corpus_count_statements(base, &filters);
            assert!(!statements.is_empty(), "{name}: no count statements");
            for (sql, args, _sign) in &statements {
                let plan = query_plan(&db, sql, args);
                // Every step that touches the messages alias `m` (a subquery over sessions may
                // appear too) must be a covering-index step: `SCAN m USING COVERING INDEX` is
                // SQLite's count(*) optimization, `SEARCH m USING COVERING INDEX ...` a seek.
                // A bare `SCAN m` or `SEARCH m USING INDEX` (non-covering) reads message rows.
                for step in plan.split(" | ") {
                    if step.contains("SCAN m") || step.contains("SEARCH m") {
                        assert!(
                            step.contains("USING COVERING INDEX"),
                            "{name}: corpus count must not read message rows\nsql: {sql}\nplan: {plan}"
                        );
                    }
                }
                assert!(
                    plan.contains("COVERING INDEX"),
                    "{name}: corpus count must be index-only\nsql: {sql}\nplan: {plan}"
                );
            }
        }
    }

    #[test]
    fn message_kind_index_is_created_free_on_an_empty_database_and_deferred_on_a_populated_one() {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("index.db");
        let db = Db::open(&path).unwrap();
        assert!(
            db.message_kind_index_exists().unwrap(),
            "an empty database gets the class index at open, where building it is free"
        );
        seed_every_message_class(&db);
        db.conn
            .execute_batch(&format!("drop index {MESSAGE_KIND_INDEX}"))
            .unwrap();
        drop(db);
        // A populated database that lacks the index (one written by an older aise) must not pay
        // for the build inside `open`: `open` runs in every query process, the build holds the
        // write lock for one full scan of `messages`, and peers opening meanwhile would fail on
        // busy timeout. The elected writer builds it during the next refresh instead.
        let reopened = Db::open(&path).unwrap();
        assert!(
            !reopened.message_kind_index_exists().unwrap(),
            "open must defer the class index build on a populated database"
        );
        assert!(
            reopened.ensure_message_kind_index().unwrap(),
            "the maintenance path reports that it built the index"
        );
        assert!(reopened.message_kind_index_exists().unwrap());
        assert!(
            !reopened.ensure_message_kind_index().unwrap(),
            "a second call is a no-op"
        );
        // Correctness is identical with or without the index; only the plan changes.
        for (name, filters) in corpus_count_filter_cases() {
            assert_eq!(
                reopened.filtered_corpus_count(&filters).unwrap(),
                naive_corpus_count(&reopened, &filters),
                "{name}"
            );
        }
    }
}