Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
717 KB
Raw Blame
//! Read-only connection pool and query helpers.
//!
//! WAL mode lets us have unlimited concurrent readers alongside the single
//! writer, so the pool is mostly about bounding file-descriptor usage and
//! avoiding `Connection::open` overhead on hot paths. Pool eviction is a
//! soft cap: a connection that comes back when the pool is already full
//! is simply dropped.

use std::collections::BTreeMap;
use std::fmt::Write as _;
use std::path::{Path, PathBuf};
use std::str::FromStr;
use std::sync::Arc;

use ai_memory_core::{
    AgentKind, AgentMessage, AutoImproveProposalId, AutoImproveRunId, FAILED_TOOL_OUTCOME_LINE,
    Handoff, HandoffContent, HandoffId, HandoffLifecycle, HandoffOrigin, HandoffScope,
    HandoffState, IdentityKey, ManagedRunId, MessageBox, Observation, ObservationId,
    ObservationKind, OwnerFilter, PageId, PagePath, ProjectId, SessionId,
    TOOL_BODY_HEADER_MAX_CHARS, TOOL_BODY_SEPARATOR, User, UserId, WorkspaceId, WorkstreamEvent,
    WorkstreamId,
};
use jiff::Timestamp;
use parking_lot::Mutex;
use rusqlite::types::Value;
use rusqlite::{Connection, OpenFlags, OptionalExtension, params, params_from_iter};
use serde::{Deserialize, Serialize};
use uuid::Uuid;
// `ai_memory_core::Tier` is referenced via fully-qualified path inside the
// DecayCandidate struct definition above to avoid a top-level import
// for a single use-site.

use crate::auto_improve::{
    AutoImproveProposalDetail, AutoImproveProposalEvent, AutoImproveProposalStatus,
    AutoImproveProposalSummary, AutoImproveRejectionSummary, AutoImproveTelemetryAggregate,
    AutoImproveTelemetryCount, OwnedAutoImproveProposalDetail, PendingAutoImproveReview,
    PendingAutoImproveScope, bytes32, opt_bytes32, summary_from_row, to_sql_err,
};
use crate::error::{StoreError, StoreResult};
use crate::fts_query::{FtsStopwords, prepare_cjk_fts5_query, prepare_fts5_query};
use crate::maintenance::MaintenanceJob;
use crate::retrieval_tuning::{RetrievalTuning, is_session_recall_query};
use crate::users::TOKEN_HASH_LEN;
use crate::workstream::{
    ManagedRunContext, OperationalWorkstreamSummary, StoredManagedRunStatus,
    StoredWorkstreamSummary,
};

/// TTL guard for retrieval surfaces (search / recent / embedding hits /
/// graph neighbours / briefing lists): appended to a WHERE clause that
/// already constrains `is_latest = 1`. `table` is the pages alias in
/// that query; `now_param` is the positional placeholder bound to the
/// current wall-clock in microseconds. One definition so the
/// NULL-handling never drifts between queries. Exact-path/id reads and
/// the decay-candidate walk deliberately do NOT use this — reads
/// annotate expiry instead of hiding it, and the sweep must see
/// expired rows to delete them.
pub(crate) fn not_expired(table: &str, now_param: &str) -> String {
    format!(" AND ({table}.expires_at IS NULL OR {table}.expires_at > {now_param})")
}

/// Latest-version guard for retrieval candidate queries (FTS / vector /
/// entity / graph). When `include_superseded` is false — the default — this
/// restricts a candidate query to the current version with
/// `AND {table}.is_latest = 1`; when true it returns an empty fragment so
/// superseded versions enter the candidate pool too. `table` is the pages
/// alias in that query. One definition so the opt-in never drifts between
/// streams, and the default fragment is byte-identical to the literal it
/// replaces. The fragment carries no bound placeholder, so dropping it never
/// disturbs positional parameter ordering.
fn latest_only(table: &str, include_superseded: bool) -> String {
    if include_superseded {
        String::new()
    } else {
        format!(" AND {table}.is_latest = 1")
    }
}

/// Current wall-clock in microseconds, for binding against
/// [`not_expired`] fragments.
pub(crate) fn now_us() -> i64 {
    Timestamp::now().as_microsecond()
}

/// Visibility guard for the page-history readers ([`ReaderPool::page_versions`],
/// [`ReaderPool::page_version_body`]). A version is hidden when its own TTL
/// has passed, the same per-row [`not_expired`] rule the superseded-inclusive
/// retrieval streams apply, and also when the live version at its path has
/// expired: the forget sweep hard-deletes every row at that path, so the
/// history of an expired page is as hidden as the page itself. The readers
/// also report a `supersedes` link to a hidden version as `None`, so an
/// expired version's id does not surface through its successor.
fn history_visible(table: &str, now_param: &str) -> String {
    format!(
        "{per_row} AND NOT EXISTS (SELECT 1 FROM pages live \
         WHERE live.workspace_id = {table}.workspace_id \
           AND live.project_id = {table}.project_id \
           AND live.path = {table}.path AND live.is_latest = 1 \
           AND live.expires_at IS NOT NULL AND live.expires_at <= {now_param})",
        per_row = not_expired(table, now_param),
    )
}

/// Restrict `project_column` to the repositories `viewer` may read (#708).
///
/// Returns a fragment to append to a `WHERE` clause and the values it binds,
/// numbered from `?{first_param}`. For `None` the fragment is empty and binds
/// nothing, so a query built with no viewer is exactly the query it was before
/// authorization existed — which is what an install with no database users and
/// the root operator both need.
///
/// "May read" is what [`crate::authorize_project`] admits for
/// [`crate::ProjectAccess::Read`]: a project that is not `restricted` (an
/// unrecognised mode reads as open there too), one the viewer created, or one
/// they hold any grant on — every level admits a read, and a test pins the two
/// together. The global
/// preferences scope is always readable: it is shared by construction (see
/// `lookup_global_scope`).
///
/// This belongs in the query, before `LIMIT`, not applied to the rows after.
/// Filtering afterwards hands a user three results out of ten because seven
/// were somebody else's: search that quietly gets worse, and a count that
/// tells them how much is being hidden.
pub(crate) fn readable_repository_filter(
    project_column: &str,
    viewer: Option<UserId>,
    first_param: usize,
) -> (String, Vec<Value>) {
    let Some(viewer) = viewer else {
        return (String::new(), Vec::new());
    };
    let (user, workspace, project) = (first_param, first_param + 1, first_param + 2);
    let fragment = readable_repository_sql(
        project_column,
        &format!("?{user}"),
        &format!("?{workspace}"),
        &format!("?{project}"),
    );
    let bound = vec![
        Value::Blob(viewer.as_bytes().to_vec()),
        Value::Text(ai_memory_core::DEFAULT_WORKSPACE_NAME.to_owned()),
        Value::Text(ai_memory_core::GLOBAL_SCOPE_PROJECT.to_owned()),
    ];
    (fragment, bound)
}

/// [`readable_repository_filter`] with its three values written into the SQL
/// instead of bound.
///
/// For statements that cannot take extra parameters without renumbering the
/// ones they already have: the workspace briefing alone runs a dozen, mixing
/// numbered and anonymous placeholders, and threading three more binds through
/// each would rewrite upstream SQL for no gain in safety. Splicing a fragment
/// in, the way [`not_expired`] already is, leaves them untouched.
///
/// Nothing here comes from a caller. The user id is a 16-byte UUID the store
/// generated, rendered as a hex blob literal, and the other two values are
/// compile-time constants, quoted defensively all the same. Both helpers build
/// from [`readable_repository_sql`], so they cannot disagree about who may
/// read what.
///
/// The cost is one distinct SQL string per user, so a `prepare_cached`
/// statement using this caches one entry per viewer. The cache is a bounded
/// LRU and the callers are operator views, not the per-call agent path; a hot
/// query should take [`readable_repository_filter`] instead.
pub(crate) fn readable_repository_predicate(
    project_column: &str,
    viewer: Option<UserId>,
) -> String {
    let Some(viewer) = viewer else {
        return String::new();
    };
    let hex: String = viewer
        .as_bytes()
        .iter()
        .map(|byte| format!("{byte:02x}"))
        .collect();
    let text = |value: &str| format!("'{}'", value.replace('\'', "''"));
    readable_repository_sql(
        project_column,
        &format!("X'{hex}'"),
        &text(ai_memory_core::DEFAULT_WORKSPACE_NAME),
        &text(ai_memory_core::GLOBAL_SCOPE_PROJECT),
    )
}

/// The one definition of "a repository this user may read", as SQL.
///
/// Callers supply how the user id and the global scope's workspace and project
/// names are referenced — placeholders or literals — and nothing else.
fn readable_repository_sql(
    project_column: &str,
    user: &str,
    workspace: &str,
    project: &str,
) -> String {
    // Aliased so the subqueries cannot bind to a `projects` / `workspaces`
    // already joined by the query this is appended to.
    format!(
        " AND ({project_column} IN (SELECT op.id FROM projects op \
                                    WHERE op.access_mode <> 'restricted' \
                                       OR op.created_by = {user}) \
               OR {project_column} IN (SELECT pg.project_id FROM project_grants pg \
                                    WHERE pg.user_id = {user}) \
               OR {project_column} IN (SELECT gp.id FROM projects gp \
                                       JOIN workspaces gw ON gw.id = gp.workspace_id \
                                       WHERE gw.name = {workspace} AND gp.name = {project}))"
    )
}

/// Path prefix to kind, in match order: the kind a page has when its
/// frontmatter names none.
const PATH_KINDS: [(&str, &str); 9] = [
    ("_rules/", "rule"),
    ("_slots/", "slot"),
    ("sessions/", "session"),
    ("decisions/", "decision"),
    ("gotchas/", "gotcha"),
    ("concepts/", "concept"),
    ("procedures/", "procedure"),
    ("notes/", "note"),
    ("profile/", "preference"),
];

/// Kind of a page whose frontmatter names none and whose path matches no
/// [`PATH_KINDS`] prefix.
const DEFAULT_PAGE_KIND: &str = "fact";

/// Every kind a page can have without custom frontmatter, as
/// `page_kind_expr` derives it.
pub const PAGE_KINDS: [&str; 10] = [
    "rule",
    "slot",
    "session",
    "decision",
    "gotcha",
    "concept",
    "procedure",
    "note",
    "preference",
    DEFAULT_PAGE_KIND,
];

pub(crate) fn page_kind_expr(path_column: &str, frontmatter_column: &str) -> String {
    let arms: String = PATH_KINDS
        .iter()
        .map(|(prefix, kind)| {
            // `_` is a LIKE wildcard; escape it so `_rules/` matches only itself.
            let prefix = prefix.replace('_', "\\_");
            format!("WHEN {path_column} LIKE '{prefix}%' ESCAPE '\\' THEN '{kind}' ")
        })
        .collect();
    // The cast keeps a non-string frontmatter `kind` (`kind: 5`) readable as
    // text instead of failing the row.
    format!(
        "COALESCE( \
            CAST(json_extract({frontmatter_column}, '$.kind') AS TEXT), \
            CASE {arms}ELSE '{DEFAULT_PAGE_KIND}' END \
        )"
    )
}

#[cfg(test)]
mod page_kind_tests {
    use super::*;

    #[test]
    fn page_kinds_lists_every_path_kind_and_the_default() {
        let mut expected: Vec<&str> = PATH_KINDS.iter().map(|(_, kind)| *kind).collect();
        expected.push(DEFAULT_PAGE_KIND);
        assert_eq!(PAGE_KINDS.to_vec(), expected);
    }

    #[test]
    fn page_kind_expr_resolves_paths_and_non_string_kinds() {
        let conn = rusqlite::Connection::open_in_memory().unwrap();
        let sql = format!(
            "SELECT {} FROM (SELECT ?1 AS path, ?2 AS fm)",
            page_kind_expr("path", "fm")
        );
        let kind = |path: &str, fm: &str| -> String {
            conn.query_row(&sql, [path, fm], |row| row.get(0)).unwrap()
        };
        assert_eq!(kind("_rules/a.md", "{}"), "rule");
        assert_eq!(kind("xrules/a.md", "{}"), "fact");
        assert_eq!(kind("profile/a.md", "{}"), "preference");
        assert_eq!(kind("sessions/a.md", r#"{"kind":"custom"}"#), "custom");
        assert_eq!(kind("sessions/a.md", r#"{"kind":5}"#), "5");
    }
}

/// Leading body characters scanned when a page carries no frontmatter
/// `summary`. Wide enough to step past the `# Title` line and a structural
/// heading or two before the first real prose.
const DESCRIPTOR_SCAN_CHARS: usize = 600;

/// Maximum length of a synthesised page descriptor, in characters.
const DESCRIPTOR_MAX_CHARS: usize = 240;

/// Upper bound on the pinned standing-context list carried by a project
/// [`BriefingSnapshot`] (`memory_briefing`), so SessionStart hot-context stays
/// bounded no matter how many pages a project has pinned.
const BRIEFING_PINNED_LIMIT: usize = 10;

/// SQL expression yielding the raw material for [`page_descriptor`]: the
/// page's own frontmatter `summary` when it has a non-blank one, otherwise a
/// prefix of the body. `NULLIF(TRIM(...), '')` keeps an empty summary from
/// winning the `COALESCE` over real body text.
fn page_descriptor_expr(body_column: &str, frontmatter_column: &str) -> String {
    format!(
        "COALESCE( \
            NULLIF(TRIM(json_extract({frontmatter_column}, '$.summary')), ''), \
            substr({body_column}, 1, {DESCRIPTOR_SCAN_CHARS}) \
        )"
    )
}

/// Strip a leading markdown list marker (`- `, `* `, `+ `, `1. `) so a kept
/// line reads as prose in the descriptor.
fn strip_list_marker(line: &str) -> &str {
    if let Some(rest) = line
        .strip_prefix("- ")
        .or_else(|| line.strip_prefix("* "))
        .or_else(|| line.strip_prefix("+ "))
    {
        return rest.trim_start();
    }
    let digits = line.chars().take_while(char::is_ascii_digit).count();
    if digits > 0 && line[digits..].starts_with(". ") {
        return line[digits + 2..].trim_start();
    }
    line
}

/// `true` for the `- **key:** value` bullets that open a compiled session
/// page's metadata block — session id, timestamps, observation count. They
/// are addressing, not content.
fn is_metadata_bullet(line: &str) -> bool {
    line.starts_with("- **") && line.contains(":**")
}

/// Page-intrinsic descriptor for a retrieval hit.
///
/// The FTS path centres its excerpt on the matched terms through
/// `snippet(pages_fts, ...)`. The vector, entity-match, graph-neighbour and
/// recency paths have no matched term to centre on. They previously returned
/// `substr(body, 1, 240)`, which on a compiled page is the `# Title` line plus
/// the `## Session metadata` block under it — the title the hit already
/// carries, followed by a session id and three timestamps.
///
/// Fills the [`DESCRIPTOR_MAX_CHARS`] budget from the page's own text,
/// skipping four things that carry no signal for the reader deciding whether
/// to open the page: structural lines, metadata bullets, and any line that
/// merely repeats `title`. On a session page that lands on the prompts after
/// the first, which is the part `title` does not already show.
fn page_descriptor(raw: &str, title: &str) -> String {
    // `truncate_for_title` suffixes an ellipsis only when it shortened the
    // title, so an ellipsis-free title is complete: a longer line that merely
    // opens with it is a different sentence and must be kept.
    let title_trimmed = title.trim();
    let title_was_truncated = title_trimmed.ends_with('\u{2026}');
    let title_key = title_trimmed.trim_end_matches('\u{2026}').trim();
    let mut out = String::new();
    for line in raw.lines().map(str::trim) {
        if line.is_empty()
            || line.starts_with('#')
            || line.starts_with("---")
            || line.starts_with("___")
            || line.starts_with("***")
            || is_metadata_bullet(line)
        {
            continue;
        }
        let content = strip_list_marker(line).trim();
        if content.is_empty() {
            continue;
        }
        let repeats_title = !title_key.is_empty()
            && if title_was_truncated {
                content.starts_with(title_key)
            } else {
                content == title_key
            };
        if repeats_title {
            continue;
        }
        if !out.is_empty() {
            if out.chars().count() + 1 + content.chars().count() > DESCRIPTOR_MAX_CHARS {
                break;
            }
            out.push(' ');
        }
        out.push_str(content);
        if out.chars().count() >= DESCRIPTOR_MAX_CHARS {
            break;
        }
    }
    if out.is_empty() {
        return truncate_chars(raw.trim(), DESCRIPTOR_MAX_CHARS);
    }
    truncate_chars(&out, DESCRIPTOR_MAX_CHARS)
}

/// Truncate on a character boundary, marking elision with an ellipsis.
fn truncate_chars(text: &str, max: usize) -> String {
    if text.chars().count() <= max {
        return text.to_owned();
    }
    let mut out: String = text.chars().take(max.saturating_sub(1)).collect();
    out.push('\u{2026}');
    out
}

const AUTHORITY_CANDIDATE_MULTIPLIER: usize = 4;
const AUTHORITY_MIN_CANDIDATES: usize = 20;
const AUTHORITY_MAX_EXTRA_CANDIDATES: usize = 300;

/// Observation rows the R1 observation stream reads per stream candidate.
/// Observations outnumber session pages by an order of magnitude and one
/// session's turns often match together, so the window is wider than the
/// page-candidate window it feeds; deduplication by session brings it back
/// down to at most `candidate_limit` pages.
const OBSERVATION_STREAM_ROWS_PER_CANDIDATE: usize = 4;
/// Hard cap on observation rows read per query, whatever the limit.
const OBSERVATION_STREAM_MAX_ROWS: usize = 1_000;
/// Matched observation ids reported per page in `explain`.
const OBSERVATION_STREAM_IDS_PER_PAGE: usize = 3;
/// Token window of the observation excerpt shown as a hit's snippet. Session
/// pages are short, so their own FTS snippets rarely fill the 24-token page
/// window; an observation body usually does, and a full window made each
/// excerpt-backed hit cost more context than the page hit it stands in for.
const OBSERVATION_SNIPPET_TOKENS: usize = 16;
/// Internal FTS highlight delimiters. Durable text crosses the sanitizer,
/// which strips both control characters, so page content cannot impersonate
/// a match. Presentation boundaries translate these markers to HTML or remove
/// them for plain-text/model input.
pub const FTS_HIGHLIGHT_START: &str = "\u{1e}";
/// Closing delimiter paired with [`FTS_HIGHLIGHT_START`].
pub const FTS_HIGHLIGHT_END: &str = "\u{1f}";

/// Remove internal FTS highlight delimiters without altering page text.
#[must_use]
pub fn plain_snippet(snippet: &str) -> String {
    snippet
        .replace(FTS_HIGHLIGHT_START, "")
        .replace(FTS_HIGHLIGHT_END, "")
}

/// Render an internal FTS snippet as safe HTML, preserving only highlights
/// produced by SQLite. All page text, including literal `<mark>` tags, is
/// escaped before it reaches an HTML `|safe` boundary or JSON frontend.
#[must_use]
pub fn highlighted_snippet_html(snippet: &str) -> String {
    let mut out = String::with_capacity(snippet.len());
    let mut rest = snippet;
    while let Some(at) = rest.find(FTS_HIGHLIGHT_START) {
        let after = &rest[at + FTS_HIGHLIGHT_START.len()..];
        let Some(close) = after.find(FTS_HIGHLIGHT_END) else {
            break;
        };
        push_html_escaped(&mut out, &rest[..at]);
        out.push_str("<mark>");
        push_html_escaped(&mut out, &after[..close]);
        out.push_str("</mark>");
        rest = &after[close + FTS_HIGHLIGHT_END.len()..];
    }
    push_html_escaped(&mut out, rest);
    out
}

fn push_html_escaped(out: &mut String, input: &str) {
    for c in input.chars() {
        match c {
            '&' => out.push_str("&amp;"),
            '<' => out.push_str("&lt;"),
            '>' => out.push_str("&gt;"),
            '"' => out.push_str("&quot;"),
            '\'' => out.push_str("&#39;"),
            _ => out.push(c),
        }
    }
}

fn serialize_highlighted_snippet<S>(snippet: &str, serializer: S) -> Result<S::Ok, S::Error>
where
    S: serde::Serializer,
{
    serializer.serialize_str(&highlighted_snippet_html(snippet))
}
/// A project's first and last observation rowid, bound to `?1` = project id.
///
/// `idx_observations_project` is `(project_id)` with the implicit rowid
/// suffix, so each scalar subquery is a single min/max seek. Filtering on
/// `(workspace_id, project_id)` instead lets the planner pick the
/// created_at-ordered `idx_observations_project_created` and walk every one
/// of the project's entries. Project ids are unique across workspaces (V18's
/// pairing triggers keep `observations.workspace_id` equal to the project's),
/// so the workspace predicate adds nothing here.
pub(crate) const OBSERVATION_ROWID_SPAN_SQL: &str = "SELECT \
     (SELECT MIN(rowid) FROM observations INDEXED BY idx_observations_project \
      WHERE project_id = ?1), \
     (SELECT MAX(rowid) FROM observations INDEXED BY idx_observations_project \
      WHERE project_id = ?1)";

#[derive(Debug, Clone, Copy)]
struct PageAuthority {
    factor: f64,
    /// Kind/tier penalty this page carries *because* it is a session page
    /// (`0.0` for every other kind). A `session_recall` query gives it back.
    session_penalty: f64,
}

impl PageAuthority {
    fn from_stored(
        path: &str,
        kind: &str,
        tier: &str,
        pinned: bool,
        frontmatter_json: &str,
    ) -> Self {
        // Relevance remains primary: even the strongest maintained page gets
        // at most a 1.5x boost, while explicit low-authority metadata bottoms
        // out at 0.55x rather than excluding the page.
        let mut factor = 1.0_f64;

        let kind_adjust = match kind {
            "rule" | "decision" => 0.15,
            "procedure" | "gotcha" | "preference" => 0.12,
            "concept" | "slot" => 0.07,
            "session" => -0.15,
            _ => 0.0,
        };
        let tier_adjust = match tier {
            "semantic" | "procedural" => 0.10,
            "episodic" => -0.08,
            "working" => -0.03,
            _ => 0.0,
        };
        factor += kind_adjust + tier_adjust;
        let session_penalty = if kind == "session" {
            -(kind_adjust + tier_adjust.min(0.0))
        } else {
            0.0
        };
        if pinned {
            factor += 0.08;
        }

        if path.starts_with("_lint/") {
            factor -= 0.20;
        } else if path.starts_with("investigations/") {
            factor -= 0.05;
        }

        let tags = authority_tags(frontmatter_json);
        if tags
            .iter()
            .any(|tag| tag == "canonical" || tag == "source-of-truth")
        {
            factor += 0.20;
        }
        if tags.iter().any(|tag| tag == "active") {
            factor += 0.05;
        }

        // Negative tags are explicit curator instructions. They cap the
        // result's authority instead of merely cancelling a canonical path
        // boost, but they never remove the page from search.
        if tags
            .iter()
            .any(|tag| tag == "do-not-answer-from" || tag == "test-fixture")
        {
            factor = factor.min(0.55);
        } else if tags.iter().any(|tag| tag == "superseded") {
            factor = factor.min(0.65);
        } else if tags.iter().any(|tag| tag == "historical") {
            factor = factor.min(0.80);
        }

        Self {
            factor: factor.clamp(0.55, 1.50),
            session_penalty,
        }
    }

    fn adjust_rank(&self, rank: f64) -> f64 {
        apply_rank_multiplier(rank, self.factor)
    }

    /// Effective multiplier when the query routed to session-recall
    /// retrieval: session pages get the kind/tier penalty they carry by
    /// default handed back plus `bonus`, still inside the bounds every
    /// other page lives in. Any other query leaves the factor alone.
    fn factor_for(&self, session_recall: bool, bonus: f64) -> f64 {
        if session_recall && self.session_penalty > 0.0 {
            (self.factor + self.session_penalty + bonus).clamp(0.55, 1.50)
        } else {
            self.factor
        }
    }
}

/// Scale a rank by a `> 0` multiplier so a larger multiplier always means a
/// better (lower) rank, whichever sign convention the rank arrived in: fused
/// RRF ranks are negated scores (`<= 0`), raw FTS5 ranks are positive.
fn apply_rank_multiplier(rank: f64, multiplier: f64) -> f64 {
    if rank <= 0.0 {
        rank * multiplier
    } else {
        rank / multiplier
    }
}

/// The two embedding tables share one schema; scans differ only by name.
#[derive(Debug, Clone, Copy)]
enum EmbeddingTable {
    /// `page_embeddings`: one vector per page over the full body.
    Body,
    /// `page_abstract_embeddings`: one vector per page over its L0
    /// frontmatter `abstract:` line (opt-in stream).
    Abstract,
}

impl EmbeddingTable {
    fn name(self) -> &'static str {
        match self {
            Self::Body => "page_embeddings",
            Self::Abstract => "page_abstract_embeddings",
        }
    }
}

fn authority_tags(frontmatter_json: &str) -> Vec<String> {
    serde_json::from_str::<serde_json::Value>(frontmatter_json)
        .ok()
        .and_then(|frontmatter| frontmatter.get("tags").cloned())
        .and_then(|tags| tags.as_array().cloned())
        .unwrap_or_default()
        .into_iter()
        .filter_map(|tag| tag.as_str().map(normalize_authority_tag))
        .collect()
}

fn normalize_authority_tag(tag: &str) -> String {
    tag.trim().to_ascii_lowercase().replace('_', "-")
}

fn authority_candidate_limit(limit: usize) -> usize {
    if limit == 0 {
        return 0;
    }
    limit
        .saturating_mul(AUTHORITY_CANDIDATE_MULTIPLIER)
        .max(AUTHORITY_MIN_CANDIDATES)
        .min(limit.saturating_add(AUTHORITY_MAX_EXTRA_CANDIDATES))
}

fn rerank_page_hits(candidates: Vec<(PageHit, PageAuthority)>, limit: usize) -> Vec<PageHit> {
    let mut hits: Vec<PageHit> = candidates
        .into_iter()
        .map(|(mut hit, authority)| {
            hit.rank = authority.adjust_rank(hit.rank);
            hit
        })
        .collect();
    hits.sort_by(|a, b| {
        a.rank
            .partial_cmp(&b.rank)
            .unwrap_or(std::cmp::Ordering::Equal)
    });
    hits.truncate(limit);
    hits
}

fn rerank_page_hits_with_meta(
    candidates: Vec<(PageHitWithMeta, PageAuthority)>,
    limit: usize,
) -> Vec<PageHitWithMeta> {
    let mut hits: Vec<PageHitWithMeta> = candidates
        .into_iter()
        .map(|(mut hit, authority)| {
            hit.rank = authority.adjust_rank(hit.rank);
            hit
        })
        .collect();
    hits.sort_by(|a, b| {
        a.rank
            .partial_cmp(&b.rank)
            .unwrap_or(std::cmp::Ordering::Equal)
    });
    hits.truncate(limit);
    hits
}

/// Fuse the ordinary unicode61 and opt-in CJK lexical streams before the
/// existing authority adjustment. The ordinary stream is returned untouched
/// when no auxiliary hits exist, which keeps non-CJK ranking byte-identical.
fn fuse_page_candidate_streams(
    primary: Vec<(PageHit, PageAuthority)>,
    auxiliary: Vec<(PageHit, PageAuthority)>,
    limit: usize,
) -> Vec<(PageHit, PageAuthority)> {
    if auxiliary.is_empty() {
        return primary;
    }
    let mut fused: std::collections::HashMap<PageId, (PageHit, PageAuthority, f64)> =
        std::collections::HashMap::new();
    for stream in [primary, auxiliary] {
        for (rank, (hit, authority)) in stream.into_iter().enumerate() {
            let contribution = 1.0 / (60.0 + (rank + 1) as f64);
            fused
                .entry(hit.id)
                .and_modify(|entry| entry.2 += contribution)
                .or_insert((hit, authority, contribution));
        }
    }
    let mut out: Vec<_> = fused
        .into_values()
        .map(|(mut hit, authority, score)| {
            hit.rank = -score;
            (hit, authority)
        })
        .collect();
    out.sort_by(|a, b| {
        a.0.rank
            .partial_cmp(&b.0.rank)
            .unwrap_or(std::cmp::Ordering::Equal)
            .then_with(|| a.0.path.as_str().cmp(b.0.path.as_str()))
    });
    out.truncate(limit);
    out
}

fn fuse_page_meta_candidate_streams(
    primary: Vec<(PageHitWithMeta, PageAuthority)>,
    auxiliary: Vec<(PageHitWithMeta, PageAuthority)>,
    limit: usize,
) -> Vec<(PageHitWithMeta, PageAuthority)> {
    if auxiliary.is_empty() {
        return primary;
    }
    let mut fused: std::collections::HashMap<PageId, (PageHitWithMeta, PageAuthority, f64)> =
        std::collections::HashMap::new();
    for stream in [primary, auxiliary] {
        for (rank, (hit, authority)) in stream.into_iter().enumerate() {
            let contribution = 1.0 / (60.0 + (rank + 1) as f64);
            fused
                .entry(hit.id)
                .and_modify(|entry| entry.2 += contribution)
                .or_insert((hit, authority, contribution));
        }
    }
    let mut out: Vec<_> = fused
        .into_values()
        .map(|(mut hit, authority, score)| {
            hit.rank = -score;
            (hit, authority)
        })
        .collect();
    out.sort_by(|a, b| {
        a.0.rank
            .partial_cmp(&b.0.rank)
            .unwrap_or(std::cmp::Ordering::Equal)
            .then_with(|| a.0.path.as_str().cmp(b.0.path.as_str()))
    });
    out.truncate(limit);
    out
}

fn fuse_observation_streams(
    primary: Vec<ObservationHit>,
    auxiliary: Vec<ObservationHit>,
    limit: usize,
) -> Vec<ObservationHit> {
    if auxiliary.is_empty() {
        return primary;
    }
    let mut fused: std::collections::HashMap<ObservationId, (ObservationHit, f64)> =
        std::collections::HashMap::new();
    for stream in [primary, auxiliary] {
        for (rank, hit) in stream.into_iter().enumerate() {
            let contribution = 1.0 / (60.0 + (rank + 1) as f64);
            fused
                .entry(hit.id)
                .and_modify(|entry| entry.1 += contribution)
                .or_insert((hit, contribution));
        }
    }
    let mut out: Vec<_> = fused
        .into_values()
        .map(|(mut hit, score)| {
            hit.rank = -score;
            hit
        })
        .collect();
    out.sort_by(|a, b| {
        a.rank
            .partial_cmp(&b.rank)
            .unwrap_or(std::cmp::Ordering::Equal)
            .then_with(|| a.created_at.cmp(&b.created_at))
    });
    out.truncate(limit);
    out
}

/// Rows keyed to one session (see [`ReaderPool::session_dependent_rows`]).
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct SessionDependentRows {
    /// `observations` rows of the session, in any scope.
    pub observations: u64,
    /// `handoffs` rows the session produced, in any scope.
    pub handoffs: u64,
    /// `session_consolidation_jobs` rows, in any scope.
    pub consolidation_jobs: u64,
    /// `auto_improve_runs` rows, in any scope.
    pub auto_improve_runs: u64,
    /// `auto_improve_scheduler_claims` rows, in any scope.
    pub auto_improve_claims: u64,
    /// Versions of `sessions/<id>.md` in the queried page scope.
    pub page_versions: u64,
    /// Latest versions of `sessions/<id>.md` in the queried page scope
    /// (0 or 1).
    pub page_latest: u64,
}

/// One page flagged by `stale`/`wrong` feedback on its current version,
/// aggregated per (page, kind) for the lint pass.
#[derive(Debug, Clone, Serialize)]
pub struct FeedbackFinding {
    /// Wiki path of the flagged page.
    pub path: String,
    /// `stale` or `wrong`.
    pub kind: String,
    /// How many signals of this kind the current version has.
    pub signal_count: u32,
    /// ISO-8601 timestamp of the most recent signal.
    pub latest_at: String,
    /// Most recent caller-supplied reason for this kind, if any.
    pub reason: Option<String>,
}

/// A page matched by the entity stream, with the inverse-frequency
/// weight that ranked it and the entity names that matched.
#[derive(Debug, Clone)]
pub struct EntityHit {
    /// The matched page.
    pub hit: PageHit,
    /// Sum of `1 / pages_carrying_entity` over the matched entities.
    pub weight: f64,
    /// Entity names that matched the query.
    pub matched: Vec<String>,
}

/// Escape a literal for use inside a SQL `LIKE` pattern with
/// `ESCAPE '\'`. Entity tokens legitimately contain `_`, which `LIKE`
/// would otherwise treat as "any single character" — so `foo_bar` would
/// match `fooxbar`.
fn like_escape(literal: &str) -> String {
    literal
        .replace('\\', "\\\\")
        .replace('%', "\\%")
        .replace('_', "\\_")
}

/// Split a query into entity-match tokens: lowercase, alphanumeric-ish
/// runs, 3+ characters, de-duplicated, bounded. Short tokens are
/// dropped because a 1-2 character prefix match is noise, not a signal.
///
/// A hyphenated/underscored run yields BOTH the whole token and its
/// parts — the same both-forms trick [`crate::ops::path_search_text`]
/// uses on paths, and for the same reason: an entity may be written
/// `ai-memory`, `ai_memory`, or `ai memory`, and the query may pick
/// any of them.
fn entity_query_tokens(query: &str) -> Vec<String> {
    /// Beyond this the query is prose, not a set of nouns; the FTS
    /// stream already handles prose better than prefix matching does.
    const MAX_TOKENS: usize = 12;
    const MIN_TOKEN_CHARS: usize = 3;
    let mut seen = std::collections::BTreeSet::new();
    let mut out = Vec::new();
    let mut push = |raw: &str| -> bool {
        let char_count = raw.chars().count();
        if !(MIN_TOKEN_CHARS..=ai_memory_core::MAX_ENTITY_LEN).contains(&char_count) {
            return true;
        }
        let token = raw.to_lowercase();
        if seen.insert(token.clone()) {
            out.push(token);
        }
        out.len() < MAX_TOKENS
    };
    'outer: for raw in query.split(|c: char| !(c.is_alphanumeric() || c == '-' || c == '_')) {
        let token = raw.trim_matches(['-', '_']);
        if token.is_empty() {
            continue;
        }
        let compound = token.contains(['-', '_']);
        if !push(token) {
            break;
        }
        if compound {
            for part in token.split(['-', '_']) {
                if !push(part) {
                    break 'outer;
                }
            }
        }
    }
    out
}

/// A graph-expansion neighbour with provenance (which seed and which
/// link direction produced it). Internal to hybrid search + explain.
struct GraphNeighbor {
    hit: PageHit,
    /// Index into the seed list handed to the expansion.
    seed_ord: usize,
    /// `true` when the neighbour links TO the seed (backlink).
    incoming: bool,
    /// The typed edge the neighbour was reached by (`causes` / `fixes` /
    /// `contradicts`), or `None` for a plain `references` link. Informational
    /// only — it is surfaced in `explain` and does not affect ranking.
    edge: Option<String>,
}

/// One session page voted for by the R1 observation stream. Internal to
/// hybrid search + explain.
struct ObservationVote {
    page_id: PageId,
    path: PagePath,
    title: String,
    /// FTS5 snippet of the session's best-ranked matching observation.
    /// Observations are sanitized and bounded on the way in, and the snippet
    /// is a bounded window over that stored text. `None` when the caller's
    /// owner filter may not read the session: the vote still counts, since
    /// session pages are shared, but the observation text stays with its
    /// owner.
    snippet: Option<String>,
    /// Best-ranked first, at most [`OBSERVATION_STREAM_IDS_PER_PAGE`]; empty
    /// under the same rule as `snippet`.
    observation_ids: Vec<ObservationId>,
}

/// The voting sessions whose observations `owner_filter` may not read, by
/// the session-timeline rule ([`OwnerFilter::admits`] on `sessions.actor_user`).
///
/// `OwnerFilter::Any` hides nothing and reads nothing, so the single-user and
/// evaluation paths run exactly the query they ran before. One batched read
/// over at most the stream's candidate sessions otherwise.
fn sessions_hidden_from(
    conn: &rusqlite::Connection,
    owner_filter: &OwnerFilter,
    sessions: &[(SessionId, String, Vec<ObservationId>)],
) -> StoreResult<std::collections::HashSet<SessionId>> {
    let mut hidden = std::collections::HashSet::new();
    if matches!(owner_filter, OwnerFilter::Any) || sessions.is_empty() {
        return Ok(hidden);
    }
    let placeholders = vec!["?"; sessions.len()].join(", ");
    let mut stmt = conn.prepare(&format!(
        "SELECT id, actor_user FROM sessions WHERE id IN ({placeholders})"
    ))?;
    let ids: Vec<Value> = sessions
        .iter()
        .map(|(session_id, _, _)| Value::Blob(session_id.as_bytes().to_vec()))
        .collect();
    let rows = stmt.query_map(params_from_iter(ids.iter()), |row| {
        Ok((row.get::<_, Vec<u8>>(0)?, row.get::<_, Option<String>>(1)?))
    })?;
    let mut known = std::collections::HashSet::new();
    for row in rows {
        let (id_bytes, actor_user) = row?;
        let session_id = SessionId::from_slice(&id_bytes)?;
        known.insert(session_id);
        if !owner_filter.admits(actor_user.as_deref()) {
            hidden.insert(session_id);
        }
    }
    // An observation whose session row is gone has no owner to check
    // against; keep its text back rather than guess.
    for (session_id, _, _) in sessions {
        if !known.contains(session_id) {
            hidden.insert(*session_id);
        }
    }
    Ok(hidden)
}

/// Which seed page pulled a hit in via graph expansion, and the link
/// direction. Part of [`SearchExplain`].
#[derive(Debug, Clone, Serialize)]
pub struct GraphVia {
    /// Path of the FTS/entity/vector seed page the link was followed from.
    pub seed_path: String,
    /// `outgoing` = seed links to the hit; `incoming` = hit links to
    /// the seed (backlink).
    pub direction: &'static str,
    /// The typed edge kind followed (`causes` / `fixes` / `contradicts`),
    /// omitted for a plain `references` link. Informational: it explains *why*
    /// a neighbour surfaced; it does not weight ranking (typed-edge weighting
    /// and `contradicts` capping are deferred behind the eval harness).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub edge: Option<String>,
}

/// Per-stream RRF contributions (`1/(k+rank)`, k=60) for one hit.
#[derive(Debug, Clone, Default, Serialize)]
pub struct RrfContributions {
    /// FTS5 stream contribution (0.0 when the hit missed that stream, and
    /// for a session page the observation stream voted for, whose lexical
    /// evidence comes from that stream instead).
    pub fts: f64,
    /// Vector stream contribution.
    pub vector: f64,
    /// Graph-neighbour stream contribution.
    pub graph: f64,
    /// Entity-match stream contribution.
    pub entity: f64,
    /// L0 abstract-embedding stream contribution (opt-in
    /// `[retrieval] abstract_vectors`; 0.0 when off or missed).
    #[serde(rename = "abstract", skip_serializing_if = "is_zero")]
    pub abstract_vector: f64,
    /// Observation-evidence stream contribution (`[retrieval]
    /// observation_stream`, on by default; 0.0 when disabled or missed).
    #[serde(skip_serializing_if = "is_zero")]
    pub observation: f64,
}

fn is_zero(v: &f64) -> bool {
    *v == 0.0
}

/// A query embedding plus the stored-vector identity it may be compared
/// against, borrowed for one [`ReaderPool::hybrid_search_scopes`] call.
#[derive(Debug, Clone, Copy)]
pub struct VectorQuery<'a> {
    /// The query embedding.
    pub vector: &'a [f32],
    /// Provider of the eligible stored vectors.
    pub provider: &'a str,
    /// Model identity of the eligible stored vectors.
    pub model: &'a str,
    /// Dimensionality of the eligible stored vectors.
    pub dim: u32,
}

/// Narrows a search to pages with the requested metadata and path prefix.
///
/// Every stream applies it in its own SQL, so each returns only pages the
/// filter keeps and a rare kind cannot be crowded out by other kinds. Entity
/// frequencies are still counted over every page, so the filter leaves an
/// entity's weight unchanged. Graph expansion seeds from the kept hits only.
#[derive(Debug, Clone, Copy, Default)]
pub struct PageFilter<'a> {
    /// Semantic kind to keep, compared ASCII case-insensitively; `None`
    /// keeps every kind.
    pub kind: Option<&'a str>,
    /// Memory tier to keep; `None` keeps every tier.
    pub tier: Option<&'a str>,
    /// Literal path prefix to keep; `None` keeps every path.
    pub path_prefix: Option<&'a str>,
    /// Exact frontmatter tag to keep, compared ASCII case-insensitively.
    /// Only string members of a `tags` array match.
    pub tag: Option<&'a str>,
}

impl PageFilter<'_> {
    /// Whether this filter narrows the candidate set.
    #[must_use]
    pub const fn is_active(&self) -> bool {
        self.kind.is_some()
            || self.tier.is_some()
            || self.path_prefix.is_some()
            || self.tag.is_some()
    }

    /// An ` AND …` predicate over the pages row `alias`, taking each bound
    /// value's placeholder from `placeholder`, and those values in order.
    fn sql(&self, alias: &str, mut placeholder: impl FnMut() -> String) -> (String, Vec<Value>) {
        let mut clause = String::new();
        let mut values = Vec::new();
        if let Some(kind) = self.kind {
            let kind_expr = page_kind_expr(
                &format!("{alias}.path"),
                &format!("{alias}.frontmatter_json"),
            );
            clause.push_str(&format!(
                " AND {kind_expr} = {} COLLATE NOCASE",
                placeholder()
            ));
            values.push(Value::Text(kind.to_owned()));
        }
        if let Some(tier) = self.tier {
            clause.push_str(&format!(" AND {alias}.tier = {}", placeholder()));
            values.push(Value::Text(tier.to_owned()));
        }
        if let Some(path_prefix) = self.path_prefix {
            let like_placeholder = placeholder();
            let length_placeholder = placeholder();
            let exact_placeholder = placeholder();
            clause.push_str(&format!(
                " AND {alias}.path LIKE {like_placeholder} ESCAPE '\\' \
                 AND substr({alias}.path, 1, length({length_placeholder})) = \
                     {exact_placeholder} COLLATE BINARY"
            ));
            values.push(Value::Text(format!("{}%", like_escape(path_prefix))));
            values.push(Value::Text(path_prefix.to_owned()));
            values.push(Value::Text(path_prefix.to_owned()));
        }
        if let Some(tag) = self.tag {
            clause.push_str(&format!(
                " AND json_type({alias}.frontmatter_json, '$.tags') = 'array' \
                 AND EXISTS (SELECT 1 FROM json_each({alias}.frontmatter_json, '$.tags') AS filter_tag \
                 WHERE filter_tag.type = 'text' \
                   AND filter_tag.value = {} COLLATE NOCASE)",
                placeholder()
            ));
            values.push(Value::Text(tag.to_owned()));
        }
        (clause, values)
    }
}

/// Placeholders `?first`, `?first+1`, … for [`PageFilter::sql`] in a
/// statement that numbers its parameters.
fn numbered_placeholders(first: usize) -> impl FnMut() -> String {
    let mut next = first;
    move || {
        next += 1;
        format!("?{}", next - 1)
    }
}

/// Placeholder for [`PageFilter::sql`] in a statement of anonymous `?`s.
fn anonymous_placeholder() -> String {
    "?".to_owned()
}

/// One [`ReaderPool::hybrid_search_scopes`] request.
#[derive(Debug, Clone, Copy)]
pub struct HybridSearch<'a> {
    /// Free-text query.
    pub query: &'a str,
    /// Query embedding; `None` skips the vector stream.
    pub vector: Option<VectorQuery<'a>>,
    /// Most hits returned.
    pub limit: usize,
    /// See [`ReaderPool::search_pages_for_project`]; `None` means now.
    pub expiry_cutoff_us: Option<i64>,
    /// Let superseded page versions into the candidate pool.
    pub include_superseded: bool,
    /// Attach per-hit [`SearchExplain`] and per-stream [`StreamTimings`].
    pub explain: bool,
    /// Who is asking, as the session timeline sees them: an observation
    /// excerpt is attached only from a session this filter admits.
    pub owner: &'a OwnerFilter,
    /// Keep only pages matching these metadata/path constraints; the default
    /// keeps all pages.
    pub filter: PageFilter<'a>,
}

/// What [`ReaderPool::hybrid_search_scopes_outcome`] found.
#[derive(Debug, Default)]
pub struct HybridSearchOutcome {
    /// The fused hits, as [`ReaderPool::hybrid_search_scopes`] returns them.
    pub hits: Vec<(PageHit, Option<SearchExplain>)>,
    /// Summed per-stream timings; `Some` only for an explained search.
    pub timings: Option<StreamTimings>,
    /// Whether page FTS, the entity stream or the observation stream found a
    /// page in any scope. When false, every hit came from the vector streams
    /// (which have no similarity floor) or their graph neighbours, so the
    /// compiled wiki holds nothing that matches the query's own terms.
    pub lexical_match: bool,
}

/// Per-query wall time of each retrieval stream, in milliseconds, for an
/// `explain=true` query. Measured only on the explained path, so a normal
/// query takes no clock readings for it. A `None` field is a stream that did
/// not run (no query vector, stream turned off, no reranker). Summed across
/// projects when one query searches several scopes.
#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize)]
pub struct StreamTimings {
    /// Page FTS5 candidate search.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub fts_ms: Option<f64>,
    /// Entity-match stream.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub entity_ms: Option<f64>,
    /// Stored-vector scans (the page vectors plus, when enabled, the abstract
    /// vectors). Embedding the query itself is not included.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub vector_ms: Option<f64>,
    /// Graph-neighbour expansion.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub graph_ms: Option<f64>,
    /// Observation-evidence stream (`[retrieval] observation_stream`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub observation_ms: Option<f64>,
    /// Post-fusion reranker call. Filled by the MCP layer, which owns the
    /// reranker; the store never sets it.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub rerank_ms: Option<f64>,
}

impl StreamTimings {
    /// Add `other` into `self`, field by field. A stream that ran in either
    /// counts as having run.
    pub fn accumulate(&mut self, other: &Self) {
        fn add(into: &mut Option<f64>, from: Option<f64>) {
            if let Some(ms) = from {
                *into = Some(into.unwrap_or(0.0) + ms);
            }
        }
        add(&mut self.fts_ms, other.fts_ms);
        add(&mut self.entity_ms, other.entity_ms);
        add(&mut self.vector_ms, other.vector_ms);
        add(&mut self.graph_ms, other.graph_ms);
        add(&mut self.observation_ms, other.observation_ms);
        add(&mut self.rerank_ms, other.rerank_ms);
    }
}

/// Milliseconds since `started`, or `None` when the clock was never read
/// (the non-explained path passes `None`).
fn elapsed_ms(started: Option<std::time::Instant>) -> Option<f64> {
    started.map(|t| t.elapsed().as_secs_f64() * 1000.0)
}

/// Score transparency for one `memory_query` hit: where the hit ranked
/// in each retrieval stream, the raw per-stream scores, and how the
/// RRF fusion combined them. All ranks are 1-based; a `None` rank
/// means the hit did not surface in that stream.
///
/// [`Default`] is "surfaced in no stream": every rank `None`, zero
/// contributions. Streams fill in their own fields as they contribute.
#[derive(Debug, Clone, Default, Serialize)]
pub struct SearchExplain {
    /// 1-based rank in the FTS5 stream.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub fts_rank: Option<usize>,
    /// Raw FTS5 (bm25-based) score — lower is better.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub fts_score: Option<f64>,
    /// 1-based rank in the vector stream.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub vector_rank: Option<usize>,
    /// Cosine similarity against the query embedding.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cosine: Option<f32>,
    /// 1-based rank in the L0 abstract-embedding stream (opt-in).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub abstract_rank: Option<usize>,
    /// Cosine similarity of the page's abstract embedding against the query.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub abstract_cosine: Option<f32>,
    /// 1-based rank in the graph-neighbour stream.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub graph_rank: Option<usize>,
    /// Which seed page and link direction pulled the hit in.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub graph_via: Option<GraphVia>,
    /// 1-based rank in the entity-match stream.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub entity_rank: Option<usize>,
    /// Raw inverse-frequency weight used to order the entity stream.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub entity_weight: Option<f64>,
    /// Entity names on this page that matched the query.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub matched_entities: Vec<String>,
    /// 1-based rank in the observation-evidence stream (`[retrieval]
    /// observation_stream`, on by default): where this session page's
    /// best-matching observation placed among the matching sessions.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub observation_rank: Option<usize>,
    /// The matching observations that voted for this session page, best
    /// first and bounded. Only the best one contributes to `fused`; the
    /// session counts once however many of its observations match.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub observation_ids: Vec<ObservationId>,
    /// Per-stream RRF contributions.
    pub rrf: RrfContributions,
    /// Total fused score (sum of the RRF contributions) — higher is
    /// better. The returned `rank` is its negation *after* the
    /// authority multiplier below, so `fused` alone does not reproduce
    /// the ordering.
    pub fused: f64,
    /// Bounded page-authority multiplier applied to the fused rank
    /// after RRF (canonical kind/tier/`pinned`/frontmatter tags).
    /// `None` when the page had no authority row to adjust with; `1.0`
    /// means it was considered and left alone.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub authority: Option<f64>,
    /// The routing decision for this query when `[retrieval] query_intent`
    /// is on: `"session_recall"` for queries the lexical router recognised.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub intent: Option<&'static str>,
    /// Multiplier the routing applied to this hit: the session-page
    /// authority lift expressed as a ratio over the un-routed factor.
    /// `1.0` = considered and left alone.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub intent_boost: Option<f64>,
    /// Relevance in `[0, 1]` assigned by the optional post-RRF
    /// reranker. `None` when no reranker is configured, when it
    /// degraded, or when the hit fell outside the bounded judged prefix.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub rerank_score: Option<f32>,
    /// Number of `page_evidence` rows citing this page version (P2,
    /// docs/design-hindsight-borrowings.md §3) — how many
    /// sessions/observations/feedback/reconsolidation passes produced or
    /// reaffirmed it. Populated only on the explained path
    /// ([`Reader::hybrid_search_explained`]), batch-fetched after fusion;
    /// `None` on the default (non-explained) path. Populated on every
    /// explained query and, additionally, whenever the belief-authority weight
    /// is on (it is an input to the factor then). Exposing the count is inert:
    /// the count itself never feeds `fused`/`authority`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub evidence_count: Option<u32>,
    /// Belief-strength confidence in `[0.0, `[`crate::belief::CONFIDENCE_CAP`]`]`
    /// derived from this page version's evidence (P2,
    /// docs/design-hindsight-borrowings.md §3): distinct supporting sessions,
    /// recency of the newest sighting, and live contradiction count. Populated
    /// alongside `evidence_count`. Informational unless
    /// `[retrieval] belief_authority_weight` is positive; see `belief_factor`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub confidence: Option<f64>,
    /// The belief contribution actually folded into `authority` for this hit:
    /// `belief_authority_weight * confidence`, or `0.0` when the confidence
    /// applied but was zero. `None` when the belief-authority weight is off
    /// (the default) or the hit was skipped (a superseded version — a
    /// supersession always wins, so stale evidence never boosts it). Inert
    /// exposure of `confidence`/`evidence_count` does not set this.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub belief_factor: Option<f64>,
}

/// One hit returned by [`ReaderPool::search_pages`].
#[derive(Debug, Clone, Serialize)]
pub struct PageHit {
    /// Stable identifier for this page version.
    pub id: PageId,
    /// Relative path within the wiki tree.
    pub path: PagePath,
    /// Page title.
    pub title: String,
    /// FTS5 snippet of the body around matched terms. Internally delimited;
    /// serialized as safe HTML with `<mark>` around genuine matches.
    #[serde(serialize_with = "serialize_highlighted_snippet")]
    pub snippet: String,
    /// Relevance rank after the bounded authority adjustment (lower is better).
    pub rank: f64,
    /// True when this hit is a superseded (non-latest) page version, surfaced
    /// only because the caller opted into `include_superseded`. False for the
    /// current version — the default. Skipped in JSON when false so default
    /// retrieval output is unchanged.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub superseded: bool,
    /// True only when this hit is standing pinned context prepended by the
    /// opt-in `memory_query(pin_first=true)` path (via
    /// [`ReaderPool::list_pinned_pages`]). Ordinary search hits leave it
    /// `false` — the store's FTS/entity/vector/graph retrieval does not read
    /// the `pinned` column into the hit — so it is skipped in JSON when false
    /// and default retrieval output is unchanged.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub pinned: bool,
}

/// Completed session selected for scheduled auto-improvement.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AutoImproveCandidateSession {
    /// Session id.
    pub session_id: SessionId,
    /// Session `ended_at` timestamp in Unix microseconds.
    pub ended_at: i64,
}

/// A scheduler claim that has spent every review attempt (#833).
///
/// The session is no longer a candidate, so this is the only place its state is
/// visible: without it a failed review removed a session from the queue with
/// nothing but a single `errors=1` in one tick's log to show for it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AutoImproveParkedClaim {
    /// Session whose scheduled review kept failing.
    pub session_id: SessionId,
    /// How many attempts were spent.
    pub attempts: u32,
    /// The last failure, verbatim, as the scheduler saw it.
    pub last_error: Option<String>,
    /// When the last attempt failed, in Unix microseconds.
    pub last_failed_at: Option<i64>,
}

/// Open session selected for manual finalization.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct OpenSession {
    /// Session id.
    pub session_id: SessionId,
    /// Captured session cwd, if available.
    pub cwd: Option<String>,
}

/// Latest substantive open session that can seed a bounded startup recovery
/// packet. Unlike a handoff, this is a read-only view: the source session stays
/// open because it may still belong to a live parallel agent.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct InterruptedSessionCandidate {
    /// Session whose persisted observations are the recovery source.
    pub session_id: SessionId,
    /// Harness that produced the source session.
    pub agent_kind: AgentKind,
    /// ISO-8601 timestamp of the most recent in-scope observation.
    pub last_activity_at: String,
    /// Captured session cwd, if available. Lets a client-side backfill
    /// locate the source session's own transcript file (its native
    /// harness's on-disk layout is typically keyed by cwd), separate from
    /// scope resolution — untrusted display/lookup data, never identity.
    pub cwd: Option<String>,
}

/// Public state and attempt count for the latest scoped consolidation job.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct SessionConsolidationSummary {
    /// Latest generation state, without provider diagnostics.
    pub state: String,
    /// Provider attempts spent on this generation.
    pub attempts: u32,
}

/// Server-wide state of the SessionEnd consolidation queue, for the health
/// panel. Counts and timestamps only: no session ids, scopes or provider
/// error text.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize)]
pub struct SessionConsolidationQueue {
    /// Jobs waiting for a worker (including ones backing off to retry).
    pub pending: u64,
    /// Jobs a worker holds right now.
    pub running: u64,
    /// Jobs that finished.
    pub completed: u64,
    /// Jobs that gave up after their attempts.
    pub failed: u64,
    /// Unix microseconds of the newest completed job, if any.
    pub last_completed_at_us: Option<i64>,
    /// Unix microseconds the oldest pending job was requested, if any.
    pub oldest_pending_requested_at_us: Option<i64>,
}

/// One consolidation job that gave up after its attempts, for the operator's
/// `status` (#1692).
///
/// Deliberately **not** part of [`SessionConsolidationQueue`]: that struct
/// feeds the web health panel, which is documented to carry counts only. This
/// one carries the session id (so it can be re-consolidated once the cause is
/// fixed) and the bounded error the worker recorded, and is served only on
/// `/admin/status`, which is root-only on a multi-user server.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct FailedConsolidationJob {
    /// Session whose consolidation gave up.
    pub session_id: String,
    /// Provider attempts spent on it.
    pub attempts: u32,
    /// Unix microseconds of the final failure.
    pub failed_at_us: i64,
    /// The worker's bounded error text, scrubbed by the caller before display.
    pub last_error: String,
}

/// One open session selected by [`ReaderPool::idle_open_sessions`] for the
/// server-side idle auto-end tick: its last activity
/// (`MAX(observations.created_at)`, falling back to `started_at`) is older
/// than the tick's cutoff, and it never received a `SessionEnd`.
#[derive(Debug, Clone)]
pub struct IdleOpenSession {
    /// Session id.
    pub session_id: SessionId,
    /// Owning workspace.
    pub workspace_id: WorkspaceId,
    /// Owning project.
    pub project_id: ProjectId,
    /// Harness that opened the session.
    pub agent_kind: AgentKind,
    /// Captured session cwd, if available.
    pub cwd: Option<String>,
    /// Operator owning the session (`IdentityKey::storage_key`), `None` when
    /// the session is shared/actorless. The tick attributes its page to this
    /// owner, not to the server process.
    pub actor_user: Option<String>,
    /// Session start, Unix microseconds.
    pub started_at: i64,
    /// `MAX(observations.created_at)`, or `started_at` when the session has
    /// no observations. The end preserves it in the audit detail
    /// (`last_activity_us`); `ended_at` is the tick's clock.
    pub last_activity_us: i64,
    /// Latest `sessions/<id>.md` version captured alongside the selection
    /// (same read, before any write). The tick's conditional page write takes
    /// it as its precondition, so it cannot supersede a page a real
    /// `SessionEnd` delivered after the selection.
    pub seen_page_id: Option<PageId>,
}

/// A session's latest captured work in one scope, as listed by
/// [`ReaderPool::recent_session_activity`]. Ordered by work, not by when the
/// session started or ended: a harness that resumes an old session, or one
/// cut off by a quota limit, never writes a fresh start or a clean end, so
/// only its observations show that it holds the project's newest work.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct SessionActivity {
    /// Session id.
    pub session_id: SessionId,
    /// `AgentKind` as stored (`claude-code`, `open-code`, ...).
    pub agent_kind: String,
    /// Captured session cwd, if available.
    pub cwd: Option<String>,
    /// ISO-8601 time of the session's newest prompt, tool, stop or
    /// compaction observation in the scope. Bare session starts and ends are
    /// not work and never count.
    pub last_activity_at: String,
    /// The same instant in Unix microseconds, for comparisons.
    #[serde(skip)]
    pub last_activity_us: i64,
    /// Whether the session ended at or after its last activity. `false`
    /// means it is still running elsewhere or was cut off (a quota limit, a
    /// crash, a closed terminal) without ending.
    pub ended: bool,
    /// Whether a handoff from this session, in any state, was written at or
    /// after its last activity. Harnesses that checkpoint every turn leave
    /// one per turn; work after the newest one is not covered by it.
    pub handed_off: bool,
}

/// One session as listed from a scope by [`ReaderPool::sessions_for_scope`]
/// and [`ReaderPool::session_summary_scoped`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct SessionSummary {
    /// Session id.
    pub session_id: SessionId,
    /// Captured session cwd, if available.
    pub cwd: Option<String>,
    /// `AgentKind` as stored (`claude-code`, `cursor`, ...).
    pub agent_kind: String,
    /// ISO-8601 session start timestamp.
    pub started_at: String,
    /// ISO-8601 session end timestamp; `None` while the session is open.
    pub ended_at: Option<String>,
    /// Observations of this session that landed in the queried scope. A
    /// session that crossed repositories mid-flight has more rows elsewhere.
    pub observation_count: u64,
    /// Operator the session belongs to, as stored on the `sessions` row.
    pub actor_user: Option<String>,
    /// Latest consolidation generation in the requested scope, if present.
    pub consolidation: Option<SessionConsolidationSummary>,
    /// Reported cumulative token usage, when the harness's hook could
    /// determine it at session end. `None` — not a zeroed
    /// [`SessionUsageView`] — for a session with no report at all (older
    /// client, unsupported harness, or an end that fired before this
    /// feature shipped).
    pub usage: Option<SessionUsageView>,
}

/// One measured response, with no prompt or tool text.
#[derive(Debug, Clone)]
pub struct TokenCallView {
    /// Native response id.
    pub call_id: String,
    /// Source session id.
    pub session_id: String,
    /// Source harness.
    pub agent: String,
    /// Reported model or an unavailable marker.
    pub model: String,
    /// Fresh input.
    pub input: u64,
    /// Output including reasoning.
    pub output: u64,
    /// Cache writes.
    pub cache_write: u64,
    /// Cache reads.
    pub cache_read: u64,
    /// First received timestamp.
    pub observed_at: String,
    /// Native turn coordinate, unknown for old reports.
    pub turn_id: Option<String>,
    /// Native provider response coordinate, when reported.
    pub response_id: Option<String>,
    /// Reported response time; otherwise the UI uses capture time explicitly.
    pub response_at: Option<String>,
    /// Bounded tool provenance, loaded in one batch for this result page.
    pub tools: Vec<ai_memory_core::TokenToolRef>,
}

/// Ordering applied to all matching measured responses before pagination.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub enum TokenCallOrder {
    /// Most tokens first, including cache.
    #[default]
    Largest,
    /// Latest reported response time first; capture time when unavailable.
    Recent,
}

/// Bounded, project/session-scoped response investigation query.
#[derive(Debug, Clone, Default)]
pub struct TokenCallQuery {
    /// Literal substring of response id, model or harness (up to 256 chars).
    pub search: String,
    /// Restrict to the same investigation signals shown in the dashboard.
    pub signals_only: bool,
    /// Stable ordering before the fifty-row page is selected.
    pub order: TokenCallOrder,
    /// Matching responses to skip.
    pub offset: usize,
    /// Exact reported model (including the unavailable marker).
    pub model: Option<String>,
    /// Exact harness identity.
    pub agent: Option<AgentKind>,
    /// Intersect this session with the caller's authorized scope.
    pub session_id: Option<SessionId>,
    /// Inclusive UTC lower bound, in microseconds.
    pub from_us: Option<i64>,
    /// Exclusive UTC upper bound, in microseconds.
    pub until_us: Option<i64>,
    /// Exact native turn identity.
    pub turn_id: Option<String>,
    /// Exact tool label, across all provenance relations.
    pub tool: Option<String>,
}

/// Usage coverage and one filtered page of measured responses.
#[derive(Debug, Clone, Default)]
pub struct TokenUsageReport {
    /// Up to fifty responses after filtering and ordering.
    pub calls: Vec<TokenCallView>,
    /// All distinct measured responses, not only the displayed fifty.
    pub call_count: u64,
    /// Responses matching the investigation query, before pagination.
    pub matching_calls: u64,
    /// Total tokens (including cache) across all matching responses.
    pub matching_tokens: u64,
    /// Fresh input across measured responses.
    pub input: u64,
    /// Output across measured responses.
    pub output: u64,
    /// Cache writes across measured responses.
    pub cache_write: u64,
    /// Cache reads across measured responses.
    pub cache_read: u64,
}

/// Cumulative token usage for one session (token-cost visibility), as
/// surfaced by [`ReaderPool::sessions_for_scope`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct SessionUsageView {
    /// Fresh (non-cached) input tokens.
    pub input_tokens: u64,
    /// Output tokens (including any reasoning/thinking breakdown).
    pub output_tokens: u64,
    /// Tokens written to a prompt cache.
    pub cache_write_tokens: u64,
    /// Tokens served from a prompt cache.
    pub cache_read_tokens: u64,
    /// Last-seen model name, when reported.
    pub model: Option<String>,
}

/// Aggregate MCP tool-call counts for one client, from
/// `client_activity` — the MCP-only complement to
/// [`AgentSessionCount`]: hook-less clients (VS Code Copilot, Claude
/// Desktop, scripts) never open sessions but still read and write
/// memory through tools.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct ClientActivity {
    /// Sanitized client name (`clientInfo.name`, actor overlay, or
    /// `unknown`).
    pub client: String,
    /// Read-shaped tool calls (query/read/recent/briefing/…).
    pub reads: u64,
    /// Write-shaped tool calls (write_page/feedback/consolidate/…).
    pub writes: u64,
}

/// How many sessions one agent CLI opened in a scope — the shape behind
/// "where is this project's memory actually coming from".
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct AgentSessionCount {
    /// `AgentKind` as stored (`claude-code`, `cursor`, …).
    pub agent: String,
    /// Sessions this agent opened in the window, ended or still open.
    pub sessions: u64,
    /// Sessions with multiple admitted capture namespaces in this scope.
    pub mixed_capture_sessions: u64,
}

/// How a `SessionEnd` event should treat its target session — see
/// [`ReaderPool::session_end_disposition`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SessionEndDisposition {
    /// The session is open in the resolved scope/agent: run the normal end
    /// path.
    Open,
    /// The session is missing or does not match the resolved scope/agent. Drop
    /// the event without attempting recovery against an unrelated session.
    DropInvalid,
    /// The matching session already ended with no observations beyond the
    /// persisted end generation. Converge any interrupted downstream effects,
    /// then drop the duplicate end.
    AlreadyEnded,
    /// Already ended, but the observation count exceeds the persisted end
    /// generation: the agent resumed the session under the same id — run the
    /// full end path again so the resumed work reaches the compiled page
    /// (issue #152).
    ReEndWithNewWork,
}

/// The latest version of a page's stored content, used as a DB-backed
/// fallback when the on-disk markdown read fails (index/disk skew). The
/// markdown file is the source of truth, but the store keeps a faithful copy
/// written in the same transaction, so serving it is safe.
#[derive(Debug, Clone)]
pub struct StoredPageBody {
    /// Page title as stored in the DB.
    pub title: String,
    /// Page body (markdown without frontmatter).
    pub body: String,
    /// Raw `frontmatter_json` TEXT column (parse at the call site).
    pub frontmatter_json: String,
    /// Memory tier stored on the latest page row.
    pub tier: String,
    /// Whether the latest page row is pinned.
    pub pinned: bool,
}

/// Most versions [`ReaderPool::page_versions`] returns in one call.
pub const PAGE_VERSIONS_MAX_LIMIT: usize = 200;

/// One stored version of a page path, listed by [`ReaderPool::page_versions`].
#[derive(Debug, Clone, Serialize)]
pub struct PageVersion {
    /// This version's id (`pages.id`).
    pub id: PageId,
    /// The version this one replaced, if it replaced one.
    pub supersedes: Option<PageId>,
    /// Whether this is the live version of the path.
    pub is_latest: bool,
    /// Title stored on this version.
    pub title: String,
    /// Memory tier stored on this version.
    pub tier: String,
    /// ISO-8601 instant this version was written.
    pub created_at: String,
    /// Length of this version's body in characters.
    pub body_chars: u64,
    /// The user who wrote this version, when the write was attributed.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub author: Option<PageAuthor>,
}

/// One page of a path's version history, newest first.
#[derive(Debug, Clone, Serialize)]
pub struct PageVersions {
    /// Every version stored at the path.
    pub total: u64,
    /// The requested slice of versions.
    pub versions: Vec<PageVersion>,
}

/// The stored content of one page version, read by
/// [`ReaderPool::page_version_body`].
#[derive(Debug, Clone)]
pub struct PageVersionBody {
    /// The version's id.
    pub id: PageId,
    /// The version this one replaced, if it replaced one.
    pub supersedes: Option<PageId>,
    /// Title stored on this version.
    pub title: String,
    /// Body stored on this version (markdown without frontmatter).
    pub body: String,
    /// Full frontmatter stored on this version.
    pub frontmatter: serde_json::Value,
    /// Memory tier stored on this version.
    pub tier: String,
    /// Whether this version was pinned.
    pub pinned: bool,
    /// ISO-8601 instant this version was written.
    pub created_at: String,
}

/// Search hit with workspace/project names, used by the web UI to avoid
/// per-hit metadata lookups after a global search.
#[derive(Debug, Clone, Serialize)]
pub struct PageHitWithMeta {
    /// Stable identifier for this page version. Not serialized, so the MCP
    /// `global_hits` and web shapes stay as they were; `GET /admin/search`
    /// copies it into its own response to keep the `id` field its global
    /// branch always returned.
    #[serde(skip)]
    pub id: PageId,
    /// Name of the workspace containing the page.
    pub workspace_name: String,
    /// Name of the project containing the page.
    pub project_name: String,
    /// Relative path within the wiki tree.
    pub path: PagePath,
    /// Page title.
    pub title: String,
    /// FTS5 snippet of the body around matched terms. Internally delimited;
    /// serialized as safe HTML with `<mark>` around genuine matches.
    #[serde(serialize_with = "serialize_highlighted_snippet")]
    pub snippet: String,
    /// Relevance rank after the bounded authority adjustment (lower is better).
    pub rank: f64,
}

/// One raw observation fallback hit returned when compiled wiki pages miss.
#[derive(Debug, Clone, Serialize)]
pub struct ObservationHit {
    /// Stable observation identifier.
    pub id: ObservationId,
    /// Owning session identifier.
    pub session_id: SessionId,
    /// Observation kind as stored on the lifecycle row.
    pub kind: String,
    /// Observation title.
    pub title: String,
    /// FTS5 snippet of the raw observation body around the matched terms.
    #[serde(serialize_with = "serialize_highlighted_snippet")]
    pub snippet: String,
    /// FTS5 rank score (lower is better).
    pub rank: f64,
    /// ISO-8601 creation timestamp.
    pub created_at: String,
}

/// One raw observation with its full stored body, as returned by
/// [`ReaderPool::session_observations_scoped`]. Bodies were sanitized and
/// bounded on the way in, so this is a read of what the store holds; callers
/// that need a smaller payload cap the body themselves.
#[derive(Debug, Clone, Serialize)]
pub struct ObservationRecord {
    /// Stable observation identifier.
    pub id: ObservationId,
    /// Owning session identifier.
    pub session_id: SessionId,
    /// Observation kind as stored on the lifecycle row.
    pub kind: String,
    /// Observation title.
    pub title: String,
    /// Full sanitized observation body.
    pub body: String,
    /// Importance in `1..=10`.
    pub importance: u8,
    /// ISO-8601 creation timestamp.
    pub created_at: String,
    /// Third-party extension namespace that supplied `source_event`, if any.
    pub extension: Option<String>,
    /// Source event name from an opt-in extension vocabulary, if any.
    pub source_event: Option<String>,
}

/// Sort direction for [`ObservationPage`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum ObservationOrder {
    /// Oldest first (capture order).
    #[default]
    Asc,
    /// Newest first.
    Desc,
}

/// Paging and filtering for [`ReaderPool::session_observations_scoped`].
/// The store applies `limit` and `offset` as given; callers clamp.
#[derive(Debug, Clone)]
pub struct ObservationPage {
    /// Maximum rows to return. Zero returns no rows but still counts.
    pub limit: usize,
    /// Rows to skip before the first returned one.
    pub offset: usize,
    /// Sort direction over `created_at` (with the id as tiebreak).
    pub order: ObservationOrder,
    /// Keep only these kinds. `None` or an empty list keeps every kind.
    pub kinds: Option<Vec<ObservationKind>>,
    /// Optional full-text query over title and body. Ignored when it
    /// normalizes to nothing searchable.
    pub query: Option<String>,
}

/// One page of a session's observations plus the counts a caller needs to
/// paginate and to notice that the session has rows outside the scope.
#[derive(Debug, Clone, Serialize)]
pub struct ObservationPageResult {
    /// The requested page, in the requested order.
    pub records: Vec<ObservationRecord>,
    /// Rows in scope matching the kind and query filters, across all pages.
    pub total: u64,
    /// Rows of the same session that landed in a different
    /// `(workspace, project)`, unfiltered. Non-zero means the session crossed
    /// repositories and this scope holds only part of it.
    pub elided_other_scope: u64,
}

/// Aggregate counts surfaced by [`ReaderPool::status_counts`] and consumed
/// by `ai-memory status`.
#[derive(Debug, Clone, Default, Serialize)]
pub struct StatusCounts {
    /// Pages with `is_latest = 1`. The briefing surfaces
    /// ([`ReaderPool::briefing`] and its scoped variants) additionally exclude
    /// TTL-expired pages, so there the count matches what their own page lists
    /// can contain.
    pub pages_latest: u64,
    /// All page versions including superseded ones.
    pub pages_all: u64,
    /// Total sessions ever recorded.
    pub sessions: u64,
    /// Total observations across all sessions.
    pub observations: u64,
    /// Total `page_evidence` rows in the project (P2,
    /// docs/design-hindsight-borrowings.md §3): the belief-strength substrate's
    /// footprint — how many session/observation/feedback/reconsolidation
    /// citations back this project's pages. `0` on a store that predates the
    /// evidence write path or has consolidated nothing yet.
    pub evidence_rows: u64,
}

/// The key two project names share when only their spelling differs
/// (#1645).
///
/// Compatibility-decomposes and lowercases first, then drops only non-spacing
/// marks. Punctuation remains significant: `api` and `api!` are different
/// project names, while `Renato`, `RENATO`, and `Rénato` share a key.
#[must_use]
pub fn project_name_fold_key(name: &str) -> String {
    use unicode_categories::UnicodeCategories as _;

    let decomposed = icu_normalizer::DecomposingNormalizer::new_nfkd().normalize(name);
    decomposed
        .chars()
        .filter(|c| !c.is_mark_nonspacing())
        .collect::<String>()
        .to_lowercase()
        .trim()
        .to_string()
}

fn project_name_case_key(name: &str) -> String {
    icu_normalizer::DecomposingNormalizer::new_nfd()
        .normalize(name)
        .to_lowercase()
        .trim()
        .to_string()
}

/// One likely cross-project contamination finding from
/// [`ReaderPool::audit_contamination`]. Advisory only — it flags STRUCTURAL
/// mislandings (an entity whose identity disagrees with the bucket it landed
/// in). Purely semantic contamination (a page whose topic belongs elsewhere
/// with no cwd/session anomaly) is not detectable structurally.
#[derive(Debug, Clone, Serialize)]
pub struct ContaminationFinding {
    /// Heuristic that fired: `session_wrong_bucket` (CHECK A).
    pub check: &'static str,
    /// Confidence — `high` for the structural check.
    pub confidence: &'static str,
    /// Entity kind: `session`.
    pub entity_kind: &'static str,
    /// Entity id (lowercase hex of the 16-byte UUID).
    pub entity_id: String,
    /// Workspace name the entity actually landed in.
    pub landed_workspace: String,
    /// Project name the entity actually landed in.
    pub landed_project: String,
    /// Project the evidence says it belongs to (the session's cwd
    /// prefix-resolution result for CHECK A).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub expected_project: Option<String>,
    /// Originating session cwd — the prefix-resolution evidence (CHECK A).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cwd: Option<String>,
    /// The other project(s) this name collides with, comma-separated
    /// (CHECK B). Names only: the fix is a marker or `merge-project`, and the
    /// reader needs both spellings.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub peer_projects: Option<String>,
    /// Page count of this project (CHECK B).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub pages: Option<u64>,
    /// Session count of this project (CHECK B).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sessions: Option<u64>,
    /// Whether the peer names differ by case, accent, or both (CHECK B).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub collision_kind: Option<&'static str>,
    /// Latest page/session/observation activity timestamp in microseconds
    /// since the Unix epoch (CHECK B).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub last_activity_us: Option<i64>,
}

/// Per-check counts for an [`ReaderPool::audit_contamination`] run.
#[derive(Debug, Clone, Default, Serialize)]
pub struct ContaminationSummary {
    /// Sessions whose cwd prefix-resolves to a different project (CHECK A).
    pub sessions_misbucketed: usize,
    /// Projects whose names collide with another project's in one workspace
    /// (CHECK B).
    pub project_name_collisions: usize,
}

/// Result of [`ReaderPool::audit_contamination`] — advisory, never mutates.
#[derive(Debug, Clone, Default, Serialize)]
pub struct ContaminationReport {
    /// Per-check counts.
    pub summary: ContaminationSummary,
    /// Individual findings.
    pub findings: Vec<ContaminationFinding>,
}

/// One `audit_log` row with names resolved through LEFT JOINs.
///
/// Workspace, project, page, and author are `Option` because the log has
/// no foreign keys (V05: append-only; orphan rows are expected).
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct AuditEvent {
    /// Auto-increment primary key; also the keyset pagination cursor.
    pub id: i64,
    /// Event time in microseconds since Unix epoch (V01 convention).
    pub at: i64,
    /// Writer-assigned op (`create_page`, `supersede_page`, `purge_project`, …).
    pub op: String,
    /// Workspace name, or `None` when the id no longer resolves.
    pub workspace: Option<String>,
    /// Project name, or `None` when the id no longer resolves.
    pub project: Option<String>,
    /// Page path, or `None` when the id no longer resolves.
    pub page_path: Option<String>,
    /// Username, or `None` for anonymous writes and deleted users.
    pub author_username: Option<String>,
    /// Schema column. The only writer stores the literal `{}`; not a payload.
    pub detail: String,
}

/// Filters for [`ReaderPool::list_audit_events`].
#[derive(Debug, Clone)]
pub struct AuditLogFilter {
    /// Restrict to this workspace **name**.
    pub workspace: Option<String>,
    /// Restrict to this project **name**.
    pub project: Option<String>,
    /// Restrict to this op string.
    pub op: Option<String>,
    /// Keyset cursor: return rows with `id` strictly less than this value.
    pub before_id: Option<i64>,
    /// Page size. Clamped to `1..=200`; [`Default`] is 50.
    pub limit: usize,
}

impl Default for AuditLogFilter {
    fn default() -> Self {
        Self {
            workspace: None,
            project: None,
            op: None,
            before_id: None,
            limit: 50,
        }
    }
}

/// Counts that must all be zero before `ai-memory reindex` rebuilds the
/// derived SQLite store from wiki files.
#[derive(Debug, Clone, Default, Serialize)]
pub struct ReindexTargetStatus {
    /// Workspace rows already present in SQLite.
    pub workspaces: u64,
    /// Project rows already present in SQLite.
    pub projects: u64,
    /// Page rows, including superseded versions.
    pub pages: u64,
    /// Link rows derived from latest page bodies.
    pub links: u64,
    /// Stored embedding rows derived from latest pages.
    pub page_embeddings: u64,
    /// Session rows. These are DB-only episodic state and are not rebuilt.
    pub sessions: u64,
    /// Observation rows. These are DB-only episodic state and are not rebuilt.
    pub observations: u64,
    /// Handoff rows. These are DB-only episodic state and are not rebuilt.
    pub handoffs: u64,
    /// User rows and token hashes. These are DB-only state and are not rebuilt.
    pub users: u64,
    /// Audit rows. These are DB-only state and are not rebuilt.
    pub audit_log: u64,
}

impl ReindexTargetStatus {
    /// True when the store has no user data or derived rows.
    #[must_use]
    pub fn is_clean(&self) -> bool {
        self.workspaces == 0
            && self.projects == 0
            && self.pages == 0
            && self.links == 0
            && self.page_embeddings == 0
            && self.sessions == 0
            && self.observations == 0
            && self.handoffs == 0
            && self.users == 0
            && self.audit_log == 0
    }

    /// Render a compact list of non-zero counters for operator errors.
    #[must_use]
    pub fn nonzero_summary(&self) -> String {
        let mut parts = Vec::new();
        macro_rules! push_nonzero {
            ($field:ident) => {
                if self.$field != 0 {
                    parts.push(format!("{}={}", stringify!($field), self.$field));
                }
            };
        }
        push_nonzero!(workspaces);
        push_nonzero!(projects);
        push_nonzero!(pages);
        push_nonzero!(links);
        push_nonzero!(page_embeddings);
        push_nonzero!(sessions);
        push_nonzero!(observations);
        push_nonzero!(handoffs);
        push_nonzero!(users);
        push_nonzero!(audit_log);
        parts.join(", ")
    }
}

/// Derived-index health counters surfaced by admin status.
#[derive(Debug, Clone, Default, Serialize)]
pub struct DerivedIndexStatus {
    /// All page rows in the source table. `pages_fts_rows` should match this.
    pub pages_rows: u64,
    /// Rows currently present in the page FTS5 index.
    pub pages_fts_rows: u64,
    /// All observation rows. `observations_fts_rows` should match this.
    pub observations_rows: u64,
    /// Rows currently present in the observation FTS5 index.
    pub observations_fts_rows: u64,
    /// Latest pages without an embedding row for the configured
    /// `(provider, model, dim)` triple, whose body is non-empty — i.e. the
    /// pages a backfill can actually act on. A vector stored under another
    /// triple is stale and does not cover the page. Without a configured
    /// embedder (the `None` query) this is "without any embedding row".
    pub latest_pages_missing_embeddings: u64,
    /// Latest pages without an embedding whose body is empty; no
    /// embedder can ever cover these (the backfill skips them by rule).
    pub latest_pages_unembeddable: u64,
    /// Latest pages whose last embed attempt failed or was skipped and which
    /// still have no embedding. These are the pages an operator can act on.
    pub embed_failures_unresolved: u64,
    /// Latest pages that recorded a failed or skipped embed at some point but
    /// have an embedding now. Kept because a global `embed --force` used to
    /// erase exactly this history, leaving a recurrence unattributable (#528).
    pub embed_failures_recovered: u64,
    /// Stored embedding rows, regardless of provider/model/dim.
    pub embedding_rows: u64,
    /// Stored embedding triples and row counts.
    pub embedding_triples: Vec<EmbeddingTripleCount>,
    /// Typed relation edges (`link_type != 'references'`) from latest
    /// pages, as `(relation, count)` — the 2.0 typed-edge surface.
    pub typed_links_from_latest_pages: Vec<(String, u64)>,
    /// Outgoing links whose source page is latest.
    pub links_from_latest_pages: u64,
    /// Latest-page outgoing links whose target path has not resolved yet.
    pub unresolved_links_from_latest_pages: u64,
    /// Latest-page outgoing links pointing at a non-latest target row.
    pub stale_links_from_latest_pages: u64,
}

/// Physical storage figures, so an operator can decide whether a `VACUUM` is
/// worth its exclusive lock instead of scheduling one blindly.
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct StorageStatus {
    /// SQLite page size in bytes.
    pub page_size: u64,
    /// Total pages in the database.
    pub page_count: u64,
    /// Pages on the freelist — allocated, holding no live data, reusable by
    /// SQLite without growing the file.
    pub freelist_count: u64,
    /// `page_count * page_size`. The database's own view of its size, which is
    /// what `VACUUM` acts on.
    pub database_bytes: u64,
    /// `freelist_count * page_size` — an *estimate* of what a `VACUUM` would
    /// return to the filesystem.
    ///
    /// An estimate in both directions: `VACUUM` also defragments, so it can
    /// release more than the freelist, and it rewrites page headers, so it can
    /// release slightly less. Treat it as the signal for "is this worth an
    /// exclusive lock", not as an exact figure.
    pub reclaimable_bytes: u64,
    /// Free space on the filesystem holding the database file, in bytes.
    /// `None` when it could not be read (e.g. an unsupported filesystem).
    ///
    /// The database's own size says nothing about how much headroom is left
    /// for it to keep growing — a store that is small can still be minutes
    /// away from a WAL that cannot extend because the *disk*, not the
    /// database, is full. This is that signal, reported alongside the
    /// database's own figures rather than gated on them.
    pub data_dir_free_bytes: Option<u64>,
}

impl StorageStatus {
    /// Reclaimable share of the file, 0.0–100.0. Zero when the database is
    /// empty rather than a division by zero.
    #[must_use]
    pub fn reclaimable_pct(&self) -> f64 {
        if self.database_bytes == 0 {
            return 0.0;
        }
        (self.reclaimable_bytes as f64 / self.database_bytes as f64) * 100.0
    }
}

/// Count of embedding rows sharing one `(provider, model, dim)` triple.
#[derive(Debug, Clone, Serialize)]
pub struct EmbeddingTripleCount {
    /// Embedding provider name.
    pub provider: String,
    /// Embedding model name.
    pub model: String,
    /// Vector dimension.
    pub dim: u32,
    /// Rows using this triple.
    pub count: u64,
}

/// Rolling activity counters over a fixed time window. Surfaced by
/// [`ReaderPool::briefing`] so the caller (or an LLM-driven `memory_explore`)
/// can calibrate verbosity against how busy the project's been.
#[derive(Debug, Clone, Default, Serialize)]
pub struct ActivityWindow {
    /// Window size in days (e.g. 7 or 30).
    pub days: u32,
    /// Sessions whose `created_at` falls in the window.
    pub sessions: u64,
    /// Observations whose `created_at` falls in the window.
    pub observations: u64,
    /// Pages whose `updated_at` falls in the window — counts only
    /// `is_latest = 1` pages whose TTL has not passed. Supersession of an old
    /// version into a new one counts as one update (the new row).
    pub pages_updated: u64,
}

/// Snapshot used by `memory_briefing` and the LLM-driven
/// `memory_explore`. Pure SQL aggregation; no LLM, no schema reads
/// outside the existing `pages` / `sessions` / `observations` /
/// `handoffs` tables.
#[derive(Debug, Clone, Default, Serialize)]
pub struct BriefingSnapshot {
    /// Lifetime totals — same shape `memory_status` returns today.
    pub counts: StatusCounts,
    /// Activity over the last 7 days.
    pub activity_7d: ActivityWindow,
    /// Activity over the last 30 days.
    pub activity_30d: ActivityWindow,
    /// Timestamp of the most recent observation (ISO-8601), or `null`
    /// if no observations exist. The `now - last_observation_at` gap
    /// is the signal `memory_explore` uses to scale its verbosity.
    pub last_observation_at: Option<String>,
    /// Number of open (un-accepted) handoffs.
    pub pending_handoff_count: u64,
    /// Number of pending cross-project messages in this project's inbox (V64).
    /// Surfaced so a resuming agent knows it has mail; popping stays a
    /// deliberate `memory_message_pop` call. Project-scoped briefings only.
    pub pending_message_count: u64,
    /// All pages currently under `_rules/` — small, surfaced verbatim
    /// because they're the highest-signal type of memory.
    pub rules: Vec<BriefingPage>,
    /// Small pinned pages under `_slots/` for active project context,
    /// preferences, current focus, and pending items.
    pub slots: Vec<BriefingPage>,
    /// Top-N most-recently-updated `is_latest = 1` pages.
    pub recent_pages: Vec<BriefingPage>,
    /// Distinct other projects whose pages link INTO this project (who
    /// depends on us). Project-scoped briefings only; `0` for
    /// workspace/global snapshots.
    pub cross_project_dependents: u64,
    /// Distinct other projects this project's pages link OUT to (what we
    /// depend on). Project-scoped briefings only; `0` otherwise.
    pub cross_project_dependencies: u64,
    /// The project's highest-standing `rule`/`decision` pages, ordered by
    /// evidence count then recency. Populated only when the caller opts
    /// in via `settled_first: true` on `memory_briefing` /
    /// `briefing_for_project(_with_slot_visibility)` (P4,
    /// docs/design-hindsight-borrowings.md §5); empty and omitted from
    /// JSON otherwise so the default briefing shape is unchanged.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub settled: Vec<SettledPage>,
    /// The project's pinned latest pages (`pinned = 1`), newest first and
    /// bounded — standing operator-curated context so SessionStart hot-context
    /// can show it before any search ("pin before search", 2.4 line). Distinct
    /// from `slots`, which is keyed by the `_slots/` path prefix rather than
    /// the `pinned` column. Empty and omitted from JSON when the project has no
    /// pinned pages, so a project without pins keeps the previous briefing
    /// shape byte-for-byte.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub pinned: Vec<BriefingPage>,
}

/// Trimmed page view for the briefing — path, title, kind, updated_at
/// timestamp. Body and snippets are intentionally omitted (the caller
/// can follow up with `memory_query` if they need detail).
#[derive(Debug, Clone, Serialize)]
pub struct BriefingPage {
    /// Relative wiki path.
    pub path: String,
    /// Page title (first H1 / frontmatter title).
    pub title: String,
    /// Semantic classification, derived from explicit frontmatter or the
    /// page's canonical path family.
    pub kind: String,
    /// ISO-8601 timestamp of the last update.
    pub updated_at: String,
}

/// One of a project's highest-standing `rule`/`decision` pages, surfaced
/// by [`ReaderPool::briefing_for_project_with_slot_visibility`] only when
/// the caller opts in via `settled_first: true` (P4,
/// docs/design-hindsight-borrowings.md §5) — a bounded list an agent can
/// boot from instead of re-deriving settled answers from scratch.
#[derive(Debug, Clone, Serialize)]
pub struct SettledPage {
    /// Relative wiki path.
    pub path: String,
    /// Page title (first H1 / frontmatter title).
    pub title: String,
    /// Semantic classification — always `rule` or `decision` here.
    pub kind: String,
    /// Number of `page_evidence` rows citing this page version (0 when
    /// none have accrued yet).
    pub evidence_count: u32,
}

/// One core page of the session-start project brief — body included,
/// because the brief is injected as agent context and the whole point is
/// sparing the agent a re-exploration round-trip. Returned by
/// [`ReaderPool::session_brief_pages`].
#[derive(Debug, Clone, Serialize)]
pub struct BriefPageBody {
    /// Relative wiki path.
    pub path: String,
    /// Page title (first H1 / frontmatter title).
    pub title: String,
    /// Full markdown body of the latest version. The hooks-side renderer
    /// applies the char budget; the store returns it whole.
    pub body: String,
    /// Whether the page is pinned (decay-immune, operator-curated).
    pub pinned: bool,
    /// ISO-8601 timestamp of the last update.
    pub updated_at: String,
    /// Parsed frontmatter, where the renderer finds the page's `abstract:`
    /// and `summary:`. `{}` if the stored JSON ever fails to parse, which
    /// leaves that page with body-only excerpts.
    pub frontmatter_json: serde_json::Value,
}

/// One row per (workspace, project) with aggregate stats.
/// Returned by [`ReaderPool::list_projects_with_stats`].
#[derive(Debug, Clone, Serialize)]
pub struct ProjectSummary {
    /// Id of the workspace, as the stable half of the scope coordinate. (#1208)
    pub workspace_id: String,
    /// Name of the workspace.
    pub workspace_name: String,
    /// Id of the project, as the stable coordinate an operator can hand to an
    /// id-targeted admin operation. Names are not stable -- a legacy twin row
    /// can shadow another project's `legacy_name` -- so this is what makes a
    /// `list-projects` row unambiguous. (#1208)
    pub project_id: String,
    /// Name of the project within the workspace.
    pub project_name: String,
    /// Number of unexpired `is_latest = 1` pages.
    pub page_count: u64,
    /// Number of recorded sessions, including sessions that remain open.
    pub session_count: u64,
    /// Number of sanitized observations recorded for this project.
    pub observation_count: u64,
    /// Sessions without a `SessionEnd` record. This can mean active work or
    /// an interruption, so the dashboard presents it as a signal, not an error.
    pub open_session_count: u64,
    /// ISO-8601 timestamp of the newest `updated_at`, or `None` when
    /// the project has no pages yet.
    pub last_updated: Option<String>,
    /// Most recent capture, session start, or page update in this project.
    pub last_activity: Option<String>,
}

/// Counts of the records a destructive project operation would discard
/// (#1713).
///
/// Used as the preflight a `move-project` refusal shows: the copy+purge merge
/// keeps the source's latest pages only, so the rest of this is what the
/// operator is about to delete.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize)]
pub struct ProjectRecordCounts {
    /// Unexpired latest pages.
    pub pages: u64,
    /// Sessions recorded in the project.
    pub sessions: u64,
    /// Observations captured for those sessions.
    pub observations: u64,
    /// Handoffs created or accepted in the project.
    pub handoffs: u64,
}

/// Pending inbox depth for one recipient project. Returned by
/// [`ReaderPool::pending_inbox_counts`]; projects with nothing pending have no
/// row.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct InboxCount {
    /// Name of the recipient workspace.
    pub workspace_name: String,
    /// Name of the recipient project.
    pub project_name: String,
    /// Number of `pending` messages addressed to it.
    pub pending: u64,
}

/// A pending inbox message with its sender named for display. Returned by
/// [`ReaderPool::list_inbox_with_senders`].
#[derive(Debug, Clone)]
pub struct InboxEntry {
    /// The message row.
    pub message: AgentMessage,
    /// `(workspace, project)` names of the sender, or `None` when the viewer
    /// may not read the sender's repository (or it no longer exists). A
    /// repository's name is itself what a restricted project hides.
    pub sender: Option<(String, String)>,
}

/// One workspace scope with the id + name needed to write its
/// self-describing `_meta.md` manifest. Returned by
/// [`ReaderPool::list_all_workspace_scopes`].
#[derive(Debug, Clone)]
pub struct WorkspaceScopeRow {
    /// Workspace id — matches the level-1 wiki directory name.
    pub workspace_id: WorkspaceId,
    /// Human-readable workspace name.
    pub workspace_name: String,
}

/// How a requested project coordinate relates to stored projects.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ProjectCoordinateStatus {
    /// The requested name is the project's current stored name.
    Exact,
    /// The requested name matched the canonical path-style compatibility key.
    CanonicalCompat,
    /// The requested name matched the v2 basename compatibility key.
    LegacyCompat,
    /// No workspace/project candidate exists.
    Missing,
    /// More than one project UUID matched the requested coordinate.
    Ambiguous,
}

impl std::fmt::Display for ProjectCoordinateStatus {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter.write_str(match self {
            Self::Exact => "exact",
            Self::CanonicalCompat => "canonical_compat",
            Self::LegacyCompat => "legacy_compat",
            Self::Missing => "missing",
            Self::Ambiguous => "ambiguous",
        })
    }
}

/// Why a coordinate cannot be safely promoted or adopted.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ProjectCoordinateCollisionReason {
    /// Different remote identities share one hostless path-style key.
    CrossForgeCollision,
    /// Different project UUIDs matched exact/canonical/legacy probes.
    MultipleProjects,
    /// The canonical target name is held by another project.
    CanonicalTargetOccupied,
    /// The requested exact name is held by a different identity-backed project.
    CrossIdentityOccupied,
    /// The exact-name holder has no repository identity and cannot be adopted diagnostically.
    UnclaimedIdentitylessProject,
}

impl std::fmt::Display for ProjectCoordinateCollisionReason {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter.write_str(match self {
            Self::CrossForgeCollision => "cross_forge_collision",
            Self::MultipleProjects => "multiple_projects",
            Self::CanonicalTargetOccupied => "canonical_target_occupied",
            Self::CrossIdentityOccupied => "cross_identity_occupied",
            Self::UnclaimedIdentitylessProject => "unclaimed_identityless_project",
        })
    }
}

/// Read-only diagnostic for one requested workspace/project coordinate.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ProjectCoordinateDiagnostic {
    /// Workspace requested by the caller.
    pub workspace: String,
    /// Project name requested by the caller.
    pub requested_name: String,
    /// Typed resolution status.
    pub status: ProjectCoordinateStatus,
    /// Existing project UUID when one candidate is preferred for context.
    /// An ambiguous status may prefer the supplied identity's project; this
    /// does not imply unique resolution or rename eligibility.
    pub project_id: Option<ProjectId>,
    /// Current name of the preferred contextual candidate, when present.
    /// Interpret this together with `status`, never as a successful resolution.
    pub current_name: Option<String>,
    /// Canonical path-style candidate when known.
    pub canonical_candidate: Option<String>,
    /// Legacy basename candidate when known.
    pub legacy_candidate: Option<String>,
    /// Safe identity source, never the identity or remote URL.
    pub identity_source: Option<String>,
    /// Naming style implied by the current/canonical relationship.
    pub identity_style: Option<String>,
    /// Whether an authorized write through this requested name could rename in place.
    pub rename_eligible: bool,
    /// Typed reason that safe promotion/adoption is unavailable.
    pub collision_reason: Option<ProjectCoordinateCollisionReason>,
    /// Candidate count after project-UUID deduplication.
    pub candidate_count: usize,
}

/// One `(workspace, project)` scope with the ids + repo_path needed to write
/// its self-describing `_meta.md` manifest. Returned by
/// [`ReaderPool::list_all_scopes`]; consumed by `Wiki::backfill_scope_manifests`.
#[derive(Debug, Clone)]
pub struct ScopeRow {
    /// Workspace id — matches the level-1 wiki directory name.
    pub workspace_id: WorkspaceId,
    /// Human-readable workspace name.
    pub workspace_name: String,
    /// Project id — matches the level-2 wiki directory name.
    pub project_id: ProjectId,
    /// Human-readable project name.
    pub project_name: String,
    /// Filesystem path the project's cwd-based routing resolves to, if any.
    pub repo_path: Option<String>,
    /// Stable hostful repository identity, when the project has one.
    pub identity: Option<String>,
    /// Source spelling for `identity`, when present.
    pub identity_source: Option<String>,
    /// Canonical path-style compatibility key derived from the identity.
    pub canonical_name: Option<String>,
    /// Legacy basename compatibility key derived from the identity.
    pub legacy_name: Option<String>,
}

/// One row per workspace with aggregate stats.
/// Returned by [`ReaderPool::list_workspaces_with_stats`].
#[derive(Debug, Clone, Serialize)]
pub struct WorkspaceSummary {
    /// Name of the workspace.
    pub workspace_name: String,
    /// Number of projects in this workspace.
    pub project_count: u64,
    /// Number of unexpired `is_latest = 1` pages across the workspace.
    pub page_count: u64,
    /// ISO-8601 timestamp of the newest `updated_at`, or `None` when
    /// the workspace has no pages yet.
    pub last_updated: Option<String>,
}

/// Page summary for tree-view rendering (no body).
/// Returned by [`ReaderPool::list_pages`].
#[derive(Debug, Clone, Serialize)]
pub struct PageSummary {
    /// Relative path within the wiki tree.
    pub path: String,
    /// Page title.
    pub title: String,
    /// Semantic kind: `fact` | `rule` | `decision` | `gotcha` | …
    pub kind: String,
    /// Memory tier: `working` | `episodic` | `semantic` | `procedural`.
    pub tier: String,
    /// ISO-8601 timestamp of last update.
    pub updated_at: String,
}

/// Page author surfaced alongside read responses (P1.7).
/// JOINed from the `users` table when `pages.author_id IS NOT NULL`;
/// `None` for anonymous + root writes (where attribution lives only in
/// the on-disk frontmatter `last_modified_by` block from P1.6).
///
/// Repeated here rather than reused from `ai_memory_core::User` because
/// the response shape intentionally omits internal fields (id,
/// created_at, last_seen_at, role) — only the human-facing
/// identity is part of the API contract.
#[derive(Debug, Clone, Serialize)]
pub struct PageAuthor {
    /// Stable username (the attribution key recorded on writes).
    pub username: String,
    /// Optional display name (`Alice Smith`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// Optional email surfaced alongside the username in UIs.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub email: Option<String>,
}

/// Full page metadata for the page-view template.
/// Returned by [`ReaderPool::page_meta`].
#[derive(Debug, Clone, Serialize)]
pub struct PageMeta {
    /// Id of this (latest) version: the token a conditional write or delete
    /// passes back to act only on the version it saw.
    pub id: PageId,
    /// Name of the workspace.
    pub workspace_name: String,
    /// Name of the project.
    pub project_name: String,
    /// UUID of the workspace — used to construct the per-project wiki path.
    pub workspace_id: WorkspaceId,
    /// UUID of the project — used to construct the per-project wiki path.
    pub project_id: ProjectId,
    /// Relative wiki path.
    pub path: String,
    /// Page title.
    pub title: String,
    /// Semantic kind.
    pub kind: String,
    /// Memory tier.
    pub tier: String,
    /// Whether the page is pinned (decay-immune).
    pub pinned: bool,
    /// ISO-8601 instant the oldest retained version of the page was written.
    pub created_at: String,
    /// ISO-8601 last-update timestamp.
    pub updated_at: String,
    /// Path of the page this one supersedes, if any.
    pub supersedes: Option<String>,
    /// Multi-user attribution (P1.7). `None` for pre-multi-user pages
    /// and for root / anonymous writes (where `pages.author_id IS
    /// NULL`); `Some` when JOIN resolves a `users` row.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub author: Option<PageAuthor>,
    /// ISO-8601 TTL instant from the frontmatter `expires_at:` key.
    /// Exact-path/id reads return expired pages (an explicit read is
    /// not search); callers annotate expiry via [`PageMeta::expired`].
    #[serde(skip_serializing_if = "Option::is_none")]
    pub expires_at: Option<String>,
    /// `true` when [`PageMeta::expires_at`] is in the past — the page
    /// is hidden from retrieval and awaiting the next forget sweep.
    #[serde(skip_serializing_if = "std::ops::Not::not")]
    pub expired: bool,
}

/// Soft cap on nodes in a project link graph. Pages with the fewest
/// same-project neighbours drop first when a project is larger, then the
/// oldest of those; the rest stay reachable from the page tree.
pub const PROJECT_LINK_GRAPH_MAX_NODES: usize = 120;

/// One latest page kept in a project link graph.
#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
pub struct LinkGraphNode {
    /// Relative wiki path.
    pub path: String,
    /// Page title.
    pub title: String,
    /// Number of resolved same-project neighbours (either direction).
    pub degree: u64,
}

/// One resolved same-project edge in a project link graph.
#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
pub struct LinkGraphEdge {
    /// Source page path.
    pub from_path: String,
    /// Target page path.
    pub to_path: String,
}

/// Latest unexpired pages in one project and the resolved wikilinks among
/// them. Powers `/web/w/{workspace}/{project}/graph` and
/// `GET /api/v1/workspaces/{workspace}/projects/{project}/graph`.
#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
pub struct LinkGraph {
    /// Pages kept after the degree-then-recency cap.
    pub nodes: Vec<LinkGraphNode>,
    /// Resolved same-project edges whose both ends are in `nodes`.
    pub edges: Vec<LinkGraphEdge>,
    /// `true` when the project has more live pages than
    /// [`PROJECT_LINK_GRAPH_MAX_NODES`].
    pub truncated: bool,
}

/// One resolved cross-project edge (a link whose endpoints live in
/// different projects). The `/api/v1/graph` endpoint returns these; the UI
/// builds nodes from the endpoints and can aggregate to a project graph.
#[derive(Debug, Clone, Serialize)]
pub struct CrossProjectEdge {
    /// Source page workspace.
    pub from_workspace: String,
    /// Source page project.
    pub from_project: String,
    /// Source page path.
    pub from_path: String,
    /// Target page workspace.
    pub to_workspace: String,
    /// Target page project.
    pub to_project: String,
    /// Target page path.
    pub to_path: String,
}

/// One typed `contradicts` edge between two latest pages, surfaced as a
/// lint finding (2.0 item 3): the declaration IS the signal — no LLM
/// needed to notice that two pages disagree once an author or the
/// consolidator said so.
#[derive(Debug, Clone, Serialize)]
pub struct ContradictionEdge {
    /// Wiki path of the page declaring the contradiction.
    pub from_path: String,
    /// Wiki path of the contradicted page (as declared; the target may
    /// be unresolved, in which case `resolved` is false).
    pub to_path: String,
    /// Whether the target currently resolves to a latest page.
    pub resolved: bool,
}

/// An unresolved cross-project link — a declared dependency on another
/// project's page that does not resolve. Surfaced by `memory_lint`.
#[derive(Debug, Clone, Serialize)]
pub struct DanglingCrossLink {
    /// Path of the page that authored the link (in the queried project).
    pub from_path: String,
    /// Target workspace name (`None` = the source page's own workspace).
    pub workspace: Option<String>,
    /// Target project name.
    pub project: String,
    /// Target page path within that project.
    pub path: String,
    /// Whether the named target project exists at all. `false` →
    /// likely a typo / wrong name; `true` → the page is missing or was
    /// renamed/deleted in an existing project (a broken dependency).
    pub project_exists: bool,
}

/// A page related to another through the link graph — used by the
/// page-view "references / referenced by" panel. Body is omitted; just
/// enough to render a clickable row.
#[derive(Debug, Clone, Serialize)]
pub struct RelatedPage {
    /// Relative wiki path of the related page.
    pub path: String,
    /// Title of the related page.
    pub title: String,
    /// Semantic kind of the related page.
    pub kind: String,
    /// Workspace the related page lives in. Lets a backlink from another
    /// project be labelled / navigated (the cross-project dependency signal).
    pub workspace: String,
    /// Project the related page lives in.
    pub project: String,
}

/// Resolved outgoing links and incoming back-links for one page.
/// Returned by [`ReaderPool::page_links`].
#[derive(Debug, Clone, Default, Serialize)]
pub struct PageLinks {
    /// Latest pages this page references (resolved outgoing links).
    pub links: Vec<RelatedPage>,
    /// Latest pages that reference this page (incoming back-links).
    pub backlinks: Vec<RelatedPage>,
}

/// The first few outgoing links and back-links of one page, with how many
/// of each the viewer may see in total. Returned by
/// [`ReaderPool::page_links_preview`].
#[derive(Debug, Clone, Default)]
pub struct PageLinksPreview {
    /// The first outgoing links, in [`PageLinks`] order.
    pub links: Vec<RelatedPage>,
    /// Visible outgoing links in total.
    pub links_total: usize,
    /// The first back-links, in [`PageLinks`] order.
    pub backlinks: Vec<RelatedPage>,
    /// Visible back-links in total.
    pub backlinks_total: usize,
}

/// Hard ceiling on how far [`ReaderPool::related_walk`] traverses the link
/// graph. A caller's requested depth is clamped into `1..=RELATED_WALK_MAX_DEPTH`
/// — a deeper walk is refused, not honoured, so one read cannot fan out across
/// an unbounded slice of the graph.
pub const RELATED_WALK_MAX_DEPTH: u8 = 3;

/// Hard ceiling on the total number of distinct related nodes a single
/// [`ReaderPool::related_walk`] returns. Bounds the response regardless of
/// depth so a dense hub page cannot blow up a read; the walk stops as soon as
/// this many nodes are collected.
pub const RELATED_WALK_MAX_NODES: usize = 50;

/// One node discovered by [`ReaderPool::related_walk`]: a [`RelatedPage`]
/// (flattened into the same fields as a single-hop link) plus how it was
/// reached — its hop distance from the seed and the direction of the edge that
/// first reached it.
#[derive(Debug, Clone, Serialize)]
pub struct RelatedNode {
    /// Stable id of the related page's latest version. Carried for access
    /// reinforcement (C1): `memory_read_page`'s related walk bumps the walked
    /// pages, not just the seed. `#[serde(skip)]` keeps the wire payload
    /// byte-identical to a plain `page_links` entry — the id is an internal
    /// handle, never part of the tool response.
    #[serde(skip)]
    pub id: PageId,
    /// Identity of the related page (path/title/kind/workspace/project),
    /// flattened so a node serializes exactly like a `page_links` entry with
    /// two extra fields.
    #[serde(flatten)]
    pub page: RelatedPage,
    /// Hop distance from the seed page (1 = a direct neighbour).
    pub depth: u8,
    /// Direction of the edge that first reached this node: `"link"` (the seed
    /// side links out to it) or `"backlink"` (it links back toward the seed).
    pub direction: &'static str,
}

/// One page flagged by a workspace health check, with enough identity to
/// render a clickable drill-down row across projects.
#[derive(Debug, Clone, Serialize)]
pub struct HealthPage {
    /// Workspace name.
    pub workspace: String,
    /// Project name within the workspace.
    pub project: String,
    /// Relative wiki path.
    pub path: String,
    /// Page title.
    pub title: String,
    /// Semantic kind.
    pub kind: String,
}

/// Drill-down lists backing the workspace "memory health" counters.
/// Each list is capped; the headline counts stay authoritative.
/// Returned by [`ReaderPool::health_detail_for_workspace`].
#[derive(Debug, Clone, Default, Serialize)]
pub struct HealthDetail {
    /// Episodic latest pages untouched for over 30 days.
    pub stale: Vec<HealthPage>,
    /// Latest pages sharing a title with at least one other page.
    pub duplicates: Vec<HealthPage>,
    /// Latest pages with no incoming or outgoing links.
    pub orphans: Vec<HealthPage>,
}

/// Cheap, cloneable read-only connection pool handle.
#[derive(Clone)]
pub struct ReaderPool {
    inner: Arc<Inner>,
    /// Opt-in post-fusion ranking signals (see [`RetrievalTuning`]). Lives
    /// on the handle, so clones taken after [`Self::set_retrieval_tuning`]
    /// share the operator's choice while the pool itself stays untouched.
    tuning: RetrievalTuning,
    /// Operator-configured FTS stopword list (issue #953, `[search.fts]`).
    /// Lives on the handle for the same reason `tuning` does: clones taken
    /// after [`Self::set_fts_stopwords`] share the operator's choice.
    /// Cheap to clone (`FtsStopwords` is `Arc`-backed).
    fts_stopwords: FtsStopwords,
}

struct Inner {
    db_path: PathBuf,
    pool: Mutex<Pool>,
    in_flight: std::sync::Arc<tokio::sync::Semaphore>,
    soft_cap: usize,
}

/// The idle connections and whether the pool still hands out new ones. One
/// lock covers both, so a checkout or a return cannot interleave with
/// [`ReaderPool::close`] between reading the flag and touching the idle list.
struct Pool {
    idle: Vec<Connection>,
    closed: bool,
}

/// Metadata for ordering answer evidence that retrieval has already authorized.
/// Contains no page body and does not authorize access to the identified page.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AnswerEvidenceMeta {
    /// Workspace owning the retrieved page.
    pub workspace_id: WorkspaceId,
    /// Project owning the retrieved page.
    pub project_id: ProjectId,
    /// Stored page title.
    pub title: String,
    /// Evidence time in microseconds since the Unix epoch: the same-scope
    /// session start for canonical session pages, otherwise page modification.
    pub updated_at: i64,
    /// Previous version identifier, without fetching that version's metadata.
    pub supersedes: Option<PageId>,
}

impl ReaderPool {
    /// Fetch metadata only for page IDs already admitted by authorized retrieval.
    ///
    /// This internal data helper is not an authorization boundary: callers must
    /// pass only their admitted hits. One batched query returns at most the
    /// requested IDs, without reading bodies or following supersession links.
    /// Empty input does not open a connection. At most 300 IDs are accepted.
    ///
    /// # Errors
    /// Rejects oversized input and propagates SQL, ID decoding and pool errors.
    pub async fn answer_evidence_metadata(
        &self,
        ids: Vec<PageId>,
    ) -> StoreResult<std::collections::HashMap<PageId, AnswerEvidenceMeta>> {
        if ids.len() > 300 {
            return Err(StoreError::InvalidState(
                "answer evidence metadata accepts at most 300 page IDs".into(),
            ));
        }
        if ids.is_empty() {
            return Ok(std::collections::HashMap::new());
        }
        self.with_conn(move |conn| {
            let placeholders = vec!["?"; ids.len()].join(",");
            let mut stmt = conn.prepare(&format!(
                "SELECT p.id, p.workspace_id, p.project_id, p.title, \
                        COALESCE(s.started_at, p.updated_at), p.supersedes \
                 FROM pages p LEFT JOIN sessions s \
                   ON s.id = unhex(replace(substr(p.path, 10, 36), '-', '')) \
                  AND s.workspace_id = p.workspace_id AND s.project_id = p.project_id \
                  AND p.path = 'sessions/' || substr(lower(hex(s.id)), 1, 8) || '-' || \
                      substr(lower(hex(s.id)), 9, 4) || '-' || \
                      substr(lower(hex(s.id)), 13, 4) || '-' || \
                      substr(lower(hex(s.id)), 17, 4) || '-' || \
                      substr(lower(hex(s.id)), 21, 12) || '.md' \
                 WHERE p.id IN ({placeholders})"
            ))?;
            let bound: Vec<Value> = ids
                .iter()
                .map(|id| Value::Blob(id.as_bytes().to_vec()))
                .collect();
            let rows = stmt.query_map(params_from_iter(bound.iter()), |row| {
                Ok((
                    row.get::<_, Vec<u8>>(0)?,
                    row.get::<_, Vec<u8>>(1)?,
                    row.get::<_, Vec<u8>>(2)?,
                    row.get::<_, String>(3)?,
                    row.get::<_, i64>(4)?,
                    row.get::<_, Option<Vec<u8>>>(5)?,
                ))
            })?;
            let mut metadata = std::collections::HashMap::new();
            for row in rows {
                let (id, workspace, project, title, updated_at, supersedes) = row?;
                metadata.insert(
                    PageId::from_slice(&id)?,
                    AnswerEvidenceMeta {
                        workspace_id: WorkspaceId::from_slice(&workspace)?,
                        project_id: ProjectId::from_slice(&project)?,
                        title,
                        updated_at,
                        supersedes: supersedes.as_deref().map(PageId::from_slice).transpose()?,
                    },
                );
            }
            Ok(metadata)
        })
        .await
    }

    /// Initialise the pool. Connections are opened lazily on first use.
    ///
    /// # Errors
    /// Currently infallible, but reserved so we can pre-open connections
    /// in a later milestone.
    pub fn new(db_path: &Path, soft_cap: usize) -> StoreResult<Self> {
        Ok(Self {
            inner: Arc::new(Inner {
                db_path: db_path.to_path_buf(),
                pool: Mutex::new(Pool {
                    idle: Vec::with_capacity(soft_cap.max(1)),
                    closed: false,
                }),
                in_flight: std::sync::Arc::new(tokio::sync::Semaphore::new(soft_cap.max(1))),
                soft_cap: soft_cap.max(1),
            }),
            tuning: RetrievalTuning::default(),
            fts_stopwords: FtsStopwords::default(),
        })
    }

    /// Close the pool for shutdown: drop every idle connection, and make every
    /// later read fail with [`StoreError::ReaderClosed`] instead of opening a
    /// new one. Idempotent.
    ///
    /// A read already running is not interrupted or waited for: it finishes
    /// on its own connection, and that connection is dropped when it is
    /// returned rather than pooled again. Such a read can hold a snapshot that
    /// keeps the writer's final checkpoint from truncating the WAL; the
    /// checkpoint then logs the blocked attempt and the WAL is replayed on the
    /// next start, as after any other unclean stop.
    pub fn close(&self) {
        let mut pool = self.inner.pool.lock();
        pool.closed = true;
        pool.idle.clear();
        self.inner.in_flight.close();
    }

    /// Configure the opt-in ranking signals used by [`Self::hybrid_search`].
    /// Only handles cloned from this one afterwards observe the change.
    pub fn set_retrieval_tuning(&mut self, tuning: RetrievalTuning) {
        self.tuning = tuning;
    }

    /// Configure the FTS stopword list applied by every search path that
    /// prepares a bare natural-language query (see [`prepare_fts5_query`]).
    /// Only handles cloned from this one afterwards observe the change.
    /// Defaults to [`FtsStopwords::default`] (the built-in English list).
    pub fn set_fts_stopwords(&mut self, stopwords: FtsStopwords) {
        self.fts_stopwords = stopwords;
    }

    /// The ranking signals this handle applies (default: none).
    #[must_use]
    pub fn retrieval_tuning(&self) -> RetrievalTuning {
        self.tuning
    }

    /// The grant this user holds on this repository, if any (at most one).
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn grants_for(
        &self,
        user_id: ai_memory_core::UserId,
        repository_id: ProjectId,
    ) -> StoreResult<Vec<crate::ProjectGrant>> {
        self.with_conn(move |conn| crate::grants::grants_for(conn, user_id, repository_id))
            .await
    }

    /// Page authors who would be refused if this repository were restricted;
    /// see [`crate::grants::authors_without_grant`].
    ///
    /// # Errors
    /// Propagates store failures.
    pub async fn authors_without_grant(
        &self,
        repository_id: ProjectId,
    ) -> StoreResult<Vec<String>> {
        self.with_conn(move |conn| crate::grants::authors_without_grant(conn, repository_id))
            .await
    }

    /// Grants matching `filter`, resolved to names for display.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn list_grants(
        &self,
        filter: crate::grants::GrantFilter,
    ) -> StoreResult<Vec<crate::grants::GrantListing>> {
        self.with_conn(move |conn| crate::grants::list_grants(conn, filter))
            .await
    }

    /// Run a synchronous closure against a pooled read-only connection.
    ///
    /// The closure runs on the tokio blocking pool so it never starves the
    /// async runtime. At most `soft_cap` closures and their connections run at
    /// once; later calls wait asynchronously for a permit instead of adding
    /// blocking threads. Idle connections are kept up to the same cap.
    ///
    /// # Errors
    /// Returns [`StoreError::PoolPanic`] if the blocking task panics; any
    /// error returned by the closure is propagated unchanged.
    pub async fn with_conn<F, T>(&self, f: F) -> StoreResult<T>
    where
        F: FnOnce(&Connection) -> StoreResult<T> + Send + 'static,
        T: Send + 'static,
    {
        let inner = self.inner.clone();
        let permit = inner
            .in_flight
            .clone()
            .acquire_owned()
            .await
            .map_err(|_| StoreError::ReaderClosed)?;
        tokio::task::spawn_blocking(move || {
            let _permit = permit;
            let conn = checkout(&inner)?;
            let result = f(&conn);
            checkin(&inner, conn);
            result
        })
        .await
        .map_err(|e| StoreError::PoolPanic(e.to_string()))?
    }

    /// The repository a managed run belongs to, or `None` when no such run
    /// exists.
    ///
    /// The workstream routes take a run id in the URL rather than a
    /// workspace/project pair, so they never pass through scope resolution and
    /// the grant check with it. This is what they authorize against.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn managed_run_scope(
        &self,
        run_id: ai_memory_core::ManagedRunId,
    ) -> StoreResult<Option<(WorkspaceId, ProjectId)>> {
        self.with_conn(move |conn| {
            scope_row(
                conn,
                "SELECT w.workspace_id, w.project_id FROM managed_runs r \
                 JOIN workstreams w ON w.id = r.workstream_id WHERE r.id = ?1",
                run_id.as_bytes(),
            )
        })
        .await
    }

    /// Validated scope of an explicitly ID-selected run, if it opted in.
    /// Legacy runs return `None`; invalid pinned boundaries fail closed.
    pub async fn managed_run_pinned_scope(
        &self,
        identity: crate::ManagedRunHookIdentity,
    ) -> StoreResult<Option<(WorkspaceId, ProjectId)>> {
        self.with_conn(move |conn| crate::workstream::pinned_hook_scope(conn, &identity))
            .await
    }

    /// The repository a workstream belongs to, or `None` when it does not
    /// exist. See [`Self::managed_run_scope`] for why the routes need it.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn workstream_scope(
        &self,
        workstream_id: ai_memory_core::WorkstreamId,
    ) -> StoreResult<Option<(WorkspaceId, ProjectId)>> {
        self.with_conn(move |conn| {
            scope_row(
                conn,
                "SELECT workspace_id, project_id FROM workstreams WHERE id = ?1",
                workstream_id.as_bytes(),
            )
        })
        .await
    }

    /// Check a managed run's owner and current Write access in one read
    /// snapshot, before any mutation of the run.
    ///
    /// # Errors
    /// Refuses a foreign owner, insufficient access, absent run or invalid scope;
    /// SQL failures propagate without degrading authorization to open.
    pub async fn authorize_managed_run(
        &self,
        run_id: ManagedRunId,
        authority: crate::ManagedRunAuthority,
    ) -> StoreResult<()> {
        self.with_conn(move |conn| {
            let tx = conn.unchecked_transaction()?;
            crate::workstream::authorize_run_mutation(&tx, run_id, &authority)
        })
        .await
    }

    /// Return the current state of one `ai-memory run` invocation.
    pub async fn managed_run_status(
        &self,
        run_id: ManagedRunId,
    ) -> StoreResult<Option<StoredManagedRunStatus>> {
        self.with_conn(move |conn| crate::workstream::run_status(conn, run_id))
            .await
    }

    /// Return the unseen portable range assigned to a managed SessionStart.
    pub async fn managed_run_context(
        &self,
        run_id: ManagedRunId,
        max_events: usize,
    ) -> StoreResult<Option<ManagedRunContext>> {
        self.with_conn(move |conn| crate::workstream::run_context(conn, run_id, max_events))
            .await
    }

    /// Search visible events in one managed workstream, or return its newest
    /// events when `query` is empty.
    pub async fn search_workstream_events(
        &self,
        workstream_id: WorkstreamId,
        query: String,
        limit: usize,
        sanitizer: ai_memory_core::Sanitizer,
    ) -> StoreResult<Vec<WorkstreamEvent>> {
        let stopwords = self.fts_stopwords.clone();
        self.with_conn(move |conn| {
            crate::workstream::search_events(
                conn,
                workstream_id,
                &query,
                limit,
                &stopwords,
                &sanitizer,
            )
        })
        .await
    }

    /// List recent managed workstreams for one exact repository/worktree.
    pub async fn recent_workstreams(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        repo_fingerprint: String,
        worktree_fingerprint: String,
        limit: usize,
    ) -> StoreResult<Vec<StoredWorkstreamSummary>> {
        self.recent_workstreams_page(
            workspace_id,
            project_id,
            repo_fingerprint,
            worktree_fingerprint,
            limit,
            0,
        )
        .await
    }

    /// List one bounded page for an exact repository/worktree, preserving the
    /// current-first order and every linked harness on each returned row.
    pub async fn recent_workstreams_page(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        repo_fingerprint: String,
        worktree_fingerprint: String,
        limit: usize,
        offset: usize,
    ) -> StoreResult<Vec<StoredWorkstreamSummary>> {
        self.with_conn(move |conn| {
            crate::workstream::list_recent(
                conn,
                workspace_id,
                project_id,
                &repo_fingerprint,
                &worktree_fingerprint,
                limit,
                offset,
            )
        })
        .await
    }

    /// Return one bounded page of cross-scope managed-workstream lifecycle
    /// summaries for an already-authorized root/operator surface.
    ///
    /// This reader performs no authorization by itself; unlike
    /// [`Self::recent_workstreams`], it intentionally aggregates checkouts and
    /// projects. Callers must enforce `Capability::Admin` before invoking it.
    pub async fn operational_workstreams(
        &self,
        limit: usize,
        offset: usize,
    ) -> StoreResult<Vec<OperationalWorkstreamSummary>> {
        let now_us = jiff::Timestamp::now().as_microsecond();
        self.with_conn(move |conn| crate::workstream::list_operational(conn, limit, offset, now_us))
            .await
    }

    /// Run a full-text search against the FTS5 index, apply the bounded page
    /// authority adjustment, and return the top `is_latest = 1` matches.
    ///
    /// `viewer` restricts the hits to repositories that user may read — see
    /// [`readable_repository_filter`]. `None` searches every repository.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn search_pages(
        &self,
        query: String,
        limit: usize,
        viewer: Option<UserId>,
    ) -> StoreResult<Vec<PageHit>> {
        let fts_query = normalize_fts_query(&query, &self.fts_stopwords);
        let cjk_query = prepare_cjk_fts5_query(&query);
        if fts_query.is_empty() || limit == 0 {
            return Ok(Vec::new());
        }
        self.with_conn(move |conn| {
            let kind_expr = page_kind_expr("pages.path", "pages.frontmatter_json");
            let (visible, visible_params) =
                readable_repository_filter("pages.project_id", viewer, 4);
            let sql = format!(
                "SELECT pages.id, pages.path, pages.title, \
                        snippet(pages_fts, 1, char(30), char(31), '…', 24) AS snip, \
                        pages_fts.rank, pages.tier, pages.pinned, \
                        pages.frontmatter_json, {kind_expr} AS kind \
                 FROM pages_fts \
                 JOIN pages ON pages.rowid = pages_fts.rowid \
                 WHERE pages_fts MATCH ?1 AND pages.is_latest = 1{not_expired}{visible} \
                 ORDER BY pages_fts.rank \
                 LIMIT ?2",
                not_expired = not_expired("pages", "?3"),
            );
            let mut stmt = conn.prepare(&sql)?;
            #[allow(clippy::cast_possible_wrap)]
            let mut bound = vec![
                Value::Text(fts_query),
                Value::Integer(authority_candidate_limit(limit) as i64),
                Value::Integer(now_us()),
            ];
            bound.extend(visible_params.iter().cloned());
            let rows = stmt.query_map(params_from_iter(bound.iter()), |row| {
                let id_bytes: Vec<u8> = row.get(0)?;
                let path: String = row.get(1)?;
                let title: String = row.get(2)?;
                let snippet: String = row.get(3)?;
                let rank: f64 = row.get(4)?;
                let tier: String = row.get(5)?;
                let pinned = row.get::<_, i64>(6)? != 0;
                let frontmatter_json: String = row.get(7)?;
                let kind: String = row.get(8)?;
                Ok((
                    id_bytes,
                    path,
                    title,
                    snippet,
                    rank,
                    tier,
                    pinned,
                    frontmatter_json,
                    kind,
                ))
            })?;

            let mut candidates = Vec::new();
            for row in rows {
                let (id_bytes, path, title, snippet, rank, tier, pinned, frontmatter_json, kind) =
                    row?;
                let authority =
                    PageAuthority::from_stored(&path, &kind, &tier, pinned, &frontmatter_json);
                candidates.push((
                    PageHit {
                        id: PageId::from_slice(&id_bytes)?,
                        path: PagePath::new(path)?,
                        title,
                        snippet,
                        rank,
                        superseded: false,
                        pinned: false,
                    },
                    authority,
                ));
            }
            let mut cjk_candidates = Vec::new();
            if let Some(cjk_query) = cjk_query {
                let descriptor = page_descriptor_expr("pages.body", "pages.frontmatter_json");
                let sql = format!(
                    "SELECT pages.id, pages.path, pages.title, {descriptor}, \
                            pages_cjk_fts.rank, pages.tier, pages.pinned, \
                            pages.frontmatter_json, {kind_expr} AS kind \
                     FROM pages_cjk_fts \
                     JOIN pages ON pages.rowid = pages_cjk_fts.rowid \
                     WHERE pages_cjk_fts MATCH ?1 AND pages.is_latest = 1{not_expired}{visible} \
                     ORDER BY pages_cjk_fts.rank LIMIT ?2",
                    not_expired = not_expired("pages", "?3"),
                );
                let mut stmt = conn.prepare(&sql)?;
                #[allow(clippy::cast_possible_wrap)]
                let mut bound = vec![
                    Value::Text(cjk_query),
                    Value::Integer(authority_candidate_limit(limit) as i64),
                    Value::Integer(now_us()),
                ];
                bound.extend(visible_params);
                let rows = stmt.query_map(params_from_iter(bound.iter()), |row| {
                    Ok((
                        row.get::<_, Vec<u8>>(0)?,
                        row.get::<_, String>(1)?,
                        row.get::<_, String>(2)?,
                        row.get::<_, String>(3)?,
                        row.get::<_, f64>(4)?,
                        row.get::<_, String>(5)?,
                        row.get::<_, i64>(6)? != 0,
                        row.get::<_, String>(7)?,
                        row.get::<_, String>(8)?,
                    ))
                })?;
                for row in rows {
                    let (id, path, title, descriptor, rank, tier, pinned, frontmatter, kind) = row?;
                    let authority =
                        PageAuthority::from_stored(&path, &kind, &tier, pinned, &frontmatter);
                    cjk_candidates.push((
                        PageHit {
                            id: PageId::from_slice(&id)?,
                            path: PagePath::new(path)?,
                            snippet: page_descriptor(&descriptor, &title),
                            title,
                            rank,
                            superseded: false,
                            pinned: false,
                        },
                        authority,
                    ));
                }
            }
            Ok(rerank_page_hits(
                fuse_page_candidate_streams(
                    candidates,
                    cjk_candidates,
                    authority_candidate_limit(limit),
                ),
                limit,
            ))
        })
        .await
    }

    /// Run a global authority-adjusted full-text search and include
    /// workspace/project names in each row. This keeps the web search route
    /// to one SQLite query instead of one search query plus a metadata lookup
    /// per hit.
    ///
    /// `viewer` restricts the hits to repositories that user may read — see
    /// [`readable_repository_filter`]. `None` searches every repository.
    /// `filter` keeps only pages matching its metadata/path constraints,
    /// before the cut to `limit`.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn search_pages_with_meta(
        &self,
        query: String,
        limit: usize,
        expiry_cutoff_us: Option<i64>,
        viewer: Option<UserId>,
        filter: PageFilter<'_>,
    ) -> StoreResult<Vec<PageHitWithMeta>> {
        let fts_query = normalize_fts_query(&query, &self.fts_stopwords);
        let cjk_query = prepare_cjk_fts5_query(&query);
        if fts_query.is_empty() || limit == 0 {
            return Ok(Vec::new());
        }
        let cutoff = expiry_cutoff_us.unwrap_or_else(now_us);
        let (visible, visible_params) = readable_repository_filter("pages.project_id", viewer, 4);
        let (kept, kept_params) =
            filter.sql("pages", numbered_placeholders(4 + visible_params.len()));
        self.with_conn(move |conn| {
            let kind_expr = page_kind_expr("pages.path", "pages.frontmatter_json");
            let sql = format!(
                "SELECT workspaces.name, projects.name, pages.path, pages.title, \
                        snippet(pages_fts, 1, char(30), char(31), '…', 24) AS snip, \
                        pages_fts.rank, pages.tier, pages.pinned, \
                        pages.frontmatter_json, {kind_expr} AS kind, pages.id \
                 FROM pages_fts \
                 JOIN pages ON pages.rowid = pages_fts.rowid \
                 JOIN projects ON projects.id = pages.project_id \
                 JOIN workspaces ON workspaces.id = pages.workspace_id \
                 WHERE pages_fts MATCH ?1 AND pages.is_latest = 1{not_expired}{visible}{kept} \
                 ORDER BY pages_fts.rank \
                 LIMIT ?2",
                not_expired = not_expired("pages", "?3"),
            );
            let mut stmt = conn.prepare(&sql)?;
            #[allow(clippy::cast_possible_wrap)]
            let mut bound = vec![
                Value::Text(fts_query),
                Value::Integer(authority_candidate_limit(limit) as i64),
                Value::Integer(cutoff),
            ];
            bound.extend(visible_params.iter().cloned());
            bound.extend(kept_params.iter().cloned());
            let rows = stmt.query_map(params_from_iter(bound.iter()), |row| {
                let workspace_name: String = row.get(0)?;
                let project_name: String = row.get(1)?;
                let path: String = row.get(2)?;
                let title: String = row.get(3)?;
                let snippet: String = row.get(4)?;
                let rank: f64 = row.get(5)?;
                let tier: String = row.get(6)?;
                let pinned = row.get::<_, i64>(7)? != 0;
                let frontmatter_json: String = row.get(8)?;
                let kind: String = row.get(9)?;
                let id_bytes: Vec<u8> = row.get(10)?;
                Ok((
                    id_bytes,
                    workspace_name,
                    project_name,
                    path,
                    title,
                    snippet,
                    rank,
                    tier,
                    pinned,
                    frontmatter_json,
                    kind,
                ))
            })?;

            let mut candidates = Vec::new();
            for row in rows {
                let (
                    id_bytes,
                    workspace_name,
                    project_name,
                    path,
                    title,
                    snippet,
                    rank,
                    tier,
                    pinned,
                    frontmatter_json,
                    kind,
                ) = row?;
                let authority =
                    PageAuthority::from_stored(&path, &kind, &tier, pinned, &frontmatter_json);
                candidates.push((
                    PageHitWithMeta {
                        id: PageId::from_slice(&id_bytes)?,
                        workspace_name,
                        project_name,
                        path: PagePath::new(path)?,
                        title,
                        snippet,
                        rank,
                    },
                    authority,
                ));
            }
            let mut cjk_candidates = Vec::new();
            if let Some(cjk_query) = cjk_query {
                let descriptor = page_descriptor_expr("pages.body", "pages.frontmatter_json");
                let sql = format!(
                    "SELECT workspaces.name, projects.name, pages.path, pages.title, \
                            {descriptor}, pages_cjk_fts.rank, pages.tier, pages.pinned, \
                            pages.frontmatter_json, {kind_expr} AS kind, pages.id \
                     FROM pages_cjk_fts \
                     JOIN pages ON pages.rowid = pages_cjk_fts.rowid \
                     JOIN projects ON projects.id = pages.project_id \
                     JOIN workspaces ON workspaces.id = pages.workspace_id \
                     WHERE pages_cjk_fts MATCH ?1 AND pages.is_latest = 1{not_expired}{visible}{kept} \
                     ORDER BY pages_cjk_fts.rank LIMIT ?2",
                    not_expired = not_expired("pages", "?3"),
                );
                let mut stmt = conn.prepare(&sql)?;
                #[allow(clippy::cast_possible_wrap)]
                let mut bound = vec![
                    Value::Text(cjk_query),
                    Value::Integer(authority_candidate_limit(limit) as i64),
                    Value::Integer(cutoff),
                ];
                bound.extend(visible_params);
                bound.extend(kept_params);
                let rows = stmt.query_map(params_from_iter(bound.iter()), |row| {
                    Ok((
                        row.get::<_, String>(0)?,
                        row.get::<_, String>(1)?,
                        row.get::<_, String>(2)?,
                        row.get::<_, String>(3)?,
                        row.get::<_, String>(4)?,
                        row.get::<_, f64>(5)?,
                        row.get::<_, String>(6)?,
                        row.get::<_, i64>(7)? != 0,
                        row.get::<_, String>(8)?,
                        row.get::<_, String>(9)?,
                        row.get::<_, Vec<u8>>(10)?,
                    ))
                })?;
                for row in rows {
                    let (workspace_name, project_name, path, title, descriptor, rank, tier, pinned, frontmatter, kind, id) = row?;
                    let authority =
                        PageAuthority::from_stored(&path, &kind, &tier, pinned, &frontmatter);
                    cjk_candidates.push((
                        PageHitWithMeta {
                            id: PageId::from_slice(&id)?,
                            workspace_name,
                            project_name,
                            path: PagePath::new(path)?,
                            snippet: page_descriptor(&descriptor, &title),
                            title,
                            rank,
                        },
                        authority,
                    ));
                }
            }
            Ok(rerank_page_hits_with_meta(
                fuse_page_meta_candidate_streams(
                    candidates,
                    cjk_candidates,
                    authority_candidate_limit(limit),
                ),
                limit,
            ))
        })
        .await
    }

    /// Run an authority-adjusted full-text search scoped to one project.
    ///
    /// `expiry_cutoff_us`: `None` hides pages whose TTL has passed as of
    /// now (the default retrieval behaviour); `Some(cutoff)` compares
    /// against that instant instead — pass `i64::MIN` to include
    /// expired pages.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn search_pages_for_project(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        query: String,
        limit: usize,
        expiry_cutoff_us: Option<i64>,
    ) -> StoreResult<Vec<PageHit>> {
        if limit == 0 {
            return Ok(Vec::new());
        }
        let candidates = self
            .search_page_candidates_for_project(
                workspace_id,
                project_id,
                query,
                authority_candidate_limit(limit),
                expiry_cutoff_us,
                false,
                PageFilter::default(),
            )
            .await?;
        Ok(rerank_page_hits(candidates, limit))
    }

    #[allow(clippy::too_many_arguments)]
    async fn search_page_candidates_for_project(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        query: String,
        candidate_limit: usize,
        expiry_cutoff_us: Option<i64>,
        include_superseded: bool,
        filter: PageFilter<'_>,
    ) -> StoreResult<Vec<(PageHit, PageAuthority)>> {
        let fts_query = normalize_fts_query(&query, &self.fts_stopwords);
        let cjk_query = prepare_cjk_fts5_query(&query);
        if fts_query.is_empty() || candidate_limit == 0 {
            return Ok(Vec::new());
        }
        let cutoff = expiry_cutoff_us.unwrap_or_else(now_us);
        let (kept, kept_params) = filter.sql("pages", numbered_placeholders(6));
        self.with_conn(move |conn| {
            let kind_expr = page_kind_expr("pages.path", "pages.frontmatter_json");
            let sql = format!(
                "SELECT pages.id, pages.path, pages.title, \
                        snippet(pages_fts, 1, char(30), char(31), '…', 24) AS snip, \
                        pages_fts.rank, pages.tier, pages.pinned, \
                        pages.frontmatter_json, {kind_expr} AS kind \
                 FROM pages_fts \
                 JOIN pages ON pages.rowid = pages_fts.rowid \
                 WHERE pages_fts MATCH ?1 \
                   AND pages.workspace_id = ?2 \
                   AND pages.project_id = ?3{latest}{not_expired}{kept} \
                 ORDER BY pages_fts.rank \
                 LIMIT ?4",
                latest = latest_only("pages", include_superseded),
                not_expired = not_expired("pages", "?5"),
            );
            let mut stmt = conn.prepare(&sql)?;
            #[allow(clippy::cast_possible_wrap)]
            let mut bound = vec![
                Value::Text(fts_query),
                Value::Blob(workspace_id.as_bytes().to_vec()),
                Value::Blob(project_id.as_bytes().to_vec()),
                Value::Integer(candidate_limit as i64),
                Value::Integer(cutoff),
            ];
            bound.extend(kept_params.iter().cloned());
            let rows = stmt.query_map(params_from_iter(bound.iter()), |row| {
                let id_bytes: Vec<u8> = row.get(0)?;
                let path: String = row.get(1)?;
                let title: String = row.get(2)?;
                let snippet: String = row.get(3)?;
                let rank: f64 = row.get(4)?;
                let tier: String = row.get(5)?;
                let pinned = row.get::<_, i64>(6)? != 0;
                let frontmatter_json: String = row.get(7)?;
                let kind: String = row.get(8)?;
                Ok((
                    id_bytes,
                    path,
                    title,
                    snippet,
                    rank,
                    tier,
                    pinned,
                    frontmatter_json,
                    kind,
                ))
            })?;

            let mut candidates = Vec::new();
            for row in rows {
                let (id_bytes, path, title, snippet, rank, tier, pinned, frontmatter_json, kind) =
                    row?;
                let authority =
                    PageAuthority::from_stored(&path, &kind, &tier, pinned, &frontmatter_json);
                candidates.push((
                    PageHit {
                        id: PageId::from_slice(&id_bytes)?,
                        path: PagePath::new(path)?,
                        title,
                        snippet,
                        rank,
                        superseded: false,
                        pinned: false,
                    },
                    authority,
                ));
            }
            let mut cjk_candidates = Vec::new();
            if let Some(cjk_query) = cjk_query {
                let descriptor = page_descriptor_expr("pages.body", "pages.frontmatter_json");
                let sql = format!(
                    "SELECT pages.id, pages.path, pages.title, {descriptor}, \
                            pages_cjk_fts.rank, pages.tier, pages.pinned, \
                            pages.frontmatter_json, {kind_expr} AS kind \
                     FROM pages_cjk_fts \
                     JOIN pages ON pages.rowid = pages_cjk_fts.rowid \
                     WHERE pages_cjk_fts MATCH ?1 \
                       AND pages.workspace_id = ?2 AND pages.project_id = ?3 \
                       {latest}{not_expired}{kept} \
                     ORDER BY pages_cjk_fts.rank LIMIT ?4",
                    latest = latest_only("pages", include_superseded),
                    not_expired = not_expired("pages", "?5"),
                );
                let mut stmt = conn.prepare(&sql)?;
                #[allow(clippy::cast_possible_wrap)]
                let mut bound = vec![
                    Value::Text(cjk_query),
                    Value::Blob(workspace_id.as_bytes().to_vec()),
                    Value::Blob(project_id.as_bytes().to_vec()),
                    Value::Integer(candidate_limit as i64),
                    Value::Integer(cutoff),
                ];
                bound.extend(kept_params);
                let rows = stmt.query_map(params_from_iter(bound.iter()), |row| {
                    Ok((
                        row.get::<_, Vec<u8>>(0)?,
                        row.get::<_, String>(1)?,
                        row.get::<_, String>(2)?,
                        row.get::<_, String>(3)?,
                        row.get::<_, f64>(4)?,
                        row.get::<_, String>(5)?,
                        row.get::<_, i64>(6)? != 0,
                        row.get::<_, String>(7)?,
                        row.get::<_, String>(8)?,
                    ))
                })?;
                for row in rows {
                    let (id, path, title, descriptor, rank, tier, pinned, frontmatter, kind) = row?;
                    let authority =
                        PageAuthority::from_stored(&path, &kind, &tier, pinned, &frontmatter);
                    cjk_candidates.push((
                        PageHit {
                            id: PageId::from_slice(&id)?,
                            path: PagePath::new(path)?,
                            snippet: page_descriptor(&descriptor, &title),
                            title,
                            rank,
                            superseded: false,
                            pinned: false,
                        },
                        authority,
                    ));
                }
            }
            Ok(fuse_page_candidate_streams(
                candidates,
                cjk_candidates,
                candidate_limit,
            ))
        })
        .await
    }

    /// Authority-adjusted full-text candidates over the page versions
    /// whose ingestion windows contain `as_of_us` (issue #656).
    /// BM25 uses the current index's statistics, not a snapshot at T.
    /// Same candidate shape as
    /// [`Self::search_page_candidates_for_project`], but the corpus is
    /// versions alive at `T` instead of latest versions. TTL expiry is
    /// evaluated at `T`: a page already expired then was already hidden
    /// from search then.
    async fn search_page_candidates_for_project_at(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        query: String,
        candidate_limit: usize,
        as_of_us: i64,
        filter: PageFilter<'_>,
    ) -> StoreResult<Vec<(PageHit, PageAuthority)>> {
        let fts_query = normalize_fts_query(&query, &self.fts_stopwords);
        let cjk_query = prepare_cjk_fts5_query(&query);
        if fts_query.is_empty() || candidate_limit == 0 {
            return Ok(Vec::new());
        }
        let (kept, kept_params) = filter.sql("pages", numbered_placeholders(7));
        self.with_conn(move |conn| {
            let kind_expr = page_kind_expr("pages.path", "pages.frontmatter_json");
            let limit_placeholder = 7 + kept_params.len();
            let sql = format!(
                "SELECT pages.id, pages.path, pages.title, \
                        snippet(pages_fts, 1, char(30), char(31), '…', 24) AS snip, \
                        pages_fts.rank, pages.tier, pages.pinned, \
                        pages.frontmatter_json, {kind_expr} AS kind \
                 FROM pages_fts \
                 JOIN pages ON pages.rowid = pages_fts.rowid \
                 WHERE pages_fts MATCH ?1 \
                   AND pages.workspace_id = ?2 \
                   AND pages.project_id = ?3 \
                   AND pages.valid_from <= ?4 \
                   AND (pages.valid_to IS NULL OR pages.valid_to > ?5){not_expired}{kept} \
                 ORDER BY pages_fts.rank \
                 LIMIT ?{limit_placeholder}",
                not_expired = not_expired("pages", "?6"),
            );
            let mut stmt = conn.prepare(&sql)?;
            let mut sql_params = vec![
                Value::Text(fts_query),
                Value::Blob(workspace_id.as_bytes().to_vec()),
                Value::Blob(project_id.as_bytes().to_vec()),
                Value::Integer(as_of_us),
                Value::Integer(as_of_us),
                Value::Integer(as_of_us),
            ];
            sql_params.extend(kept_params.iter().cloned());
            #[allow(clippy::cast_possible_wrap)]
            sql_params.push(Value::Integer(candidate_limit as i64));
            let rows = stmt.query_map(params_from_iter(sql_params), |row| {
                let id_bytes: Vec<u8> = row.get(0)?;
                let path: String = row.get(1)?;
                let title: String = row.get(2)?;
                let snippet: String = row.get(3)?;
                let rank: f64 = row.get(4)?;
                let tier: String = row.get(5)?;
                let pinned = row.get::<_, i64>(6)? != 0;
                let frontmatter_json: String = row.get(7)?;
                let kind: String = row.get(8)?;
                Ok((
                    id_bytes,
                    path,
                    title,
                    snippet,
                    rank,
                    tier,
                    pinned,
                    frontmatter_json,
                    kind,
                ))
            })?;

            let mut candidates = Vec::new();
            for row in rows {
                let (id_bytes, path, title, snippet, rank, tier, pinned, frontmatter_json, kind) =
                    row?;
                let authority =
                    PageAuthority::from_stored(&path, &kind, &tier, pinned, &frontmatter_json);
                candidates.push((
                    PageHit {
                        id: PageId::from_slice(&id_bytes)?,
                        path: PagePath::new(path)?,
                        title,
                        snippet,
                        rank,
                        superseded: false,
                        pinned: false,
                    },
                    authority,
                ));
            }
            let mut cjk_candidates = Vec::new();
            if let Some(cjk_query) = cjk_query {
                let descriptor = page_descriptor_expr("pages.body", "pages.frontmatter_json");
                let sql = format!(
                    "SELECT pages.id, pages.path, pages.title, {descriptor}, \
                            pages_cjk_fts.rank, pages.tier, pages.pinned, \
                            pages.frontmatter_json, {kind_expr} AS kind \
                     FROM pages_cjk_fts \
                     JOIN pages ON pages.rowid = pages_cjk_fts.rowid \
                     WHERE pages_cjk_fts MATCH ?1 \
                       AND pages.workspace_id = ?2 AND pages.project_id = ?3 \
                       AND pages.valid_from <= ?4 \
                       AND (pages.valid_to IS NULL OR pages.valid_to > ?5){not_expired}{kept} \
                     ORDER BY pages_cjk_fts.rank LIMIT ?{limit_placeholder}",
                    not_expired = not_expired("pages", "?6"),
                );
                let mut sql_params = vec![
                    Value::Text(cjk_query),
                    Value::Blob(workspace_id.as_bytes().to_vec()),
                    Value::Blob(project_id.as_bytes().to_vec()),
                    Value::Integer(as_of_us),
                    Value::Integer(as_of_us),
                    Value::Integer(as_of_us),
                ];
                sql_params.extend(kept_params);
                #[allow(clippy::cast_possible_wrap)]
                sql_params.push(Value::Integer(candidate_limit as i64));
                let mut stmt = conn.prepare(&sql)?;
                let rows = stmt.query_map(params_from_iter(sql_params), |row| {
                    Ok((
                        row.get::<_, Vec<u8>>(0)?,
                        row.get::<_, String>(1)?,
                        row.get::<_, String>(2)?,
                        row.get::<_, String>(3)?,
                        row.get::<_, f64>(4)?,
                        row.get::<_, String>(5)?,
                        row.get::<_, i64>(6)? != 0,
                        row.get::<_, String>(7)?,
                        row.get::<_, String>(8)?,
                    ))
                })?;
                for row in rows {
                    let (id, path, title, descriptor, rank, tier, pinned, frontmatter, kind) = row?;
                    let authority =
                        PageAuthority::from_stored(&path, &kind, &tier, pinned, &frontmatter);
                    cjk_candidates.push((
                        PageHit {
                            id: PageId::from_slice(&id)?,
                            path: PagePath::new(path)?,
                            snippet: page_descriptor(&descriptor, &title),
                            title,
                            rank,
                            superseded: false,
                            pinned: false,
                        },
                        authority,
                    ));
                }
            }
            Ok(fuse_page_candidate_streams(
                candidates,
                cjk_candidates,
                candidate_limit,
            ))
        })
        .await
    }

    /// Time-travel search backing `memory_query(as_of)`
    /// (docs/temporal.md, issue #656): the entity-window lookup
    /// unchanged, plus version-filtered FTS over the page ingestion
    /// windows alive at `as_of_us`, fused with the same RRF (k=60) the
    /// default path uses and the same bounded authority adjustment —
    /// current-index relevance over knowledge *valid at T*. Vector, graph, and
    /// the raw-observation fallback stay out of audit mode: embeddings
    /// and links are present-tense artifacts with no version scope, and
    /// audit reads must not perturb access stats (no bump, no rerank).
    ///
    /// `explain` mirrors [`Self::hybrid_search`]: `false` drops the
    /// per-hit [`SearchExplain`]; `streams_active` reporting stays with
    /// the MCP caller.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn search_pages_for_project_at(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        query: String,
        limit: usize,
        as_of_us: i64,
        explain: bool,
    ) -> StoreResult<Vec<(PageHit, Option<SearchExplain>)>> {
        self.search_pages_for_project_at_filtered(
            workspace_id,
            project_id,
            query,
            limit,
            as_of_us,
            explain,
            PageFilter::default(),
        )
        .await
    }

    /// [`Self::search_pages_for_project_at`] returning only pages `filter`
    /// keeps. Every historical stream applies the filter before ranking.
    #[allow(clippy::too_many_arguments)]
    pub async fn search_pages_for_project_at_filtered(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        query: String,
        limit: usize,
        as_of_us: i64,
        explain: bool,
        filter: PageFilter<'_>,
    ) -> StoreResult<Vec<(PageHit, Option<SearchExplain>)>> {
        if limit == 0 {
            return Ok(Vec::new());
        }
        let candidate_limit = authority_candidate_limit(limit);
        let entity_hits = self
            .entity_hits_filtered(
                workspace_id,
                project_id,
                &query,
                candidate_limit,
                None,
                Some(as_of_us),
                // The as_of branch resolves versions by ingestion window, so
                // this flag is inert; false keeps the audit path unchanged.
                false,
                filter,
            )
            .await?;
        let fts_candidates = self
            .search_page_candidates_for_project_at(
                workspace_id,
                project_id,
                query,
                candidate_limit,
                as_of_us,
                filter,
            )
            .await?;
        let mut authorities: std::collections::HashMap<PageId, PageAuthority> = fts_candidates
            .iter()
            .map(|(hit, authority)| (hit.id, *authority))
            .collect();
        // Entity-only hits never passed through an FTS candidate row;
        // read their authority off the version row itself (no latest
        // filter — audit mode ranks superseded versions too).
        let missing: Vec<PageId> = entity_hits
            .iter()
            .map(|e| e.hit.id)
            .filter(|id| !authorities.contains_key(id))
            .collect();
        authorities.extend(
            self.page_authorities_for_versions(workspace_id, project_id, missing)
                .await?,
        );

        // RRF fuse: score(d) = Σ 1/(k + rank_i(d)) over the two streams.
        let k = 60.0_f64;
        struct FusedAt {
            path: PagePath,
            title: String,
            snippet: String,
            score: f64,
            explain: Option<SearchExplain>,
        }
        let mut fused: std::collections::HashMap<PageId, FusedAt> =
            std::collections::HashMap::new();
        for (rank, h) in fts_candidates.iter().map(|(hit, _)| hit).enumerate() {
            let contrib = 1.0 / (k + (rank + 1) as f64);
            let entry = fused.entry(h.id).or_insert_with(|| FusedAt {
                path: h.path.clone(),
                title: h.title.clone(),
                snippet: h.snippet.clone(),
                score: 0.0,
                explain: explain.then(SearchExplain::default),
            });
            entry.score += contrib;
            if let Some(details) = &mut entry.explain {
                details.fts_rank = Some(rank + 1);
                details.fts_score = Some(h.rank);
                details.rrf.fts = contrib;
                details.fused += contrib;
            }
        }
        for (rank, e) in entity_hits.iter().enumerate() {
            let contrib = 1.0 / (k + (rank + 1) as f64);
            let entry = fused.entry(e.hit.id).or_insert_with(|| FusedAt {
                path: e.hit.path.clone(),
                title: e.hit.title.clone(),
                snippet: e.hit.snippet.clone(),
                score: 0.0,
                explain: explain.then(SearchExplain::default),
            });
            entry.score += contrib;
            if let Some(details) = &mut entry.explain {
                details.entity_rank = Some(rank + 1);
                details.entity_weight = Some(e.weight);
                details.matched_entities = e.matched.clone();
                details.rrf.entity = contrib;
                details.fused += contrib;
            }
        }

        let mut out: Vec<(PageHit, Option<SearchExplain>)> = fused
            .into_iter()
            .map(|(id, entry)| {
                (
                    PageHit {
                        id,
                        path: entry.path,
                        title: entry.title,
                        snippet: entry.snippet,
                        rank: -entry.score, // lower = better (matches FTS5 convention)
                        superseded: false,
                        pinned: false,
                    },
                    entry.explain,
                )
            })
            .collect();
        // No session-recall routing in audit mode; the plain authority
        // factor keeps maintained pages' bounded advantage at T.
        for (hit, details) in &mut out {
            if let Some(authority) = authorities.get(&hit.id) {
                hit.rank = authority.adjust_rank(hit.rank);
                if let Some(explain) = details {
                    explain.authority = Some(authority.factor);
                }
            }
        }
        out.sort_by(|a, b| {
            a.0.rank
                .partial_cmp(&b.0.rank)
                .unwrap_or(std::cmp::Ordering::Equal)
                .then_with(|| a.0.path.as_str().cmp(b.0.path.as_str()))
        });
        out.truncate(limit);
        Ok(out)
    }
    /// Raw-observation FTS over one project, with no owner filter: every
    /// session's observations. Internal callers and tests use this; a
    /// caller answering on someone's behalf uses
    /// [`Self::search_observations_for_project_as`].
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn search_observations_for_project(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        query: String,
        limit: usize,
    ) -> StoreResult<Vec<ObservationHit>> {
        self.search_observations_for_project_as(
            workspace_id,
            project_id,
            query,
            limit,
            OwnerFilter::Any,
        )
        .await
    }

    /// Raw-observation FTS over one project, limited to sessions
    /// `owner_filter` admits: the rule `memory_read_session_observations`
    /// and the web session timeline apply (the caller's own sessions plus
    /// unattributed ones). Another operator's owned session contributes no
    /// hit.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn search_observations_for_project_as(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        query: String,
        limit: usize,
        owner_filter: OwnerFilter,
    ) -> StoreResult<Vec<ObservationHit>> {
        let fts_query = normalize_fts_query(&query, &self.fts_stopwords);
        let cjk_query = prepare_cjk_fts5_query(&query);
        if fts_query.is_empty() {
            return Ok(Vec::new());
        }
        self.with_conn(move |conn| {
            let owner_clause = match &owner_filter {
                OwnerFilter::Any => "",
                OwnerFilter::User(_) => {
                    " AND EXISTS (SELECT 1 FROM sessions s WHERE s.id = observations.session_id \
                       AND (s.actor_user IS NULL OR s.actor_user = ?5))"
                }
                OwnerFilter::Unattributed => {
                    " AND EXISTS (SELECT 1 FROM sessions s WHERE s.id = observations.session_id \
                       AND s.actor_user IS NULL)"
                }
            };
            let mut stmt = conn.prepare(&format!(
                "SELECT observations.id, observations.session_id, observations.kind, \
                        observations.title, \
                        snippet(observations_fts, 1, char(30), char(31), '…', 24) AS snip, \
                        observations_fts.rank, observations.created_at \
                 FROM observations_fts \
                 JOIN observations ON observations.rowid = observations_fts.rowid \
                 WHERE observations_fts MATCH ?1 \
                   AND observations.workspace_id = ?2 \
                   AND observations.project_id = ?3{owner_clause} \
                 ORDER BY observations_fts.rank \
                 LIMIT ?4",
            ))?;
            let actor = match &owner_filter {
                OwnerFilter::User(user) => Some(user.as_str()),
                OwnerFilter::Any | OwnerFilter::Unattributed => None,
            };
            let mut sql_params: Vec<&dyn rusqlite::ToSql> = Vec::with_capacity(5);
            let ws_bytes = workspace_id.as_bytes();
            let proj_bytes = project_id.as_bytes();
            #[allow(clippy::cast_possible_wrap)]
            let limit = limit as i64;
            sql_params.push(&fts_query);
            sql_params.push(&ws_bytes);
            sql_params.push(&proj_bytes);
            sql_params.push(&limit);
            if let Some(actor) = &actor {
                sql_params.push(actor);
            }
            let rows = stmt.query_map(sql_params.as_slice(), |row| {
                let id_bytes: Vec<u8> = row.get(0)?;
                let session_bytes: Vec<u8> = row.get(1)?;
                let kind: String = row.get(2)?;
                let title: String = row.get(3)?;
                let snippet: String = row.get(4)?;
                let rank: f64 = row.get(5)?;
                let created_us: i64 = row.get(6)?;
                Ok((
                    id_bytes,
                    session_bytes,
                    kind,
                    title,
                    snippet,
                    rank,
                    created_us,
                ))
            })?;

            let mut hits = Vec::new();
            for row in rows {
                let (id_bytes, session_bytes, kind, title, snippet, rank, created_us) = row?;
                let created_at = jiff::Timestamp::from_microsecond(created_us)
                    .map(|ts| ts.to_string())
                    .unwrap_or_default();
                hits.push(ObservationHit {
                    id: ObservationId::from_slice(&id_bytes)?,
                    session_id: SessionId::from_slice(&session_bytes)?,
                    kind,
                    title,
                    snippet,
                    rank,
                    created_at,
                });
            }
            let mut cjk_hits = Vec::new();
            if let Some(cjk_query) = cjk_query {
                let mut stmt = conn.prepare(&format!(
                    "SELECT observations.id, observations.session_id, observations.kind, \
                            observations.title, substr(observations.body, 1, 240), \
                            observations_cjk_fts.rank, observations.created_at \
                     FROM observations_cjk_fts \
                     JOIN observations ON observations.rowid = observations_cjk_fts.rowid \
                     WHERE observations_cjk_fts MATCH ?1 \
                       AND observations.workspace_id = ?2 \
                       AND observations.project_id = ?3{owner_clause} \
                     ORDER BY observations_cjk_fts.rank LIMIT ?4",
                ))?;
                let mut sql_params: Vec<&dyn rusqlite::ToSql> = Vec::with_capacity(5);
                sql_params.push(&cjk_query);
                sql_params.push(&ws_bytes);
                sql_params.push(&proj_bytes);
                sql_params.push(&limit);
                if let Some(actor) = &actor {
                    sql_params.push(actor);
                }
                let rows = stmt.query_map(sql_params.as_slice(), |row| {
                    Ok((
                        row.get::<_, Vec<u8>>(0)?,
                        row.get::<_, Vec<u8>>(1)?,
                        row.get::<_, String>(2)?,
                        row.get::<_, String>(3)?,
                        row.get::<_, String>(4)?,
                        row.get::<_, f64>(5)?,
                        row.get::<_, i64>(6)?,
                    ))
                })?;
                for row in rows {
                    let (id, session, kind, title, snippet, rank, created_us) = row?;
                    let created_at = jiff::Timestamp::from_microsecond(created_us)
                        .map(|ts| ts.to_string())
                        .unwrap_or_default();
                    cjk_hits.push(ObservationHit {
                        id: ObservationId::from_slice(&id)?,
                        session_id: SessionId::from_slice(&session)?,
                        kind,
                        title,
                        snippet,
                        rank,
                        created_at,
                    });
                }
            }
            Ok(fuse_observation_streams(hits, cjk_hits, limit as usize))
        })
        .await
    }

    /// The R1 observation stream: sessions whose observations match `query`,
    /// mapped to their latest `sessions/<id>.md` page in the same scope and
    /// ordered by each session's best-ranked observation.
    ///
    /// Both halves of the join are filtered to `(workspace_id, project_id)`:
    /// an observation from another project never votes, and a same-path page
    /// in another project never receives a vote. A session counts once
    /// however many of its observations match. A session with no latest,
    /// unexpired page in this scope contributes nothing; the raw-observation
    /// fallback still covers live sessions. The two reads share one read
    /// transaction so the mapping sees a single snapshot. Read-only.
    #[allow(clippy::too_many_arguments)]
    async fn observation_stream_votes(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        query: &str,
        candidate_limit: usize,
        cutoff: i64,
        owner_filter: OwnerFilter,
        filter: PageFilter<'_>,
    ) -> StoreResult<Vec<ObservationVote>> {
        let fts_query = normalize_fts_query(query, &self.fts_stopwords);
        let cjk_query = prepare_cjk_fts5_query(query);
        if fts_query.is_empty() || candidate_limit == 0 {
            return Ok(Vec::new());
        }
        // The ranked observation window must contain only sessions whose
        // latest page survives the page filter. Otherwise a common excluded
        // kind or tag can crowd a rare eligible session out before mapping.
        let (candidate_kept, candidate_kept_params) =
            filter.sql("candidate_page", numbered_placeholders(8));
        // The session pages' lookup takes anonymous `?`s after its IN list.
        let (kept, kept_params) = filter.sql("pages", anonymous_placeholder);
        let row_limit = candidate_limit
            .saturating_mul(OBSERVATION_STREAM_ROWS_PER_CANDIDATE)
            .min(OBSERVATION_STREAM_MAX_ROWS);
        self.with_conn(move |conn| {
            let tx = conn.unchecked_transaction()?;
            // `observations_fts` spans every project, and bm25 runs for every
            // match before the scope filter can drop it. The project's rowid
            // span bounds the index scan to the stretch of the log where
            // this project wrote; the scope predicates below still decide
            // membership inside it.
            let span: Option<(i64, i64)> = tx
                .query_row(
                    OBSERVATION_ROWID_SPAN_SQL,
                    params![project_id.as_bytes()],
                    |row| Ok((row.get::<_, Option<i64>>(0)?, row.get::<_, Option<i64>>(1)?)),
                )
                .map(|(lo, hi)| lo.zip(hi))?;
            let Some((first_rowid, last_rowid)) = span else {
                return Ok(Vec::new());
            };
            // Best-ranked observation first, grouped by session in first-seen
            // order: the session's stream rank is its best observation's.
            let mut sessions: Vec<(SessionId, String, Vec<ObservationId>)> = Vec::new();
            let mut index: std::collections::HashMap<SessionId, usize> =
                std::collections::HashMap::new();
            let candidate_path =
                "'sessions/' || substr(lower(hex(observations.session_id)), 1, 8) || '-' || \
                 substr(lower(hex(observations.session_id)), 9, 4) || '-' || \
                 substr(lower(hex(observations.session_id)), 13, 4) || '-' || \
                 substr(lower(hex(observations.session_id)), 17, 4) || '-' || \
                 substr(lower(hex(observations.session_id)), 21, 12) || '.md'";
            {
                // CROSS JOIN pins the FTS table as the outer loop: left to
                // itself the planner drives from the observations scope index
                // and re-enters FTS once per row, which is far slower.
                let mut stmt = tx.prepare(&format!(
                    "SELECT observations.id, observations.session_id, \
                            snippet(observations_fts, 1, char(30), char(31), '…', \
                                    {OBSERVATION_SNIPPET_TOKENS}) \
                     FROM observations_fts \
                     CROSS JOIN observations ON observations.rowid = observations_fts.rowid \
                     WHERE observations_fts MATCH ?1 \
                       AND observations_fts.rowid >= ?5 \
                       AND observations_fts.rowid <= ?6 \
                       AND observations.workspace_id = ?2 \
                       AND observations.project_id = ?3 \
                       AND EXISTS ( \
                         SELECT 1 FROM pages AS candidate_page \
                         WHERE candidate_page.workspace_id = observations.workspace_id \
                           AND candidate_page.project_id = observations.project_id \
                           AND candidate_page.is_latest = 1 \
                           AND candidate_page.path = {candidate_path} \
                           {candidate_not_expired}{candidate_kept} \
                       ) \
                     ORDER BY observations_fts.rank \
                     LIMIT ?4",
                    candidate_not_expired = not_expired("candidate_page", "?7"),
                ))?;
                #[allow(clippy::cast_possible_wrap)]
                let mut candidate_params = vec![
                    Value::Text(fts_query),
                    Value::Blob(workspace_id.as_bytes().to_vec()),
                    Value::Blob(project_id.as_bytes().to_vec()),
                    Value::Integer(row_limit as i64),
                    Value::Integer(first_rowid),
                    Value::Integer(last_rowid),
                    Value::Integer(cutoff),
                ];
                candidate_params.extend(candidate_kept_params.iter().cloned());
                let rows = stmt.query_map(params_from_iter(candidate_params.iter()), |row| {
                        Ok((
                            row.get::<_, Vec<u8>>(0)?,
                            row.get::<_, Vec<u8>>(1)?,
                            row.get::<_, String>(2)?,
                        ))
                    })?;
                for row in rows {
                    let (id_bytes, session_bytes, snippet) = row?;
                    let id = ObservationId::from_slice(&id_bytes)?;
                    let session_id = SessionId::from_slice(&session_bytes)?;
                    match index.get(&session_id) {
                        Some(&at) => {
                            let ids = &mut sessions[at].2;
                            if ids.len() < OBSERVATION_STREAM_IDS_PER_PAGE {
                                ids.push(id);
                            }
                        }
                        None => {
                            index.insert(session_id, sessions.len());
                            sessions.push((session_id, snippet, vec![id]));
                        }
                    }
                }
            }
            if let Some(cjk_query) = cjk_query {
                let mut stmt = tx.prepare(&format!(
                    "SELECT observations.id, observations.session_id, \
                            substr(observations.body, 1, 240) \
                     FROM observations_cjk_fts \
                     CROSS JOIN observations ON observations.rowid = observations_cjk_fts.rowid \
                     WHERE observations_cjk_fts MATCH ?1 \
                       AND observations_cjk_fts.rowid >= ?5 \
                       AND observations_cjk_fts.rowid <= ?6 \
                       AND observations.workspace_id = ?2 \
                       AND observations.project_id = ?3 \
                       AND EXISTS ( \
                         SELECT 1 FROM pages AS candidate_page \
                         WHERE candidate_page.workspace_id = observations.workspace_id \
                           AND candidate_page.project_id = observations.project_id \
                           AND candidate_page.is_latest = 1 \
                           AND candidate_page.path = {candidate_path} \
                           {candidate_not_expired}{candidate_kept} \
                       ) \
                     ORDER BY observations_cjk_fts.rank LIMIT ?4",
                    candidate_not_expired = not_expired("candidate_page", "?7"),
                ))?;
                #[allow(clippy::cast_possible_wrap)]
                let mut candidate_params = vec![
                    Value::Text(cjk_query),
                    Value::Blob(workspace_id.as_bytes().to_vec()),
                    Value::Blob(project_id.as_bytes().to_vec()),
                    Value::Integer(row_limit as i64),
                    Value::Integer(first_rowid),
                    Value::Integer(last_rowid),
                    Value::Integer(cutoff),
                ];
                candidate_params.extend(candidate_kept_params);
                let rows = stmt.query_map(params_from_iter(candidate_params.iter()), |row| {
                    Ok((
                        row.get::<_, Vec<u8>>(0)?,
                        row.get::<_, Vec<u8>>(1)?,
                        row.get::<_, String>(2)?,
                    ))
                })?;
                for row in rows {
                    let (id_bytes, session_bytes, snippet) = row?;
                    let id = ObservationId::from_slice(&id_bytes)?;
                    let session_id = SessionId::from_slice(&session_bytes)?;
                    match index.get(&session_id) {
                        Some(&at) => {
                            let ids = &mut sessions[at].2;
                            if ids.len() < OBSERVATION_STREAM_IDS_PER_PAGE && !ids.contains(&id) {
                                ids.push(id);
                            }
                        }
                        None => {
                            index.insert(session_id, sessions.len());
                            sessions.push((session_id, snippet, vec![id]));
                        }
                    }
                }
            }
            if sessions.is_empty() {
                return Ok(Vec::new());
            }
            let hidden = sessions_hidden_from(&tx, &owner_filter, &sessions)?;

            let mut sql_params: Vec<Value> = Vec::with_capacity(sessions.len() + 3);
            sql_params.push(Value::Blob(workspace_id.as_bytes().to_vec()));
            sql_params.push(Value::Blob(project_id.as_bytes().to_vec()));
            sql_params.push(Value::Integer(cutoff));
            let mut placeholders = String::with_capacity(sessions.len() * 3);
            for (idx, (session_id, _, _)) in sessions.iter().enumerate() {
                if idx > 0 {
                    placeholders.push_str(", ");
                }
                placeholders.push('?');
                sql_params.push(Value::Text(format!("sessions/{session_id}.md")));
            }
            sql_params.extend(kept_params);
            let sql = format!(
                "SELECT pages.id, pages.path, pages.title \
                 FROM pages \
                 WHERE pages.workspace_id = ?1 \
                   AND pages.project_id = ?2 \
                   AND pages.is_latest = 1{not_expired} \
                   AND pages.path IN ({placeholders}){kept}",
                not_expired = not_expired("pages", "?3"),
            );
            let mut pages: std::collections::HashMap<String, (PageId, String)> =
                std::collections::HashMap::new();
            {
                let mut stmt = tx.prepare(&sql)?;
                let rows = stmt.query_map(params_from_iter(sql_params.iter()), |row| {
                    Ok((
                        row.get::<_, Vec<u8>>(0)?,
                        row.get::<_, String>(1)?,
                        row.get::<_, String>(2)?,
                    ))
                })?;
                for row in rows {
                    let (id_bytes, path, title) = row?;
                    pages.insert(path, (PageId::from_slice(&id_bytes)?, title));
                }
            }
            tx.finish()?;

            let mut votes = Vec::new();
            for (session_id, snippet, observation_ids) in sessions {
                let path = format!("sessions/{session_id}.md");
                let Some((page_id, title)) = pages.remove(&path) else {
                    continue;
                };
                let readable = !hidden.contains(&session_id);
                votes.push(ObservationVote {
                    page_id,
                    path: PagePath::new(path)?,
                    title,
                    snippet: readable.then_some(snippet),
                    observation_ids: if readable {
                        observation_ids
                    } else {
                        Vec::new()
                    },
                });
                if votes.len() == candidate_limit {
                    break;
                }
            }
            Ok(votes)
        })
        .await
    }

    /// Return the N most-recently-updated `is_latest = 1` pages.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn recent_pages(&self, limit: usize) -> StoreResult<Vec<PageHit>> {
        self.with_conn(move |conn| {
            let sql = format!(
                "SELECT id, path, title, \
                        {descriptor} AS snip, \
                        CAST(updated_at AS REAL) AS rank \
                 FROM pages \
                 WHERE is_latest = 1{not_expired} \
                 ORDER BY updated_at DESC \
                 LIMIT ?1",
                descriptor = page_descriptor_expr("body", "frontmatter_json"),
                not_expired = not_expired("pages", "?2"),
            );
            let mut stmt = conn.prepare_cached(&sql)?;
            #[allow(clippy::cast_possible_wrap)]
            let rows = stmt.query_map(params![limit as i64, now_us()], |row| {
                let id_bytes: Vec<u8> = row.get(0)?;
                let path: String = row.get(1)?;
                let title: String = row.get(2)?;
                let snippet = page_descriptor(&row.get::<_, String>(3)?, &title);
                let rank: f64 = row.get(4)?;
                Ok((id_bytes, path, title, snippet, rank))
            })?;
            let mut hits = Vec::new();
            for row in rows {
                let (id_bytes, path, title, snippet, rank) = row?;
                hits.push(PageHit {
                    id: PageId::from_slice(&id_bytes)?,
                    path: PagePath::new(path)?,
                    title,
                    snippet,
                    rank,
                    superseded: false,
                    pinned: false,
                });
            }
            Ok(hits)
        })
        .await
    }

    /// List the project's pinned latest pages, most-recently-updated first.
    ///
    /// This is the "list pinned pages" primitive behind the opt-in
    /// `memory_query(pin_first=true)` prepend and the briefing's `pinned`
    /// standing-context list (2.4 line): pages an operator explicitly pinned
    /// are standing context an agent should see *before* it searches. It
    /// returns only current pinned versions (`pinned = 1 AND is_latest = 1`),
    /// so an unpinned page and a superseded (older) pinned version are both
    /// excluded, and `limit` bounds the result.
    ///
    /// Recency has no FTS relevance score, so the reused [`PageHit::rank`]
    /// field carries `updated_at` (µs, cast to REAL) exactly as
    /// [`Self::recent_pages_for_project`] does — larger means "more recent";
    /// callers must not read it as an FTS rank. Each hit is marked
    /// `pinned: true`.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn list_pinned_pages(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        limit: usize,
    ) -> StoreResult<Vec<PageHit>> {
        self.list_pinned_pages_filtered(workspace_id, project_id, limit, PageFilter::default())
            .await
    }

    /// [`Self::list_pinned_pages`] returning only pages `filter` keeps.
    pub async fn list_pinned_pages_filtered(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        limit: usize,
        filter: PageFilter<'_>,
    ) -> StoreResult<Vec<PageHit>> {
        let limit = limit.clamp(1, 100);
        let (kept, kept_params) = filter.sql("pages", numbered_placeholders(5));
        self.with_conn(move |conn| {
            let sql = format!(
                "SELECT id, path, title, \
                        {descriptor} AS snip, \
                        CAST(updated_at AS REAL) AS rank \
                 FROM pages \
                 WHERE workspace_id = ?1 AND project_id = ?2 \
                   AND is_latest = 1 AND pinned = 1{not_expired}{kept} \
                 ORDER BY updated_at DESC \
                 LIMIT ?3",
                descriptor = page_descriptor_expr("body", "frontmatter_json"),
                not_expired = not_expired("pages", "?4"),
            );
            let mut stmt = conn.prepare_cached(&sql)?;
            let mut sql_params = vec![
                Value::Blob(workspace_id.as_bytes().to_vec()),
                Value::Blob(project_id.as_bytes().to_vec()),
                Value::Integer(i64::try_from(limit).unwrap_or(i64::MAX)),
                Value::Integer(now_us()),
            ];
            sql_params.extend(kept_params);
            #[allow(clippy::cast_possible_wrap)]
            let rows = stmt.query_map(params_from_iter(sql_params), |row| {
                let id_bytes: Vec<u8> = row.get(0)?;
                let path: String = row.get(1)?;
                let title: String = row.get(2)?;
                let snippet = page_descriptor(&row.get::<_, String>(3)?, &title);
                let rank: f64 = row.get(4)?;
                Ok((id_bytes, path, title, snippet, rank))
            })?;
            let mut hits = Vec::new();
            for row in rows {
                let (id_bytes, path, title, snippet, rank) = row?;
                hits.push(PageHit {
                    id: PageId::from_slice(&id_bytes)?,
                    path: PagePath::new(path)?,
                    title,
                    snippet,
                    rank,
                    superseded: false,
                    pinned: true,
                });
            }
            Ok(hits)
        })
        .await
    }

    /// Return the N most-recently-updated pages scoped to one project.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn recent_pages_for_project(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        limit: usize,
    ) -> StoreResult<Vec<PageHit>> {
        self.with_conn(move |conn| {
            let sql = format!(
                "SELECT id, path, title, \
                        {descriptor} AS snip, \
                        CAST(updated_at AS REAL) AS rank \
                 FROM pages \
                 WHERE workspace_id = ?1 AND project_id = ?2 AND is_latest = 1{not_expired} \
                 ORDER BY updated_at DESC \
                 LIMIT ?3",
                descriptor = page_descriptor_expr("body", "frontmatter_json"),
                not_expired = not_expired("pages", "?4"),
            );
            let mut stmt = conn.prepare_cached(&sql)?;
            #[allow(clippy::cast_possible_wrap)]
            let rows = stmt.query_map(
                params![
                    workspace_id.as_bytes(),
                    project_id.as_bytes(),
                    limit as i64,
                    now_us()
                ],
                |row| {
                    let id_bytes: Vec<u8> = row.get(0)?;
                    let path: String = row.get(1)?;
                    let title: String = row.get(2)?;
                    let snippet = page_descriptor(&row.get::<_, String>(3)?, &title);
                    let rank: f64 = row.get(4)?;
                    Ok((id_bytes, path, title, snippet, rank))
                },
            )?;
            let mut hits = Vec::new();
            for row in rows {
                let (id_bytes, path, title, snippet, rank) = row?;
                hits.push(PageHit {
                    id: PageId::from_slice(&id_bytes)?,
                    path: PagePath::new(path)?,
                    title,
                    snippet,
                    rank,
                    superseded: false,
                    pinned: false,
                });
            }
            Ok(hits)
        })
        .await
    }

    /// The `limit` most-recently-updated `is_latest` pages across EVERY
    /// project, each annotated with its workspace + project name. The
    /// cross-project analog of [`Self::recent_pages_for_project`]; used when a
    /// read's scope broadens to global.
    ///
    /// Recency has no FTS relevance score, so the reused
    /// [`PageHitWithMeta::rank`] field carries `updated_at` (µs, cast to
    /// REAL) — larger still means "ranks first", callers must not read it
    /// as an FTS rank.
    ///
    /// `viewer` restricts the pages to repositories that user may read — see
    /// [`readable_repository_filter`]. `None` lists every repository.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn recent_pages_global(
        &self,
        limit: usize,
        viewer: Option<UserId>,
    ) -> StoreResult<Vec<PageHitWithMeta>> {
        self.with_conn(move |conn| {
            let (visible, visible_params) =
                readable_repository_filter("pages.project_id", viewer, 3);
            let sql = format!(
                "SELECT workspaces.name, projects.name, pages.path, pages.title, \
                        {descriptor} AS snip, \
                        CAST(pages.updated_at AS REAL) AS rank, pages.id \
                 FROM pages \
                 JOIN projects ON projects.id = pages.project_id \
                 JOIN workspaces ON workspaces.id = pages.workspace_id \
                 WHERE pages.is_latest = 1{not_expired}{visible} \
                 ORDER BY pages.updated_at DESC \
                 LIMIT ?1",
                descriptor = page_descriptor_expr("pages.body", "pages.frontmatter_json"),
                not_expired = not_expired("pages", "?2"),
            );
            let mut stmt = conn.prepare_cached(&sql)?;
            #[allow(clippy::cast_possible_wrap)]
            let mut bound = vec![Value::Integer(limit as i64), Value::Integer(now_us())];
            bound.extend(visible_params);
            let rows = stmt.query_map(params_from_iter(bound.iter()), |row| {
                let workspace_name: String = row.get(0)?;
                let project_name: String = row.get(1)?;
                let path: String = row.get(2)?;
                let title: String = row.get(3)?;
                let snippet = page_descriptor(&row.get::<_, String>(4)?, &title);
                let rank: f64 = row.get(5)?;
                let id_bytes: Vec<u8> = row.get(6)?;
                Ok((
                    id_bytes,
                    workspace_name,
                    project_name,
                    path,
                    title,
                    snippet,
                    rank,
                ))
            })?;
            let mut hits = Vec::new();
            for row in rows {
                let (id_bytes, workspace_name, project_name, path, title, snippet, rank) = row?;
                hits.push(PageHitWithMeta {
                    id: PageId::from_slice(&id_bytes)?,
                    workspace_name,
                    project_name,
                    path: PagePath::new(path)?,
                    title,
                    snippet,
                    rank,
                });
            }
            Ok(hits)
        })
        .await
    }

    /// Return all observations for the given session, ordered by
    /// `created_at` ascending.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn observations_for_session(
        &self,
        session_id: SessionId,
    ) -> StoreResult<Vec<Observation>> {
        self.with_conn(move |conn| {
            let mut stmt = conn.prepare_cached(
                "SELECT id, session_id, workspace_id, project_id, kind, extension, source_event, \
                        title, body, importance, created_at \
                 FROM observations \
                 WHERE session_id = ?1 \
                 ORDER BY created_at ASC",
            )?;
            let rows = stmt.query_map(params![session_id.as_bytes()], row_to_observation)?;
            let mut out = Vec::new();
            for r in rows {
                out.push(r??);
            }
            Ok(out)
        })
        .await
    }

    /// Whether the session in the given scope holds at least one prompt or
    /// tool use: the positive "real work" predicate
    /// ([`SUBSTANTIVE_OBSERVATION_KIND_SQL`]) the writer's lifecycle-only end
    /// applies in its own transaction, asked as one short-circuiting existence
    /// query instead of loading the rows. A missing or foreign session returns
    /// `false` without revealing which condition applied.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn session_has_substantive_observation(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        session_id: SessionId,
    ) -> StoreResult<bool> {
        self.with_conn(move |conn| {
            let sql = format!(
                "SELECT EXISTS(\
                    SELECT 1 FROM observations AS o \
                    JOIN sessions AS s ON s.id = o.session_id \
                    WHERE o.session_id = ?1 \
                      AND s.workspace_id = ?2 AND s.project_id = ?3 \
                      AND {}\
                )",
                SUBSTANTIVE_OBSERVATION_KIND_SQL
            );
            Ok(conn.query_row(
                &sql,
                params![
                    session_id.as_bytes(),
                    workspace_id.as_bytes(),
                    project_id.as_bytes()
                ],
                |row| row.get(0),
            )?)
        })
        .await
    }

    /// Count one session's IN-SCOPE observations — every kind, not just the
    /// substantive ones. A session's idle end stamps
    /// `ended_observation_count` from the live count and re-verifies the
    /// candidate's digest-time count against it: a non-end observation
    /// (a `Stop`, a lifecycle marker) landing in the window between the
    /// digest read and the stamp must still lose the CAS. Scoped the same
    /// way as [`Self::session_has_substantive_observation`]; a missing or
    /// foreign session counts as zero.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn session_observation_count(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        session_id: SessionId,
    ) -> StoreResult<i64> {
        self.with_conn(move |conn| {
            const SQL: &str = "SELECT COUNT(*) \
                 FROM observations AS o \
                 JOIN sessions AS s ON s.id = o.session_id \
                 WHERE o.session_id = ?1 \
                   AND s.workspace_id = ?2 AND s.project_id = ?3";
            Ok(conn.query_row(
                SQL,
                params![
                    session_id.as_bytes(),
                    workspace_id.as_bytes(),
                    project_id.as_bytes()
                ],
                |row| row.get(0),
            )?)
        })
        .await
    }

    /// Read one session's observations through bounded queries, all inside one
    /// read transaction so every answer describes the same set of rows. The
    /// session must belong to the given workspace and project; a foreign or
    /// missing id is refused as [`StoreError::SessionCollision`].
    ///
    /// This is the SessionEnd path's alternative to
    /// [`Self::observations_for_session`]: that call deserializes every row
    /// (a session can hold hundreds of thousands), while `read` gets a
    /// [`SessionObservationSnapshot`] whose queries are aggregates, `LIMIT`ed
    /// windows and streamed scans. `read` runs on a blocking thread and must
    /// not wait on anything async.
    ///
    /// # Errors
    /// Propagates any SQL or pool error, and whatever `read` returns.
    pub async fn read_session_observations<F, T>(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        session_id: SessionId,
        read: F,
    ) -> StoreResult<T>
    where
        F: FnOnce(&SessionObservationSnapshot<'_>) -> StoreResult<T> + Send + 'static,
        T: Send + 'static,
    {
        self.with_conn(move |conn| {
            let tx = conn.unchecked_transaction()?;
            let in_scope = tx.query_row(
                "SELECT EXISTS(\
                    SELECT 1 FROM sessions \
                    WHERE id = ?1 AND workspace_id = ?2 AND project_id = ?3\
                )",
                params![
                    session_id.as_bytes(),
                    workspace_id.as_bytes(),
                    project_id.as_bytes()
                ],
                |row| row.get::<_, bool>(0),
            )?;
            if !in_scope {
                return Err(StoreError::SessionCollision);
            }
            let snapshot = SessionObservationSnapshot {
                conn: &tx,
                session_id: session_id.as_bytes().to_vec(),
                rows_read: std::cell::Cell::new(0),
            };
            read(&snapshot)
        })
        .await
    }

    /// [`Self::read_session_observations`] gated on the session holding at
    /// least one observation in the given scope, instead of on its
    /// `sessions` row.
    ///
    /// The consolidator resolves the repository a session consolidates into
    /// from where its observations actually landed, not from the (possibly
    /// stale) `sessions` row, so its bounded reads gate on the observations
    /// themselves: a session with rows in the scope opens, and a session
    /// with none there — including a purged one — is refused as
    /// [`StoreError::SessionCollision`], like the `sessions`-row gate.
    ///
    /// # Errors
    /// Propagates any SQL or pool error, and whatever `read` returns.
    pub async fn read_session_observations_in_scope<F, T>(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        session_id: SessionId,
        read: F,
    ) -> StoreResult<T>
    where
        F: FnOnce(&SessionObservationSnapshot<'_>) -> StoreResult<T> + Send + 'static,
        T: Send + 'static,
    {
        self.with_conn(move |conn| {
            let tx = conn.unchecked_transaction()?;
            let in_scope = tx.query_row(
                "SELECT EXISTS(\
                    SELECT 1 FROM observations \
                    WHERE session_id = ?1 AND workspace_id = ?2 AND project_id = ?3\
                )",
                params![
                    session_id.as_bytes(),
                    workspace_id.as_bytes(),
                    project_id.as_bytes()
                ],
                |row| row.get::<_, bool>(0),
            )?;
            if !in_scope {
                return Err(StoreError::SessionCollision);
            }
            let snapshot = SessionObservationSnapshot {
                conn: &tx,
                session_id: session_id.as_bytes().to_vec(),
                rows_read: std::cell::Cell::new(0),
            };
            read(&snapshot)
        })
        .await
    }

    /// Page through one session's raw observations as seen from one scope.
    ///
    /// Only the rows that landed in `(workspace_id, project_id)` are returned:
    /// a session that crossed repositories mid-flight has observations in more
    /// than one scope, and a caller resolved to one of them must not read the
    /// other. `elided_other_scope` reports how many rows were left out so the
    /// caller can tell a short session from a partially visible one. `total`
    /// counts the in-scope rows matching the page's kind and query filters, so
    /// paginating needs no second round-trip; a zero `limit` returns no rows
    /// but still reports both counts.
    ///
    /// The query goes through the same FTS5 normalization as
    /// [`Self::search_observations_for_project`] and is dropped when nothing
    /// searchable remains, so a punctuation-only query lists the session
    /// instead of matching nothing.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn session_observations_scoped(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        session_id: SessionId,
        page: ObservationPage,
    ) -> StoreResult<ObservationPageResult> {
        let cjk_query = page.query.as_deref().and_then(prepare_cjk_fts5_query);
        let fts_query = page
            .query
            .as_deref()
            .map(|q| normalize_fts_query(q, &self.fts_stopwords))
            .filter(|q| !q.is_empty());
        let kinds: Vec<&'static str> = page
            .kinds
            .iter()
            .flatten()
            .map(ObservationKind::as_str)
            .collect();
        let direction = match page.order {
            ObservationOrder::Asc => "ASC",
            ObservationOrder::Desc => "DESC",
        };
        let (limit, offset) = (page.limit, page.offset);
        self.with_conn(move |conn| {
            // `?` is positional-by-order: session, scope, then the optional
            // MATCH term and kind list, then LIMIT/OFFSET on the page query.
            let mut sql_params: Vec<Value> = Vec::with_capacity(kinds.len() + 6);
            sql_params.push(Value::Blob(session_id.as_bytes().to_vec()));
            sql_params.push(Value::Blob(workspace_id.as_bytes().to_vec()));
            sql_params.push(Value::Blob(project_id.as_bytes().to_vec()));
            let mut source = String::from("FROM observations");
            let mut predicate = String::from(
                " WHERE observations.session_id = ?1 \
                   AND observations.workspace_id = ?2 \
                   AND observations.project_id = ?3",
            );
            if let Some(q) = fts_query {
                if let Some(cjk_query) = cjk_query {
                    source.push_str(
                        " JOIN ( \
                            SELECT rowid FROM observations_fts WHERE observations_fts MATCH ?4 \
                            UNION \
                            SELECT rowid FROM observations_cjk_fts \
                              WHERE observations_cjk_fts MATCH ?5 \
                         ) AS matched_fts ON matched_fts.rowid = observations.rowid",
                    );
                    sql_params.push(Value::Text(q));
                    sql_params.push(Value::Text(cjk_query));
                } else {
                    source.push_str(
                        " JOIN observations_fts ON observations_fts.rowid = observations.rowid",
                    );
                    predicate.push_str(" AND observations_fts MATCH ?");
                    sql_params.push(Value::Text(q));
                }
            }
            if !kinds.is_empty() {
                predicate.push_str(" AND observations.kind IN (");
                for (idx, kind) in kinds.iter().enumerate() {
                    if idx > 0 {
                        predicate.push_str(", ");
                    }
                    predicate.push('?');
                    sql_params.push(Value::Text((*kind).to_string()));
                }
                predicate.push(')');
            }

            let total: i64 = conn.query_row(
                &format!("SELECT COUNT(*) {source}{predicate}"),
                params_from_iter(sql_params.iter()),
                |row| row.get(0),
            )?;
            let elided: i64 = conn.query_row(
                "SELECT COUNT(*) FROM observations \
                 WHERE session_id = ?1 AND NOT (workspace_id = ?2 AND project_id = ?3)",
                params![
                    session_id.as_bytes(),
                    workspace_id.as_bytes(),
                    project_id.as_bytes()
                ],
                |row| row.get(0),
            )?;

            let mut records = Vec::new();
            if limit > 0 {
                sql_params.push(Value::Integer(i64::try_from(limit).unwrap_or(i64::MAX)));
                sql_params.push(Value::Integer(i64::try_from(offset).unwrap_or(i64::MAX)));
                let sql = format!(
                    "SELECT observations.id, observations.session_id, observations.kind, \
                            observations.title, observations.body, observations.importance, \
                            observations.created_at, observations.extension, \
                            observations.source_event \
                     {source}{predicate} \
                     ORDER BY observations.created_at {direction}, observations.id {direction} \
                     LIMIT ? OFFSET ?"
                );
                let mut stmt = conn.prepare(&sql)?;
                let rows = stmt.query_map(
                    params_from_iter(sql_params.iter()),
                    row_to_observation_record,
                )?;
                for row in rows {
                    records.push(row??);
                }
            }
            Ok(ObservationPageResult {
                records,
                total: u64::try_from(total).unwrap_or(0),
                elided_other_scope: u64::try_from(elided).unwrap_or(0),
            })
        })
        .await
    }

    /// Return the `(workspace_id, project_id)` with the most recent recorded
    /// activity at or after `since_us` (wall clock, microseconds).
    ///
    /// Observations are the complete activity log — every lifecycle hook event
    /// lands as one, stamped with the scope it was routed to — so the newest
    /// row is the project the operator was last working in. Used at startup to
    /// seed the in-memory active-project fallback, which a restart otherwise
    /// drops (#678). The caller supplies the cutoff so a long-idle server does
    /// not resurrect a scope the live pointer would have expired anyway.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn most_recently_active_scope(
        &self,
        since_us: i64,
    ) -> StoreResult<Option<(WorkspaceId, ProjectId)>> {
        self.with_conn(move |conn| {
            let row = conn
                .query_row(
                    "SELECT workspace_id, project_id FROM observations \
                     WHERE created_at >= ?1 \
                     ORDER BY created_at DESC LIMIT 1",
                    params![since_us],
                    |row| Ok((row.get::<_, Vec<u8>>(0)?, row.get::<_, Vec<u8>>(1)?)),
                )
                .optional()?;
            match row {
                Some((ws, proj)) => Ok(Some((
                    WorkspaceId::from_slice(&ws)?,
                    ProjectId::from_slice(&proj)?,
                ))),
                None => Ok(None),
            }
        })
        .await
    }

    /// Return the latest completed session for a project.
    ///
    /// Used by read-only review tools that need a natural default when the user
    /// asks what the project just learned without naming a session id.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn latest_completed_session_for_project(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> StoreResult<Option<SessionId>> {
        self.with_conn(move |conn| {
            let row_opt: Option<Vec<u8>> = conn
                .query_row(
                    "SELECT id FROM sessions \
                     WHERE workspace_id = ?1 AND project_id = ?2 AND ended_at IS NOT NULL \
                     ORDER BY ended_at DESC, started_at DESC LIMIT 1",
                    params![workspace_id.as_bytes(), project_id.as_bytes()],
                    |row| row.get(0),
                )
                .optional()?;
            row_opt
                .map(|bytes| SessionId::from_slice(&bytes).map_err(StoreError::from))
                .transpose()
        })
        .await
    }

    /// Return the latest completed session that has no persisted
    /// auto-improvement run in the same project.
    ///
    /// This is the implicit queue used by manual auto-improvement. Explicitly
    /// named sessions remain rerunnable, while an omitted session id advances
    /// past both full reviews and preflight-skipped runs.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn latest_unreviewed_completed_session_for_project(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> StoreResult<Option<SessionId>> {
        self.with_conn(move |conn| {
            let row_opt: Option<Vec<u8>> = conn
                .query_row(
                    "SELECT s.id FROM sessions s \
                     WHERE s.workspace_id = ?1 \
                       AND s.project_id = ?2 \
                       AND s.ended_at IS NOT NULL \
                       AND NOT EXISTS ( \
                           SELECT 1 FROM auto_improve_runs r \
                           WHERE r.workspace_id = s.workspace_id \
                             AND r.project_id = s.project_id \
                             AND r.session_id = s.id \
                       ) \
                     ORDER BY s.ended_at DESC, s.started_at DESC LIMIT 1",
                    params![workspace_id.as_bytes(), project_id.as_bytes()],
                    |row| row.get(0),
                )
                .optional()?;
            row_opt
                .map(|bytes| SessionId::from_slice(&bytes).map_err(StoreError::from))
                .transpose()
        })
        .await
    }

    /// Sum per-client MCP tool-call counters, optionally bounded to
    /// buckets at or after `since_day` (UTC days since the epoch;
    /// `None` = whole history). Ordered by total volume descending
    /// with a client-name tiebreak so equal totals do not reorder
    /// between calls.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn client_activity_since(
        &self,
        since_day: Option<i64>,
    ) -> StoreResult<Vec<ClientActivity>> {
        self.with_conn(move |conn| {
            let since_clause = if since_day.is_some() {
                " WHERE day >= :since"
            } else {
                ""
            };
            let sql = format!(
                "SELECT client, SUM(reads), SUM(writes) FROM client_activity\
                 {since_clause} \
                 GROUP BY client \
                 ORDER BY SUM(reads) + SUM(writes) DESC, client ASC"
            );
            let mut stmt = conn.prepare_cached(&sql)?;
            let map = |row: &rusqlite::Row<'_>| {
                let client: String = row.get(0)?;
                let reads: i64 = row.get(1)?;
                let writes: i64 = row.get(2)?;
                Ok((client, reads, writes))
            };
            let rows = match &since_day {
                Some(since) => stmt.query_map(&[(":since", since as &dyn rusqlite::ToSql)], map)?,
                None => stmt.query_map([], map)?,
            };
            let mut out = Vec::new();
            for row in rows {
                let (client, reads, writes) = row?;
                out.push(ClientActivity {
                    client,
                    reads: u64::try_from(reads).unwrap_or(0),
                    writes: u64::try_from(writes).unwrap_or(0),
                });
            }
            Ok(out)
        })
        .await
    }

    /// Count sessions per agent CLI in one scope, newest window first.
    ///
    /// Counts every session the window covers, open or ended — the question
    /// is which tools produced this project's memory, not which are running
    /// right now (`open_sessions_for_scope_agent` answers that).
    ///
    /// `since_us` is an inclusive lower bound on `started_at`; `None` counts
    /// the project's whole history. The scan rides
    /// `idx_sessions_recent (workspace_id, project_id, started_at DESC)`, so
    /// it stays bounded by scope rather than table-wide, and the per-session
    /// capture probe is pinned to `idx_observations_session`.
    ///
    /// Ordering is count-descending with an agent-name tiebreak, so equal
    /// counts do not reorder between calls.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn session_counts_by_agent(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        owner_filter: OwnerFilter,
        since_us: Option<i64>,
    ) -> StoreResult<Vec<AgentSessionCount>> {
        self.with_conn(move |conn| {
            let sql = session_counts_by_agent_sql(since_us.is_some(), &owner_filter);
            let mut stmt = conn.prepare_cached(&sql)?;
            let ws_bytes = workspace_id.as_bytes();
            let proj_bytes = project_id.as_bytes();
            let mut named: Vec<(&str, &dyn rusqlite::ToSql)> = vec![
                (":ws", &ws_bytes as &dyn rusqlite::ToSql),
                (":proj", &proj_bytes as &dyn rusqlite::ToSql),
            ];
            if let Some(since) = &since_us {
                named.push((":since", since));
            }
            if let OwnerFilter::User(user) = &owner_filter {
                named.push((":actor", user));
            }
            let rows = stmt.query_map(named.as_slice(), |row| {
                let agent: String = row.get(0)?;
                let n: i64 = row.get(1)?;
                Ok((agent, n, row.get::<_, i64>(2)?))
            })?;
            let mut out = Vec::new();
            for row in rows {
                let (agent, n, mixed) = row?;
                out.push(AgentSessionCount {
                    agent,
                    sessions: u64::try_from(n).unwrap_or(0),
                    mixed_capture_sessions: u64::try_from(mixed).unwrap_or(0),
                });
            }
            Ok(out)
        })
        .await
    }

    /// Read response diagnostics in one scope, filtering session ownership
    /// before aggregating or ranking. No observation bodies are loaded.
    pub async fn token_usage_report(
        &self,
        ws: WorkspaceId,
        proj: ProjectId,
        owner: OwnerFilter,
    ) -> StoreResult<TokenUsageReport> {
        self.token_usage_report_filtered(ws, proj, owner, None)
            .await
    }

    pub(crate) async fn token_usage_report_filtered(
        &self,
        ws: WorkspaceId,
        proj: ProjectId,
        owner: OwnerFilter,
        session: Option<SessionId>,
    ) -> StoreResult<TokenUsageReport> {
        self.token_usage_report_page(ws, proj, owner, session, TokenCallQuery::default())
            .await
    }

    /// Search and order all authorized responses before selecting one bounded
    /// page. Totals and signal averages always cover the whole authorized scope.
    pub async fn token_usage_report_page(
        &self,
        ws: WorkspaceId,
        proj: ProjectId,
        owner: OwnerFilter,
        session: Option<SessionId>,
        query: TokenCallQuery,
    ) -> StoreResult<TokenUsageReport> {
        self.with_conn(move |conn| {
            let (mode, actor) = match owner {
                OwnerFilter::Any => (0, String::new()),
                OwnerFilter::User(a) => (1, a),
                OwnerFilter::Unattributed => (2, String::new()),
            };
            let from = " FROM token_calls c JOIN sessions s ON s.id = c.session_id \
                         WHERE s.workspace_id = ?1 AND s.project_id = ?2 \
                         AND (?3 = 0 OR s.actor_user IS NULL \
                              OR (?3 = 1 AND s.actor_user = ?4)) AND (?5 IS NULL OR s.id = ?5)";
            let session_bytes = session.map(|id| id.as_bytes().to_vec());
            let params =
                rusqlite::params![ws.as_bytes(), proj.as_bytes(), mode, actor, session_bytes];
            let mut report = conn.query_row(
                &format!(
                    "SELECT COUNT(*), COALESCE(SUM(c.input_tokens), 0), \
                         COALESCE(SUM(c.output_tokens), 0), \
                         COALESCE(SUM(c.cache_write_tokens), 0), \
                         COALESCE(SUM(c.cache_read_tokens), 0){from}"
                ),
                params,
                |r| {
                    Ok(TokenUsageReport {
                        call_count: r.get(0)?,
                        input: r.get(1)?,
                        output: r.get(2)?,
                        cache_write: r.get(3)?,
                        cache_read: r.get(4)?,
                        calls: Vec::new(),
                        matching_calls: 0,
                        matching_tokens: 0,
                    })
                },
            )?;
            let total = "(c.input_tokens + c.output_tokens + c.cache_write_tokens + c.cache_read_tokens)";
            let context = "(c.input_tokens + c.cache_write_tokens + c.cache_read_tokens)";
            let mean = (report.input + report.output + report.cache_write + report.cache_read)
                .checked_div(report.call_count).unwrap_or(0);
            let filtered = format!("{from} AND (?6 = '' OR instr(lower(c.call_id || ' ' || COALESCE(c.native_response_id,'') || ' ' || s.agent_kind || ' ' || replace(s.agent_kind,'-',' ') || ' ' || COALESCE(c.model,'')), ?6) > 0) \
                AND (?7 = 0 OR {context} >= 100000 OR c.output_tokens >= 20000 OR (?8 >= 5 AND {total} > ?9)) \
                AND (?10 IS NULL OR COALESCE(c.model,'Not reported')=?10) \
                AND (?11 IS NULL OR s.agent_kind=?11) AND (?12 IS NULL OR s.id=?12) \
                AND (?13 IS NULL OR COALESCE(c.response_at,c.observed_at)>=?13) \
                AND (?14 IS NULL OR COALESCE(c.response_at,c.observed_at)<?14) \
                AND (?15 IS NULL OR c.turn_id=?15) \
                AND (?16 IS NULL OR EXISTS(SELECT 1 FROM token_call_tools t WHERE t.session_id=c.session_id AND t.call_id=c.call_id AND t.tool_name=?16))");
            let search = query.search.chars().take(256).collect::<String>().to_lowercase();
            let filter_session = query.session_id.map(|s| s.as_bytes().to_vec());
            let filter_agent = query.agent.map(AgentKind::as_str);
            let filtered_params = rusqlite::params![ws.as_bytes(), proj.as_bytes(), mode, actor,
                session_bytes, search, query.signals_only, report.call_count, mean.saturating_mul(3),
                query.model,filter_agent,filter_session,query.from_us,query.until_us,query.turn_id,query.tool];
            (report.matching_calls,report.matching_tokens) = conn.query_row(&format!("SELECT COUNT(*),COALESCE(SUM({total}),0){filtered}"), filtered_params, |r| Ok((r.get(0)?,r.get(1)?)))?;
            let order = match query.order {
                TokenCallOrder::Largest => format!("{total} DESC, c.observed_at DESC"),
                TokenCallOrder::Recent => format!("COALESCE(c.response_at,c.observed_at) DESC, {total} DESC"),
            };
            let offset = query.offset.min(i64::MAX as usize);
            let mut stmt = conn.prepare(&format!(
                "SELECT c.call_id, s.id, s.agent_kind, COALESCE(c.model, 'Not reported'), \
                        c.input_tokens, c.output_tokens, c.cache_write_tokens, \
                        c.cache_read_tokens, c.observed_at, c.turn_id,c.native_response_id,c.response_at {filtered} \
                 ORDER BY {order}, c.session_id, c.call_id LIMIT 50 OFFSET {offset}"
            ))?;
            let rows = stmt.query_map(filtered_params, |r| {
                let sid: Vec<u8> = r.get(1)?;
                Ok((
                    sid,
                    TokenCallView {
                        turn_id: r.get(9)?,
                        response_id: r.get(10)?,
                        response_at: r.get::<_,Option<i64>>(11)?.and_then(|us| jiff::Timestamp::from_microsecond(us).ok()).map(|t| t.to_string()),
                        tools: Vec::new(),
                        call_id: r.get(0)?,
                        session_id: String::new(),
                        agent: r.get(2)?,
                        model: r.get(3)?,
                        input: r.get(4)?,
                        output: r.get(5)?,
                        cache_write: r.get(6)?,
                        cache_read: r.get(7)?,
                        observed_at: jiff::Timestamp::from_microsecond(r.get(8)?)
                            .map(|t| t.to_string())
                            .unwrap_or_default(),
                    },
                ))
            })?;
            let mut keys=Vec::new();
            for row in rows {
                let (sid, mut call) = row?;
                keys.push(Value::Blob(sid.clone()));keys.push(Value::Text(call.call_id.clone()));
                call.session_id = SessionId::from_slice(&sid)?.to_string();
                report.calls.push(call);
            }
            if !keys.is_empty() {
                let pairs=std::iter::repeat_n("(?,?)",report.calls.len()).collect::<Vec<_>>().join(",");
                let mut tools=conn.prepare(&format!("SELECT session_id,call_id,tool_id,tool_name,relation,is_error FROM token_call_tools WHERE (session_id,call_id) IN ({pairs}) ORDER BY session_id,call_id,tool_id,relation"))?;
                let rows=tools.query_map(params_from_iter(keys),|r|Ok((r.get::<_,Vec<u8>>(0)?,r.get::<_,String>(1)?,r.get::<_,String>(2)?,r.get::<_,String>(3)?,r.get::<_,String>(4)?,r.get::<_,Option<bool>>(5)?)))?;
                for row in rows {
                    let (sid,call_id,id,name,relation,is_error)=row?;
                    let sid=SessionId::from_slice(&sid)?.to_string();
                    let relation=match relation.as_str(){"requested"=>ai_memory_core::TokenToolRelation::Requested,"input"=>ai_memory_core::TokenToolRelation::Input,_=>ai_memory_core::TokenToolRelation::Turn};
                    if let Some(call)=report.calls.iter_mut().find(|c|c.session_id==sid && c.call_id==call_id) && call.tools.len()<16 {
                        call.tools.push(ai_memory_core::TokenToolRef{id,name,relation,is_error});
                    }
                }
            }
            Ok(report)
        })
        .await
    }

    /// Total reported token usage across every session in one scope
    /// (token-cost visibility) — the project-wide figure the web dashboard's
    /// "Tokens" stat needs, as opposed to the per-row usage
    /// [`Self::sessions_for_scope`] returns for its most-recent page.
    /// `None` when not a single session in scope has reported any usage yet
    /// (not a zeroed [`SessionUsageView`]).
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn total_session_usage(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        owner_filter: OwnerFilter,
    ) -> StoreResult<Option<SessionUsageView>> {
        self.with_conn(move |conn| {
            let owner_clause = match &owner_filter {
                OwnerFilter::Any => "",
                OwnerFilter::User(_) => " AND (s.actor_user IS NULL OR s.actor_user = :actor)",
                OwnerFilter::Unattributed => " AND s.actor_user IS NULL",
            };
            let sql = format!(
                "SELECT COUNT(*), SUM(u.input_tokens), SUM(u.output_tokens), \
                        SUM(u.cache_write_tokens), SUM(u.cache_read_tokens) \
                 FROM session_usage u \
                 JOIN sessions s ON s.id = u.session_id \
                 WHERE s.workspace_id = :ws AND s.project_id = :proj{owner_clause}"
            );
            let mut stmt = conn.prepare_cached(&sql)?;
            let ws_bytes = workspace_id.as_bytes();
            let proj_bytes = project_id.as_bytes();
            let mut named: Vec<(&str, &dyn rusqlite::ToSql)> = vec![
                (":ws", &ws_bytes as &dyn rusqlite::ToSql),
                (":proj", &proj_bytes as &dyn rusqlite::ToSql),
            ];
            if let OwnerFilter::User(user) = &owner_filter {
                named.push((":actor", user));
            }
            let (rows, input, output, cache_write, cache_read): (
                i64,
                Option<i64>,
                Option<i64>,
                Option<i64>,
                Option<i64>,
            ) = stmt.query_row(named.as_slice(), |row| {
                Ok((
                    row.get(0)?,
                    row.get(1)?,
                    row.get(2)?,
                    row.get(3)?,
                    row.get(4)?,
                ))
            })?;
            if rows == 0 {
                return Ok(None);
            }
            Ok(Some(SessionUsageView {
                input_tokens: u64::try_from(input.unwrap_or(0)).unwrap_or(0),
                output_tokens: u64::try_from(output.unwrap_or(0)).unwrap_or(0),
                cache_write_tokens: u64::try_from(cache_write.unwrap_or(0)).unwrap_or(0),
                cache_read_tokens: u64::try_from(cache_read.unwrap_or(0)).unwrap_or(0),
                model: None,
            }))
        })
        .await
    }

    /// Return open sessions matching one scoped project and agent.
    ///
    /// Results are newest-first so callers can default to finalizing only the
    /// latest open session while offering an explicit all-sessions mode.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn open_sessions_for_scope_agent(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        agent_kind: AgentKind,
        owner_filter: OwnerFilter,
        limit: Option<usize>,
    ) -> StoreResult<Vec<OpenSession>> {
        self.open_sessions_for_scope_agent_filtered(
            workspace_id,
            project_id,
            agent_kind,
            owner_filter,
            limit,
            None,
            false,
        )
        .await
    }

    /// Return one exact open session for a scoped project and agent.
    ///
    /// The id narrows the scope, agent, open-state, and owner predicates; it
    /// never replaces them. A known id therefore cannot expose or finalize a
    /// colleague's session unless the caller explicitly uses
    /// [`OwnerFilter::Any`].
    ///
    /// Pass `include_ended = true` to also match a session whose `ended_at`
    /// is already set — the re-finalize path (`finalize-session --reopen`)
    /// for agents without a native session-end, where new observations may
    /// have landed after the first end. Reopening stays exact-id-only: the
    /// bulk listing above always excludes ended sessions.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn open_session_for_scope_agent_by_id(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        agent_kind: AgentKind,
        owner_filter: OwnerFilter,
        session_id: SessionId,
        include_ended: bool,
    ) -> StoreResult<Option<OpenSession>> {
        let mut sessions = self
            .open_sessions_for_scope_agent_filtered(
                workspace_id,
                project_id,
                agent_kind,
                owner_filter,
                Some(1),
                Some(session_id),
                include_ended,
            )
            .await?;
        Ok(sessions.pop())
    }

    /// Return the most recently active substantive interrupted session in a scope.
    ///
    /// This powers startup recovery when a harness disappears without a
    /// `SessionEnd` (quota exhaustion, process kill, machine restart). The
    /// query is owner-filtered before prompt-derived rows are selected and
    /// excludes the receiving session id, so it cannot echo a new session back
    /// to itself. It is deliberately non-destructive: parallel sessions are a
    /// supported workflow and an open row is not proof that its process died.
    ///
    /// A candidate must contain at least one prompt or tool observation in the
    /// exact scope. Lifecycle-only sessions never produce recovery noise. Some
    /// harnesses reuse a session id after they previously emitted `SessionEnd`;
    /// those rows are eligible again only when a substantive observation is
    /// newer than the recorded end. This preserves normal completed-session
    /// behavior while avoiding a silent continuity gap after quota recovery.
    /// A handoff covering its newest work already supplies continuity, so
    /// reading recovery must not replay a claimed or superseded baton.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn latest_interrupted_session_candidate(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        owner_filter: OwnerFilter,
        receiving_session_id: Option<SessionId>,
    ) -> StoreResult<Option<InterruptedSessionCandidate>> {
        self.with_conn(move |conn| {
            let sql = latest_interrupted_session_candidate_sql(
                &owner_filter,
                receiving_session_id.is_some(),
            );
            let ws_bytes = workspace_id.as_bytes();
            let proj_bytes = project_id.as_bytes();
            let receiver_bytes = receiving_session_id.map(|id| *id.as_bytes());
            let mut named: Vec<(&str, &dyn rusqlite::ToSql)> = vec![
                (":ws", &ws_bytes as &dyn rusqlite::ToSql),
                (":proj", &proj_bytes as &dyn rusqlite::ToSql),
            ];
            if let OwnerFilter::User(owner) = &owner_filter {
                named.push((":actor", owner));
            }
            if let Some(receiver) = &receiver_bytes {
                named.push((":receiver", receiver));
            }
            let row = conn
                .query_row(&sql, named.as_slice(), |row| {
                    Ok((
                        row.get::<_, Vec<u8>>(0)?,
                        row.get::<_, String>(1)?,
                        row.get::<_, i64>(2)?,
                        row.get::<_, Option<String>>(3)?,
                    ))
                })
                .optional()?;
            let Some((id, agent, last_activity_us, cwd)) = row else {
                return Ok(None);
            };
            let last_activity_at = jiff::Timestamp::from_microsecond(last_activity_us)
                .map(|ts| ts.to_string())
                .unwrap_or_default();
            Ok(Some(InterruptedSessionCandidate {
                session_id: SessionId::from_slice(&id)?,
                agent_kind: AgentKind::from_wire(&agent),
                last_activity_at,
                cwd,
            }))
        })
        .await
    }

    // Eight arguments is the full lookup key (scope + agent + owner +
    // limit + exact id + ended-state); splitting it would just move the
    // same parameters into a struct at both call sites.
    #[allow(clippy::too_many_arguments)]
    async fn open_sessions_for_scope_agent_filtered(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        agent_kind: AgentKind,
        owner_filter: OwnerFilter,
        limit: Option<usize>,
        exact_session_id: Option<SessionId>,
        include_ended: bool,
    ) -> StoreResult<Vec<OpenSession>> {
        let agent = agent_kind.as_str().to_string();
        self.with_conn(move |conn| {
            let limit_clause = limit.map_or(String::new(), |n| format!(" LIMIT {}", n.max(1)));
            // Without the owner predicate this returns whichever session in the
            // scope started last — frequently a teammate's live one — and the
            // callers act on it destructively.
            let owner_clause = match &owner_filter {
                OwnerFilter::Any => "",
                OwnerFilter::User(_) => " AND (actor_user IS NULL OR actor_user = ?4)",
                OwnerFilter::Unattributed => " AND actor_user IS NULL",
            };
            // An exact-id lookup with `include_ended` reaches sessions that
            // already closed (a manual finalizer's re-run after more work
            // landed); the default and every bulk listing only see sessions
            // whose `ended_at` is still NULL.
            let ended_clause = if include_ended {
                ""
            } else {
                " AND ended_at IS NULL"
            };
            let session_id_placeholder = if matches!(owner_filter, OwnerFilter::User(_)) {
                "?5"
            } else {
                "?4"
            };
            let session_id_clause = if exact_session_id.is_some() {
                format!(" AND id = {session_id_placeholder}")
            } else {
                String::new()
            };
            let sql = format!(
                "SELECT id, cwd FROM sessions \
                 WHERE workspace_id = ?1 AND project_id = ?2 \
                   AND agent_kind = ?3{ended_clause}{owner_clause}{session_id_clause} \
                 ORDER BY started_at DESC, id DESC{limit_clause}"
            );
            let mut stmt = conn.prepare_cached(&sql)?;
            let row_map = |row: &rusqlite::Row<'_>| {
                let id_bytes: Vec<u8> = row.get(0)?;
                let cwd: Option<String> = row.get(1)?;
                Ok((id_bytes, cwd))
            };
            let rows = match (&owner_filter, exact_session_id) {
                (OwnerFilter::User(user), Some(sid)) => stmt.query_map(
                    params![
                        workspace_id.as_bytes(),
                        project_id.as_bytes(),
                        agent,
                        user,
                        sid.as_bytes()
                    ],
                    row_map,
                )?,
                (OwnerFilter::User(user), None) => stmt.query_map(
                    params![workspace_id.as_bytes(), project_id.as_bytes(), agent, user],
                    row_map,
                )?,
                (_, Some(sid)) => stmt.query_map(
                    params![
                        workspace_id.as_bytes(),
                        project_id.as_bytes(),
                        agent,
                        sid.as_bytes()
                    ],
                    row_map,
                )?,
                (_, None) => stmt.query_map(
                    params![workspace_id.as_bytes(), project_id.as_bytes(), agent],
                    row_map,
                )?,
            };
            let mut out = Vec::new();
            for row in rows {
                let (id_bytes, cwd) = row?;
                out.push(OpenSession {
                    session_id: SessionId::from_slice(&id_bytes)?,
                    cwd,
                });
            }
            Ok(out)
        })
        .await
    }

    /// List the sessions that touched one scope, newest first.
    ///
    /// A session is listed when its `sessions` row is anchored in the scope OR
    /// at least one of its observations landed there. The second half matters
    /// for a session that changed repositories mid-flight: its row stays
    /// frozen on the starting scope (`begin_session` is `ON CONFLICT DO
    /// NOTHING`), so listing by row alone would hide it from the very scope
    /// that holds its work. `observation_count` counts only the rows in this
    /// scope. `include_open == false` keeps sessions with `ended_at` set.
    ///
    /// The owner predicate follows the rest of the session surface: shared
    /// (`actor_user IS NULL`) rows are visible to everyone, owned rows only to
    /// their operator unless the caller passes [`OwnerFilter::Any`].
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn sessions_for_scope(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        owner_filter: OwnerFilter,
        include_open: bool,
        limit: usize,
        offset: usize,
    ) -> StoreResult<Vec<SessionSummary>> {
        self.sessions_for_scope_filtered(
            workspace_id,
            project_id,
            owner_filter,
            include_open,
            limit,
            offset,
            None,
            None,
        )
        .await
    }

    /// Return one session as seen from one scope, or `None` when the session
    /// has neither its row nor any observation there, or when the owner
    /// filter rejects it. The id narrows the same predicates
    /// [`Self::sessions_for_scope`] applies (open sessions included); it
    /// never replaces them, so a known id cannot read across scopes or
    /// operators.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn session_summary_scoped(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        session_id: SessionId,
        owner_filter: OwnerFilter,
    ) -> StoreResult<Option<SessionSummary>> {
        let mut sessions = self
            .sessions_for_scope_filtered(
                workspace_id,
                project_id,
                owner_filter,
                true,
                1,
                0,
                Some(session_id),
                None,
            )
            .await?;
        Ok(sessions.pop())
    }

    /// The sessions with the newest captured work in one scope, newest
    /// first, limited to work at or after `since`. Owner-filtered on the
    /// session row exactly like [`Self::sessions_for_scope`], so on a shared
    /// server one operator never learns another's session ids.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn recent_session_activity(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        owner_filter: OwnerFilter,
        since: jiff::Timestamp,
        limit: usize,
    ) -> StoreResult<Vec<SessionActivity>> {
        self.with_conn(move |conn| {
            let owner_clause = match &owner_filter {
                OwnerFilter::Any => "",
                OwnerFilter::User(_) => " AND (s.actor_user IS NULL OR s.actor_user = :actor)",
                OwnerFilter::Unattributed => " AND s.actor_user IS NULL",
            };
            // The project/time index bounds the scan to the window; the
            // grouping is per session, so the row count is the number of
            // sessions that worked in it.
            let sql = format!(
                "SELECT w.session_id, w.last_us, w.agent_kind, w.cwd, w.ended_at, \
                        EXISTS (SELECT 1 FROM handoffs h \
                                WHERE h.workspace_id = :ws AND h.project_id = :proj \
                                  AND h.from_session_id = w.session_id \
                                  AND h.created_at >= w.last_us) \
                 FROM (SELECT o.session_id, MAX(o.created_at) AS last_us, \
                              s.agent_kind, s.cwd, s.ended_at \
                       FROM observations o INDEXED BY idx_observations_project_created \
                       JOIN sessions s ON s.id = o.session_id \
                       WHERE o.workspace_id = :ws AND o.project_id = :proj \
                         AND o.created_at >= :since \
                         AND o.kind NOT IN ('session-start', 'session-end'){owner_clause} \
                       GROUP BY o.session_id \
                       ORDER BY last_us DESC, o.session_id DESC \
                       LIMIT :limit) w \
                 ORDER BY w.last_us DESC, w.session_id DESC"
            );
            let mut stmt = conn.prepare_cached(&sql)?;
            let ws_bytes = workspace_id.as_bytes();
            let proj_bytes = project_id.as_bytes();
            let since_us = since.as_microsecond();
            let limit = i64::try_from(limit).unwrap_or(i64::MAX);
            let mut named: Vec<(&str, &dyn rusqlite::ToSql)> = vec![
                (":ws", &ws_bytes as &dyn rusqlite::ToSql),
                (":proj", &proj_bytes),
                (":since", &since_us),
                (":limit", &limit),
            ];
            if let OwnerFilter::User(user) = &owner_filter {
                named.push((":actor", user));
            }
            let rows = stmt.query_map(named.as_slice(), |row| {
                Ok((
                    row.get::<_, Vec<u8>>(0)?,
                    row.get::<_, i64>(1)?,
                    row.get::<_, String>(2)?,
                    row.get::<_, Option<String>>(3)?,
                    row.get::<_, Option<i64>>(4)?,
                    row.get::<_, bool>(5)?,
                ))
            })?;
            let mut out = Vec::new();
            for row in rows {
                let (id_bytes, last_us, agent_kind, cwd, ended_us, handed_off) = row?;
                out.push(SessionActivity {
                    session_id: SessionId::from_slice(&id_bytes)?,
                    agent_kind,
                    cwd,
                    last_activity_at: jiff::Timestamp::from_microsecond(last_us)
                        .map(|ts| ts.to_string())
                        .unwrap_or_default(),
                    last_activity_us: last_us,
                    ended: ended_us.is_some_and(|ended| ended >= last_us),
                    handed_off,
                });
            }
            Ok(out)
        })
        .await
    }

    #[allow(clippy::too_many_arguments)]
    pub(crate) async fn sessions_for_scope_filtered(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        owner_filter: OwnerFilter,
        include_open: bool,
        limit: usize,
        offset: usize,
        exact_session_id: Option<SessionId>,
        agent: Option<String>,
    ) -> StoreResult<Vec<SessionSummary>> {
        self.with_conn(move |conn| {
            let sql =
                sessions_for_scope_sql(exact_session_id.is_some(), &owner_filter, include_open);
            let sql = if agent.is_some() {
                sql.replace("WHERE 1 = 1", "WHERE s.agent_kind = :agent")
            } else {
                sql
            };
            let mut stmt = conn.prepare_cached(&sql)?;
            let ws_bytes = workspace_id.as_bytes();
            let proj_bytes = project_id.as_bytes();
            let limit = i64::try_from(limit).unwrap_or(i64::MAX);
            let offset = i64::try_from(offset).unwrap_or(i64::MAX);
            let sid_bytes = exact_session_id.map(|sid| *sid.as_bytes());
            let mut named: Vec<(&str, &dyn rusqlite::ToSql)> = vec![
                (":ws", &ws_bytes as &dyn rusqlite::ToSql),
                (":proj", &proj_bytes as &dyn rusqlite::ToSql),
                (":limit", &limit),
                (":offset", &offset),
            ];
            if let Some(sid) = &sid_bytes {
                named.push((":sid", sid));
            }
            if let Some(agent) = &agent {
                named.push((":agent", agent));
            }
            if let OwnerFilter::User(user) = &owner_filter {
                named.push((":actor", user));
            }
            let rows = stmt.query_map(named.as_slice(), |row| {
                let id_bytes: Vec<u8> = row.get(0)?;
                let cwd: Option<String> = row.get(1)?;
                let agent_kind: String = row.get(2)?;
                let started_us: i64 = row.get(3)?;
                let ended_us: Option<i64> = row.get(4)?;
                let actor_user: Option<String> = row.get(5)?;
                let n: i64 = row.get(6)?;
                let input_tokens: Option<i64> = row.get(7)?;
                let output_tokens: Option<i64> = row.get(8)?;
                let cache_write_tokens: Option<i64> = row.get(9)?;
                let cache_read_tokens: Option<i64> = row.get(10)?;
                let model: Option<String> = row.get(11)?;
                Ok((
                    id_bytes,
                    cwd,
                    agent_kind,
                    started_us,
                    ended_us,
                    actor_user,
                    n,
                    input_tokens,
                    output_tokens,
                    cache_write_tokens,
                    cache_read_tokens,
                    model,
                    row.get::<_, Option<String>>(12)?,
                    row.get::<_, Option<u32>>(13)?,
                ))
            })?;
            let mut out = Vec::new();
            for row in rows {
                let (
                    id_bytes,
                    cwd,
                    agent_kind,
                    started_us,
                    ended_us,
                    actor_user,
                    n,
                    input_tokens,
                    output_tokens,
                    cache_write_tokens,
                    cache_read_tokens,
                    model,
                    state,
                    attempts,
                ) = row?;
                let started_at = jiff::Timestamp::from_microsecond(started_us)
                    .map(|ts| ts.to_string())
                    .unwrap_or_default();
                let ended_at = ended_us
                    .and_then(|us| jiff::Timestamp::from_microsecond(us).ok())
                    .map(|ts| ts.to_string());
                // `input_tokens` alone stands in for "a usage row exists": the
                // LEFT JOIN yields all-NULL columns for a session with no
                // report, and every real row always carries this column
                // (defaulted to 0, never NULL) once `upsert_session_usage`
                // has run.
                let usage = input_tokens.map(|input_tokens| SessionUsageView {
                    input_tokens: u64::try_from(input_tokens).unwrap_or(0),
                    output_tokens: u64::try_from(output_tokens.unwrap_or(0)).unwrap_or(0),
                    cache_write_tokens: u64::try_from(cache_write_tokens.unwrap_or(0)).unwrap_or(0),
                    cache_read_tokens: u64::try_from(cache_read_tokens.unwrap_or(0)).unwrap_or(0),
                    model,
                });
                out.push(SessionSummary {
                    session_id: SessionId::from_slice(&id_bytes)?,
                    cwd,
                    agent_kind,
                    started_at,
                    usage,
                    ended_at,
                    observation_count: u64::try_from(n).unwrap_or(0),
                    actor_user,
                    consolidation: state
                        .zip(attempts)
                        .map(|(state, attempts)| SessionConsolidationSummary { state, attempts }),
                });
            }
            Ok(out)
        })
        .await
    }

    /// Whether LLM consolidation of the session's current observation
    /// generation is already running or finished. A redelivered checkpoint
    /// checks this before rewriting the rule-based page, so a retry that
    /// arrives after the worker finished cannot replace the LLM page it
    /// wrote.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn session_generation_consolidating_or_done(
        &self,
        session_id: SessionId,
    ) -> StoreResult<bool> {
        self.with_conn(move |conn| {
            Ok(conn.query_row(
                "SELECT EXISTS (SELECT 1 FROM session_consolidation_jobs \
                 WHERE session_id = ?1 AND state IN ('running', 'completed') \
                   AND generation = (SELECT COUNT(*) FROM observations WHERE session_id = ?1))",
                params![session_id.as_bytes()],
                |row| row.get::<_, bool>(0),
            )?)
        })
        .await
    }

    /// The `(workspace_id, project_id, cwd)` a session was created under,
    /// or `None` when no such session exists. The hook router uses this for
    /// session-sticky attribution: mid-session events inherit the session's
    /// scope instead of re-deriving a project from the event's cwd, so a
    /// `cd subdir/` inside a non-git project (whose parent has no
    /// `repo_path` for the prefix match to key on) can no longer scatter
    /// observations into basename-fragment projects. The session's own cwd
    /// is returned so the router can bound stickiness to the session's
    /// directory subtree.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn find_session_scope(
        &self,
        session_id: SessionId,
    ) -> StoreResult<Option<(WorkspaceId, ProjectId, Option<String>)>> {
        self.with_conn(move |conn| {
            let row = conn
                .query_row(
                    "SELECT workspace_id, project_id, cwd FROM sessions WHERE id = ?1",
                    params![session_id.as_bytes()],
                    |row| {
                        Ok((
                            row.get::<_, Vec<u8>>(0)?,
                            row.get::<_, Vec<u8>>(1)?,
                            row.get::<_, Option<String>>(2)?,
                        ))
                    },
                )
                .optional()?;
            match row {
                Some((ws, proj, cwd)) => Ok(Some((
                    WorkspaceId::from_slice(&ws)?,
                    ProjectId::from_slice(&proj)?,
                    cwd,
                ))),
                None => Ok(None),
            }
        })
        .await
    }

    /// The recorded `(workspace, project)` of a session that has not ended.
    /// A mid-session checkpoint writes its artifacts there, next to where the
    /// session's eventual end writes them, whatever scope the event resolved
    /// to.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn open_session_scope(
        &self,
        session_id: SessionId,
    ) -> StoreResult<Option<(WorkspaceId, ProjectId)>> {
        self.with_conn(move |conn| {
            let row = conn
                .query_row(
                    "SELECT workspace_id, project_id FROM sessions \
                     WHERE id = ?1 AND ended_at IS NULL",
                    params![session_id.as_bytes()],
                    |row| Ok((row.get::<_, Vec<u8>>(0)?, row.get::<_, Vec<u8>>(1)?)),
                )
                .optional()?;
            row.map(|(ws, proj)| Ok((WorkspaceId::from_slice(&ws)?, ProjectId::from_slice(&proj)?)))
                .transpose()
        })
        .await
    }

    /// Ids of every session that touches `(workspace_id, project_id)`: a
    /// `sessions` row in the scope OR at least one observation stamped into
    /// it. The second leg catches the phantom projects that mid-session
    /// routing before the sticky mode filled with observations of sessions
    /// rooted elsewhere (no `sessions` row of their own), so a batch
    /// `move-session` can empty such a bucket. Ordered by first touch (the
    /// row's `started_at` or the earliest observation in the scope), then id.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn session_ids_touching_scope(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> StoreResult<Vec<SessionId>> {
        self.with_conn(move |conn| {
            let mut stmt = conn.prepare(
                "SELECT id FROM ( \
                     SELECT id, started_at AS first_seen FROM sessions \
                     WHERE workspace_id = ?1 AND project_id = ?2 \
                     UNION ALL \
                     SELECT session_id AS id, MIN(created_at) AS first_seen FROM observations \
                     WHERE workspace_id = ?1 AND project_id = ?2 \
                     GROUP BY session_id \
                 ) \
                 GROUP BY id \
                 ORDER BY MIN(first_seen), id",
            )?;
            let rows = stmt.query_map(
                params![workspace_id.as_bytes(), project_id.as_bytes()],
                |row| row.get::<_, Vec<u8>>(0),
            )?;
            let mut out = Vec::new();
            for r in rows {
                out.push(SessionId::from_slice(&r?)?);
            }
            Ok(out)
        })
        .await
    }

    /// Rows keyed to a session across every scope, plus its
    /// `sessions/<id>.md` page rows in one scope: what a `move_session` into
    /// a scope that holds nothing of the session yet would touch. Used for
    /// the dry run of a move whose destination does not exist yet.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn session_dependent_rows(
        &self,
        session_id: SessionId,
        page_scope: (WorkspaceId, ProjectId),
    ) -> StoreResult<SessionDependentRows> {
        self.with_conn(move |conn| {
            let sid = session_id.as_bytes();
            let count = |sql: &str| -> StoreResult<u64> {
                Ok(conn.query_row(sql, [sid.as_slice()], |r| r.get::<_, i64>(0))? as u64)
            };
            let (page_versions, page_latest): (i64, i64) = conn.query_row(
                "SELECT COUNT(*), COALESCE(SUM(is_latest), 0) FROM pages \
                 WHERE workspace_id = ?1 AND project_id = ?2 AND path = ?3",
                params![
                    page_scope.0.as_bytes(),
                    page_scope.1.as_bytes(),
                    format!("sessions/{session_id}.md"),
                ],
                |r| Ok((r.get(0)?, r.get(1)?)),
            )?;
            Ok(SessionDependentRows {
                observations: count("SELECT COUNT(*) FROM observations WHERE session_id = ?1")?,
                handoffs: count("SELECT COUNT(*) FROM handoffs WHERE from_session_id = ?1")?,
                consolidation_jobs: count(
                    "SELECT COUNT(*) FROM session_consolidation_jobs WHERE session_id = ?1",
                )?,
                auto_improve_runs: count(
                    "SELECT COUNT(*) FROM auto_improve_runs WHERE session_id = ?1",
                )?,
                auto_improve_claims: count(
                    "SELECT COUNT(*) FROM auto_improve_scheduler_claims WHERE session_id = ?1",
                )?,
                page_versions: page_versions as u64,
                page_latest: page_latest as u64,
            })
        })
        .await
    }

    /// How a `SessionEnd` should treat its target session (issue #152).
    ///
    /// The old boolean ("is the session open?") conflated two very different
    /// ended states: a *duplicate/stale* end (the observation generation did
    /// not advance — drop it, the reason the guard exists) and a *re-end* of a
    /// resumed session (the agent reused the id and kept working after the
    /// first end — the end path must run again or the resumed work never
    /// reaches the compiled session page). A persisted count is deliberately
    /// used instead of comparing wall clocks, which does not converge after
    /// clock skew (issue #261).
    pub async fn session_end_disposition(
        &self,
        session_id: SessionId,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        agent_kind: AgentKind,
    ) -> StoreResult<SessionEndDisposition> {
        let agent = agent_kind.as_str().to_string();
        self.with_conn(move |conn| {
            let end_state: Option<(Option<i64>, u64)> = conn
                .query_row(
                    "SELECT ended_at, ended_observation_count FROM sessions \
                     WHERE id = ?1 AND workspace_id = ?2 AND project_id = ?3 \
                       AND agent_kind = ?4",
                    params![
                        session_id.as_bytes(),
                        workspace_id.as_bytes(),
                        project_id.as_bytes(),
                        agent,
                    ],
                    |row| Ok((row.get(0)?, row.get(1)?)),
                )
                .optional()?;
            let Some((ended_at, ended_observation_count)) = end_state else {
                // Missing, cross-scope, or cross-agent: never end it.
                return Ok(SessionEndDisposition::DropInvalid);
            };
            if ended_at.is_none() {
                return Ok(SessionEndDisposition::Open);
            }
            let current_observation_count: u64 = conn.query_row(
                "SELECT COUNT(*) FROM observations WHERE session_id = ?1",
                params![session_id.as_bytes()],
                |row| row.get(0),
            )?;
            if current_observation_count > ended_observation_count {
                Ok(SessionEndDisposition::ReEndWithNewWork)
            } else {
                Ok(SessionEndDisposition::AlreadyEnded)
            }
        })
        .await
    }

    /// Return completed sessions eligible for scheduled auto-improvement.
    ///
    /// The scheduler uses a persisted first-run watermark so an upgrade with an
    /// LLM provider configured does not chew through historical backlog by
    /// default. The scheduler inserts a per-session claim before the LLM call,
    /// so failed scheduled reviews do not retry forever or starve newer
    /// sessions. Any existing auto-improvement run row for a session also counts
    /// as a scheduler review for candidate selection; manual reruns remain
    /// available through CLI/admin/MCP.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn auto_improve_candidate_sessions(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        min_session_age_secs: u64,
        limit: usize,
    ) -> StoreResult<Vec<AutoImproveCandidateSession>> {
        let cutoff = Timestamp::now().as_microsecond().saturating_sub(
            (min_session_age_secs.min(i64::MAX as u64 / 1_000_000) as i64) * 1_000_000,
        );
        self.with_conn(move |conn| {
            let watermark: Option<i64> = conn
                .query_row(
                    "SELECT watermark_ended_at FROM auto_improve_scheduler_state \
                     WHERE workspace_id = ?1 AND project_id = ?2",
                    params![workspace_id.as_bytes(), project_id.as_bytes()],
                    |row| row.get(0),
                )
                .optional()?;
            let Some(watermark) = watermark else {
                return Ok(Vec::new());
            };

            let mut stmt = conn.prepare_cached(
                "SELECT s.id, s.ended_at FROM sessions s \
                 WHERE s.workspace_id = ?1 \
                   AND s.project_id = ?2 \
                   AND s.ended_at IS NOT NULL \
                   AND s.ended_at > ?3 \
                   AND s.ended_at <= ?4 \
                   AND NOT EXISTS ( \
                       SELECT 1 FROM auto_improve_scheduler_claims c \
                       WHERE c.workspace_id = s.workspace_id \
                         AND c.project_id = s.project_id \
                         AND c.session_id = s.id \
                         AND NOT ( \
                             c.last_failed_at IS NOT NULL \
                             AND c.attempts < ?6 \
                         ) \
                   ) \
                   AND NOT EXISTS ( \
                       SELECT 1 FROM auto_improve_runs r \
                       WHERE r.workspace_id = s.workspace_id \
                         AND r.project_id = s.project_id \
                         AND r.session_id = s.id \
                   ) \
                 ORDER BY s.ended_at ASC, s.started_at ASC \
                 LIMIT ?5",
            )?;
            let rows = stmt.query_map(
                params![
                    workspace_id.as_bytes(),
                    project_id.as_bytes(),
                    watermark,
                    cutoff,
                    limit.min(i64::MAX as usize) as i64,
                    crate::auto_improve::AUTO_IMPROVE_CLAIM_MAX_ATTEMPTS,
                ],
                |row| {
                    let id_bytes: Vec<u8> = row.get(0)?;
                    Ok((id_bytes, row.get::<_, i64>(1)?))
                },
            )?;
            let mut out = Vec::new();
            for row in rows {
                let (id_bytes, ended_at) = row?;
                out.push(AutoImproveCandidateSession {
                    session_id: SessionId::from_slice(&id_bytes)?,
                    ended_at,
                });
            }
            Ok(out)
        })
        .await
    }

    /// Scheduler claims that have spent every attempt and no longer produce a
    /// candidate, newest failure first.
    ///
    /// A parked claim is a session the scheduler has given up on. It is excluded
    /// from `auto_improve_candidate_sessions` exactly like an in-flight claim,
    /// so without this listing the two are indistinguishable from outside the
    /// database — which is what made the original leak silent (#833).
    ///
    /// # Errors
    /// Returns an error when the underlying SQLite statement fails.
    pub async fn auto_improve_parked_claims(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> StoreResult<Vec<AutoImproveParkedClaim>> {
        self.with_conn(move |conn| {
            let mut stmt = conn.prepare_cached(
                "SELECT session_id, attempts, last_error, last_failed_at \
                 FROM auto_improve_scheduler_claims \
                 WHERE workspace_id = ?1 AND project_id = ?2 AND attempts >= ?3 \
                 ORDER BY last_failed_at DESC",
            )?;
            let rows = stmt.query_map(
                params![
                    workspace_id.as_bytes(),
                    project_id.as_bytes(),
                    crate::auto_improve::AUTO_IMPROVE_CLAIM_MAX_ATTEMPTS,
                ],
                |row| {
                    Ok((
                        row.get::<_, Vec<u8>>(0)?,
                        row.get::<_, u32>(1)?,
                        row.get::<_, Option<String>>(2)?,
                        row.get::<_, Option<i64>>(3)?,
                    ))
                },
            )?;
            let mut out = Vec::new();
            for row in rows {
                let (id_bytes, attempts, last_error, last_failed_at) = row?;
                out.push(AutoImproveParkedClaim {
                    session_id: SessionId::from_slice(&id_bytes)?,
                    attempts,
                    last_error,
                    last_failed_at,
                });
            }
            Ok(out)
        })
        .await
    }

    /// Look up the `(workspace_id, project_id)` a session belongs to.
    /// Returns `None` when no such session row exists.
    ///
    /// Used by the consolidator + lint pass to write pages into the
    /// SESSION'S project, not the server's startup defaults — every
    /// session row carries the project_id the hook router resolved
    /// from its per-cwd basename heuristic, which is the correct
    /// target for any wiki page derived from that session.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn session_project_ids(
        &self,
        session_id: SessionId,
    ) -> StoreResult<Option<(WorkspaceId, ProjectId)>> {
        self.with_conn(move |conn| {
            let mut stmt =
                conn.prepare("SELECT workspace_id, project_id FROM sessions WHERE id = ?1")?;
            let mut rows = stmt.query(params![session_id.as_bytes()])?;
            let Some(row) = rows.next()? else {
                return Ok(None);
            };
            let ws_bytes: Vec<u8> = row.get(0)?;
            let proj_bytes: Vec<u8> = row.get(1)?;
            let ws = WorkspaceId::from_slice(&ws_bytes)
                .map_err(|_| rusqlite::Error::IntegralValueOutOfRange(0, 0))?;
            let proj = ProjectId::from_slice(&proj_bytes)
                .map_err(|_| rusqlite::Error::IntegralValueOutOfRange(1, 0))?;
            Ok(Some((ws, proj)))
        })
        .await
    }

    /// Look up the immutable harness identity stored for a session.
    ///
    /// Machine-generated session pages use this as their origin metadata.
    /// Reading it from the session row, rather than from the request that
    /// happens to trigger consolidation, keeps spool drains and later
    /// superseding writes attributed to the harness that created the session.
    /// Returns `None` when no such session row exists.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn session_agent_kind(
        &self,
        session_id: SessionId,
    ) -> StoreResult<Option<AgentKind>> {
        self.with_conn(move |conn| {
            let stored: Option<String> = conn
                .query_row(
                    "SELECT agent_kind FROM sessions WHERE id = ?1",
                    params![session_id.as_bytes()],
                    |row| row.get(0),
                )
                .optional()?;
            Ok(stored.map(|value| AgentKind::from_wire(&value)))
        })
        .await
    }

    /// The operator a session belongs to (an
    /// [`ai_memory_core::IdentityKey::storage_key`] string), as recorded at
    /// session start.
    ///
    /// The identity carrying a SessionEnd is not necessarily the identity that
    /// owned the session: a spool drain, an operator finalizing a stuck
    /// session, or a shared static hook token can all deliver it. Attribution
    /// for the session's page and the baton it leaves must follow the session,
    /// not the request.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn session_actor_user(&self, session_id: SessionId) -> StoreResult<Option<String>> {
        self.with_conn(move |conn| {
            let owner: Option<Option<String>> = conn
                .query_row(
                    "SELECT actor_user FROM sessions WHERE id = ?1",
                    params![session_id.as_bytes()],
                    |row| row.get(0),
                )
                .optional()?;
            Ok(owner.flatten())
        })
        .await
    }

    /// Open sessions whose last activity is older than `cutoff_us`, for the
    /// server-side idle auto-end tick.
    ///
    /// "Last activity" is `MAX(observations.created_at)` — the same fact the
    /// end's audit preserves (`last_activity_us` detail; `ended_at` itself is
    /// the tick's clock) — falling back to `started_at` for a session that
    /// began but never captured an observation. Sessions without the
    /// `ended_at IS NULL` shape are never returned, so the result is a
    /// re-check-free candidate list: the end itself still guards with its own
    /// `ended_at IS NULL` CAS in the writer.
    ///
    /// `seen_page_id` captures the latest `sessions/<id>.md` version in the
    /// SAME STATEMENT as the session row (a correlated subquery over `pages`,
    /// so one atomic SELECT cannot observe a page a real `SessionEnd`
    /// publishes after the session row was read): the tick's conditional page
    /// write takes it as its precondition and cannot supersede a page the
    /// hook delivered between the selection and the tick's write. The path is
    /// rendered in SQL from the id blob (see the query below); the selection
    /// test proves it byte-for-byte against the Rust-rendered path.
    ///
    /// Ordered by last activity (oldest first) and bounded by `limit`, so one
    /// tick ends a bounded batch and the next picks up the rest.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn idle_open_sessions(
        &self,
        cutoff_us: i64,
        limit: usize,
    ) -> StoreResult<Vec<IdleOpenSession>> {
        self.with_conn(move |conn| {
            // ONE statement: the correlated subquery reads each session page
            // from the same atomic snapshot as the session row, so the tick's
            // precondition can never be a page version it never saw.
            //
            // The page path is rendered in SQL because `sessions.id` is the
            // 16-byte UUID blob while `pages.path` is text: `lower(hex(s.id))`
            // is the UUID's canonical hyphenless hex in the same lowercase
            // letters `SessionId`'s `Display` prints, and the substr pieces
            // reinsert the 8-4-4-4-12 hyphens. The result is byte-for-byte the
            // Rust `format!("sessions/{session_id}.md")` — the selection test
            // proves it with a page present (captured) and absent (not), so a
            // rendering drift would stall the session, never compare against a
            // guessed path.
            let mut stmt = conn.prepare(
                "SELECT s.id, s.workspace_id, s.project_id, s.agent_kind, s.cwd, s.actor_user, \
             s.started_at, COALESCE( \
                 (SELECT MAX(o.created_at) FROM observations o \
                  WHERE o.session_id = s.id), \
                 s.started_at) AS last_activity, \
                 (SELECT p.id FROM pages p \
                  WHERE p.workspace_id = s.workspace_id \
                    AND p.project_id = s.project_id \
                    AND p.is_latest = 1 \
                    AND p.path = 'sessions/' || substr(lower(hex(s.id)), 1, 8) || '-' || \
                                       substr(lower(hex(s.id)), 9, 4) || '-' || \
                                       substr(lower(hex(s.id)), 13, 4) || '-' || \
                                       substr(lower(hex(s.id)), 17, 4) || '-' || \
                                       substr(lower(hex(s.id)), 21, 12) || '.md') \
             FROM sessions s \
             WHERE s.ended_at IS NULL \
               AND COALESCE( \
                     (SELECT MAX(o.created_at) FROM observations o \
                      WHERE o.session_id = s.id), \
                     s.started_at) < ?1 \
             ORDER BY last_activity ASC, s.id ASC \
             LIMIT ?2",
            )?;
            let rows = stmt
                .query_map(params![cutoff_us, limit as i64], |row| {
                    Ok((
                        row.get::<_, Vec<u8>>(0)?,
                        row.get::<_, Vec<u8>>(1)?,
                        row.get::<_, Vec<u8>>(2)?,
                        row.get::<_, String>(3)?,
                        row.get::<_, Option<String>>(4)?,
                        row.get::<_, Option<String>>(5)?,
                        row.get::<_, i64>(6)?,
                        row.get::<_, i64>(7)?,
                        row.get::<_, Option<Vec<u8>>>(8)?,
                    ))
                })?
                .collect::<Result<Vec<_>, _>>()?;
            let mut out = Vec::with_capacity(rows.len());
            for (
                id,
                workspace_id,
                project_id,
                agent_kind,
                cwd,
                actor_user,
                started_at,
                last_activity_us,
                page_id,
            ) in rows
            {
                let session_id = SessionId::from_slice(&id)?;
                let workspace_id = WorkspaceId::from_slice(&workspace_id)?;
                let project_id = ProjectId::from_slice(&project_id)?;
                let seen_page_id = page_id
                    .as_ref()
                    .map(|bytes| PageId::from_slice(bytes))
                    .transpose()?;
                out.push(IdleOpenSession {
                    session_id,
                    workspace_id,
                    project_id,
                    agent_kind: AgentKind::from_wire(&agent_kind),
                    cwd,
                    actor_user,
                    started_at,
                    last_activity_us,
                    seen_page_id,
                });
            }
            Ok(out)
        })
        .await
    }

    /// Native session ids bound to `managed_runs` rows still in state
    /// `active`, for the idle auto-end tick's exclusion: a live managed run
    /// (`ai-memory run`) owns its native session's lifecycle, so the tick
    /// must not end it even when the session row looks idle.
    ///
    /// The join is done in Rust, not SQL: `managed_runs.native_session_id`
    /// holds the harness's native id string while `sessions.id` is the
    /// derived UUIDv7 blob, so the two columns never compare equal in SQL.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn active_managed_run_native_session_ids(&self) -> StoreResult<Vec<String>> {
        self.with_conn(|conn| {
            let mut stmt = conn.prepare(
                "SELECT native_session_id FROM managed_runs \
                 WHERE state = 'active' AND native_session_id IS NOT NULL",
            )?;
            let ids = stmt
                .query_map([], |row| row.get::<_, String>(0))?
                .collect::<Result<Vec<_>, _>>()?;
            Ok(ids)
        })
        .await
    }

    /// Resolve the `(workspace, project)` where a session's observations
    /// actually landed, independent of the (possibly stale) `sessions` row.
    ///
    /// The `sessions` row is frozen at the first session-start (`begin_session`
    /// uses `ON CONFLICT(id) DO NOTHING`), so a "hybrid" session that installed
    /// its scope marker mid-flight stays anchored to the pre-marker scope. The
    /// observation log, in contrast, carries the correct per-cwd scope for each
    /// captured event. Returns the scope holding the most observations for the
    /// session (ties broken by the most recent observation), or `None` when the
    /// session has no observations.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn session_scope_from_observations(
        &self,
        session_id: SessionId,
    ) -> StoreResult<Option<(WorkspaceId, ProjectId)>> {
        self.with_conn(move |conn| {
            let mut stmt = conn.prepare_cached(
                "SELECT workspace_id, project_id \
                 FROM observations \
                 WHERE session_id = ?1 \
                 GROUP BY workspace_id, project_id \
                 ORDER BY COUNT(*) DESC, MAX(created_at) DESC \
                 LIMIT 1",
            )?;
            let mut rows = stmt.query(params![session_id.as_bytes()])?;
            let Some(row) = rows.next()? else {
                return Ok(None);
            };
            let ws_bytes: Vec<u8> = row.get(0)?;
            let proj_bytes: Vec<u8> = row.get(1)?;
            let ws = WorkspaceId::from_slice(&ws_bytes).map_err(|e| {
                StoreError::Memory(ai_memory_core::MemoryError::MalformedRecord(format!(
                    "bad observation workspace_id: {e}"
                )))
            })?;
            let proj = ProjectId::from_slice(&proj_bytes).map_err(|e| {
                StoreError::Memory(ai_memory_core::MemoryError::MalformedRecord(format!(
                    "bad observation project_id: {e}"
                )))
            })?;
            Ok(Some((ws, proj)))
        })
        .await
    }

    /// Load every `is_latest=1` page's embedding for the project, but
    /// only when the stored `(provider, model, dim)` matches the
    /// caller's expectation. Mismatched rows are skipped (the
    /// refuse-on-mismatch check is `embedding_meta_for_mismatch`).
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn load_embeddings(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        provider: String,
        model: String,
        dim: u32,
    ) -> StoreResult<Vec<StoredEmbedding>> {
        self.with_conn(move |conn| {
            let mut stmt = conn.prepare_cached(
                "SELECT page_embeddings.page_id, page_embeddings.vector, pages.path \
                 FROM page_embeddings \
                 JOIN pages ON pages.id = page_embeddings.page_id \
                 WHERE pages.workspace_id = ?1 \
                   AND pages.project_id = ?2 \
                   AND pages.is_latest = 1 \
                   AND page_embeddings.provider = ?3 \
                   AND page_embeddings.model = ?4 \
                   AND page_embeddings.dim = ?5",
            )?;
            let rows = stmt.query_map(
                params![
                    workspace_id.as_bytes(),
                    project_id.as_bytes(),
                    provider,
                    model,
                    dim,
                ],
                |row| {
                    let id_bytes: Vec<u8> = row.get(0)?;
                    let vec_bytes: Vec<u8> = row.get(1)?;
                    let path: String = row.get(2)?;
                    Ok((id_bytes, vec_bytes, path))
                },
            )?;
            let mut out = Vec::new();
            for r in rows {
                let (id_bytes, vec_bytes, path) = r?;
                let id = PageId::from_slice(&id_bytes)?;
                let path = PagePath::new(path)?;
                let vector = bytes_to_f32_vec(&vec_bytes, dim)?;
                out.push(StoredEmbedding { id, path, vector });
            }
            Ok(out)
        })
        .await
    }

    /// Return page ids that already have a matching embedding row.
    ///
    /// This is cheaper than [`ReaderPool::load_embeddings`] for backfill paths
    /// that only need to skip already-embedded pages.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn embedded_page_ids(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        provider: String,
        model: String,
        dim: u32,
    ) -> StoreResult<Vec<PageId>> {
        self.embedded_page_ids_in_table(
            EmbeddingTable::Body,
            workspace_id,
            project_id,
            provider,
            model,
            dim,
        )
        .await
    }

    /// Page ids whose L0 abstract already has a matching embedding row
    /// (`page_abstract_embeddings`). The backfill uses it to skip pages
    /// whose abstract is already indexed under the current triple.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn abstract_embedded_page_ids(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        provider: String,
        model: String,
        dim: u32,
    ) -> StoreResult<Vec<PageId>> {
        self.embedded_page_ids_in_table(
            EmbeddingTable::Abstract,
            workspace_id,
            project_id,
            provider,
            model,
            dim,
        )
        .await
    }

    /// Latest pages of a project whose frontmatter carries a non-empty
    /// `abstract` string — the only pages the L0 stream can index. Lets the
    /// backfill decide without reading every page off disk.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn abstract_bearing_page_ids(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> StoreResult<Vec<PageId>> {
        self.with_conn(move |conn| {
            let mut stmt = conn.prepare_cached(
                "SELECT pages.id \
                 FROM pages \
                 WHERE pages.workspace_id = ?1 \
                   AND pages.project_id = ?2 \
                   AND pages.is_latest = 1 \
                   AND json_type(pages.frontmatter_json, '$.abstract') = 'text' \
                   AND length(trim(json_extract(pages.frontmatter_json, '$.abstract'))) > 0",
            )?;
            let rows = stmt.query_map(
                params![workspace_id.as_bytes(), project_id.as_bytes()],
                |row| {
                    let id_bytes: Vec<u8> = row.get(0)?;
                    Ok(id_bytes)
                },
            )?;
            let mut out = Vec::new();
            for row in rows {
                out.push(PageId::from_slice(&row?)?);
            }
            Ok(out)
        })
        .await
    }

    async fn embedded_page_ids_in_table(
        &self,
        table: EmbeddingTable,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        provider: String,
        model: String,
        dim: u32,
    ) -> StoreResult<Vec<PageId>> {
        let table = table.name();
        self.with_conn(move |conn| {
            let sql = format!(
                "SELECT {table}.page_id \
                 FROM {table} \
                 JOIN pages ON pages.id = {table}.page_id \
                 WHERE pages.workspace_id = ?1 \
                   AND pages.project_id = ?2 \
                   AND pages.is_latest = 1 \
                   AND {table}.provider = ?3 \
                   AND {table}.model = ?4 \
                   AND {table}.dim = ?5"
            );
            let mut stmt = conn.prepare_cached(&sql)?;
            let rows = stmt.query_map(
                params![
                    workspace_id.as_bytes(),
                    project_id.as_bytes(),
                    provider,
                    model,
                    dim,
                ],
                |row| {
                    let id_bytes: Vec<u8> = row.get(0)?;
                    Ok(id_bytes)
                },
            )?;
            let mut out = Vec::new();
            for row in rows {
                out.push(PageId::from_slice(&row?)?);
            }
            Ok(out)
        })
        .await
    }

    #[allow(clippy::too_many_arguments)]
    async fn top_embedding_hits_for_project(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        query_vec: Vec<f32>,
        provider: String,
        model: String,
        dim: u32,
        limit: usize,
        expiry_cutoff_us: i64,
        include_superseded: bool,
        filter: PageFilter<'_>,
    ) -> StoreResult<Vec<(PageId, PagePath, f32)>> {
        self.top_embedding_hits_in_table(
            EmbeddingTable::Body,
            workspace_id,
            project_id,
            query_vec,
            provider,
            model,
            dim,
            limit,
            expiry_cutoff_us,
            include_superseded,
            filter,
        )
        .await
    }

    /// Cosine top-`limit` over one embedding table for the latest, unexpired
    /// pages of a project. The body and L0-abstract tables share a schema,
    /// so the scan differs only in which table it reads.
    #[allow(clippy::too_many_arguments)]
    async fn top_embedding_hits_in_table(
        &self,
        table: EmbeddingTable,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        query_vec: Vec<f32>,
        provider: String,
        model: String,
        dim: u32,
        limit: usize,
        expiry_cutoff_us: i64,
        include_superseded: bool,
        filter: PageFilter<'_>,
    ) -> StoreResult<Vec<(PageId, PagePath, f32)>> {
        if limit == 0 {
            return Ok(Vec::new());
        }
        let table = table.name();
        let (kept, kept_params) = filter.sql("pages", numbered_placeholders(7));
        self.with_conn(move |conn| {
            let sql = format!(
                "SELECT {table}.page_id, {table}.vector, pages.path \
                 FROM {table} \
                 JOIN pages ON pages.id = {table}.page_id \
                 WHERE pages.workspace_id = ?1 \
                   AND pages.project_id = ?2{latest}{not_expired}{kept} \
                   AND {table}.provider = ?3 \
                   AND {table}.model = ?4 \
                   AND {table}.dim = ?5",
                latest = latest_only("pages", include_superseded),
                not_expired = not_expired("pages", "?6"),
            );
            let mut stmt = conn.prepare_cached(&sql)?;
            let mut bound = vec![
                Value::Blob(workspace_id.as_bytes().to_vec()),
                Value::Blob(project_id.as_bytes().to_vec()),
                Value::Text(provider),
                Value::Text(model),
                Value::Integer(i64::from(dim)),
                Value::Integer(expiry_cutoff_us),
            ];
            bound.extend(kept_params);
            let rows = stmt.query_map(params_from_iter(bound.iter()), |row| {
                let id_bytes: Vec<u8> = row.get(0)?;
                let vec_bytes: Vec<u8> = row.get(1)?;
                let path: String = row.get(2)?;
                Ok((id_bytes, vec_bytes, path))
            })?;

            let mut out = Vec::new();
            for row in rows {
                let (id_bytes, vec_bytes, path) = row?;
                out.push((
                    PageId::from_slice(&id_bytes)?,
                    PagePath::new(path)?,
                    dot_embedding_bytes(&query_vec, &vec_bytes, dim)?,
                ));
            }
            if out.len() > limit {
                out.select_nth_unstable_by(limit, score_desc);
                out.truncate(limit);
            }
            out.sort_by(score_desc);
            Ok(out)
        })
        .await
    }

    /// Return any `(provider, model, dim)` triples currently stored
    /// that *don't* match the caller's expectation. An empty vec
    /// means "all clean". Used at startup for the refuse-on-mismatch
    /// (agentmemory #469 lesson).
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn embedding_meta_for_mismatch(
        &self,
        provider: String,
        model: String,
        dim: u32,
    ) -> StoreResult<Vec<(String, String, u32, u64)>> {
        self.with_conn(move |conn| {
            let mut stmt = conn.prepare(
                "SELECT pe.provider, pe.model, pe.dim, COUNT(*) \
                 FROM page_embeddings pe \
                 JOIN pages pg ON pg.id = pe.page_id AND pg.is_latest = 1 \
                 WHERE NOT (pe.provider = ?1 AND pe.model = ?2 AND pe.dim = ?3) \
                 GROUP BY pe.provider, pe.model, pe.dim",
            )?;
            let rows = stmt.query_map(params![provider, model, dim], |row| {
                let provider: String = row.get(0)?;
                let model: String = row.get(1)?;
                let dim: i64 = row.get(2)?;
                let count: i64 = row.get(3)?;
                Ok((
                    provider,
                    model,
                    u32::try_from(dim).unwrap_or(0),
                    u64::try_from(count).unwrap_or(0),
                ))
            })?;
            let mut out = Vec::new();
            for r in rows {
                out.push(r?);
            }
            Ok(out)
        })
        .await
    }

    /// Return decay-evaluation candidates for the M8 forget sweep.
    ///
    /// Walks `pages` rows with `is_latest = 1` and returns the columns
    /// the forget sweep needs to compute the retention formula. The
    /// sweep itself filters by tier (only `episodic`) + pinned flag,
    /// so this method does not pre-filter -- it just hands the data
    /// over.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn decay_candidates(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> StoreResult<Vec<DecayCandidate>> {
        self.with_conn(move |conn| {
            let mut stmt = conn.prepare(
                "SELECT id, path, tier, pinned, updated_at, access_count, last_accessed_at, \
                        frontmatter_json, expires_at, salience, compacted_at \
                 FROM pages \
                 WHERE workspace_id = ?1 AND project_id = ?2 AND is_latest = 1",
            )?;
            let rows = stmt.query_map(
                params![workspace_id.as_bytes(), project_id.as_bytes()],
                row_to_decay_candidate,
            )?;
            let mut out = Vec::new();
            for r in rows {
                out.push(r??);
            }
            Ok(out)
        })
        .await
    }

    /// Return `(PageId, PagePath)` for every `is_latest = 1` page under a
    /// scope, cheaper than [`decay_candidates`](Self::decay_candidates) when
    /// only identity is needed. Used by the watcher's reconcile-delete
    /// safety net (#929) to snapshot the store's view of "pages that should
    /// have a file on disk" before walking the tree, so a page written via
    /// the API mid-walk is never mistaken for one the walk simply hasn't
    /// reached yet.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn latest_page_ids(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> StoreResult<Vec<(PageId, PagePath)>> {
        self.with_conn(move |conn| {
            let mut stmt = conn.prepare(
                "SELECT id, path FROM pages \
                 WHERE workspace_id = ?1 AND project_id = ?2 AND is_latest = 1",
            )?;
            let rows = stmt.query_map(
                params![workspace_id.as_bytes(), project_id.as_bytes()],
                |row| Ok((row.get::<_, Vec<u8>>(0)?, row.get::<_, String>(1)?)),
            )?;
            let mut out = Vec::new();
            for row in rows {
                let (id, path) = row?;
                out.push((PageId::from_slice(&id)?, PagePath::new(path)?));
            }
            Ok(out)
        })
        .await
    }

    /// Return decay tombstones old enough for permanent cleanup.
    ///
    /// `superseded_at` is written by the forget-sweep eviction path AND by
    /// the watcher's opt-in reconcile-delete safety net (#929) — the two are
    /// deliberately indistinguishable here (docs/okf.md), so it remains the
    /// tombstone discriminator regardless of whether a rewritten page head
    /// also has a `supersedes` ancestor. A tombstone whose path was rewritten
    /// after it was marked (the false-positive self-healing, or an ordinary
    /// decay-then-recreate) has its `superseded_at` cleared by
    /// `ops::upsert_page_in_tx`'s resurrection path and so drops out of this
    /// query — only a chain with no successor ever reaches here. The caller
    /// still routes each result through the wiki layer before deleting its
    /// version chain.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn decay_tombstones_before(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        cutoff_us: i64,
    ) -> StoreResult<Vec<DecayTombstone>> {
        self.with_conn(move |conn| {
            let mut stmt = conn.prepare(
                "SELECT id, path FROM pages \
                 WHERE workspace_id = ?1 AND project_id = ?2 \
                   AND is_latest = 0 \
                   AND superseded_at IS NOT NULL \
                   AND superseded_at <= ?3 \
                 ORDER BY superseded_at, id",
            )?;
            let rows = stmt.query_map(
                params![workspace_id.as_bytes(), project_id.as_bytes(), cutoff_us],
                |row| Ok((row.get::<_, Vec<u8>>(0)?, row.get::<_, String>(1)?)),
            )?;
            let mut out = Vec::new();
            for row in rows {
                let (id, path) = row?;
                out.push(DecayTombstone {
                    id: PageId::from_slice(&id)?,
                    path: PagePath::new(path)?,
                });
            }
            Ok(out)
        })
        .await
    }

    /// Count the observations the prune pass would delete for this scope.
    ///
    /// Same predicate as
    /// [`prune_consolidated_observations`](crate::ops::prune_consolidated_observations),
    /// read-only, so a dry run can report a number without any chance of a
    /// write. Kept beside the delete rather than derived from it because the
    /// dry run must never open a write transaction at all. The
    /// active-work exclusion is the shared fragment
    /// `OBSERVATION_PRUNE_SESSION_GUARD_SQL` (interpolated here and in the
    /// delete), so a dry run can never report rows the real pass would keep,
    /// or miss rows it would delete for the same snapshot.
    ///
    /// # Errors
    /// Propagates SQL errors.
    pub async fn prunable_observation_count(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        cutoff_us: i64,
    ) -> StoreResult<usize> {
        self.with_conn(move |conn| {
            let guard = crate::ops::OBSERVATION_PRUNE_SESSION_GUARD_SQL;
            let sql = format!(
                "WITH candidate_sessions AS ( \
                     SELECT DISTINCT session_id FROM observations \
                     WHERE workspace_id = ?1 AND project_id = ?2 AND created_at < ?3 \
                 ), eligible_sessions AS MATERIALIZED ( \
                     SELECT s.id FROM candidate_sessions candidate \
                     JOIN sessions s ON s.id = candidate.session_id \
                     JOIN pages p ON p.id = s.summary_page_id \
                     WHERE p.superseded_at IS NULL AND {guard} \
                 ) \
                 SELECT COUNT(*) FROM observations o \
                 JOIN eligible_sessions eligible ON eligible.id = o.session_id \
                 WHERE o.workspace_id = ?1 \
                   AND o.project_id = ?2 \
                   AND o.created_at < ?3"
            );
            let n: i64 = conn.query_row(
                &sql,
                params![workspace_id.as_bytes(), project_id.as_bytes(), cutoff_us],
                |row| row.get(0),
            )?;
            Ok(usize::try_from(n).unwrap_or(0))
        })
        .await
    }

    /// Return the number of DISTINCT operators that reinforced each
    /// `is_latest = 1` page of a project, for the sweep's breadth term.
    ///
    /// Scoped and grouped exactly like [`decay_candidates`](Self::decay_candidates)
    /// so the sweep pays for one query per run, never one per candidate. Pages
    /// with no per-operator rows (everything read anonymously, and everything
    /// that predates `page_access`) are simply absent from the map, which the
    /// caller reads as breadth 0 — scored identically to breadth 1 by
    /// [`retention_score_with_breadth`](crate::retention_score_with_breadth).
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn access_breadth_for_project(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> StoreResult<std::collections::HashMap<PageId, u32>> {
        self.with_conn(move |conn| {
            let mut stmt = conn.prepare(
                "SELECT pa.page_id, COUNT(*) \
                 FROM page_access pa \
                 JOIN pages p ON p.id = pa.page_id \
                 WHERE p.workspace_id = ?1 AND p.project_id = ?2 AND p.is_latest = 1 \
                 GROUP BY pa.page_id",
            )?;
            let rows = stmt.query_map(
                params![workspace_id.as_bytes(), project_id.as_bytes()],
                |row| {
                    let id: Vec<u8> = row.get(0)?;
                    let actors: i64 = row.get(1)?;
                    Ok((id, u32::try_from(actors).unwrap_or(u32::MAX)))
                },
            )?;
            let mut out = std::collections::HashMap::new();
            for r in rows {
                let (id, actors) = r?;
                out.insert(PageId::from_slice(&id)?, actors);
            }
            Ok(out)
        })
        .await
    }

    /// Batched belief-strength inputs for each of `page_ids` (P2,
    /// docs/design-hindsight-borrowings.md §3): the evidence aggregate and the
    /// live-contradiction count that [`crate::belief::confidence`] needs.
    ///
    /// Two fixed batch queries for the whole result page — never one per hit
    /// (invariant #2). Only called when the belief signal is needed (an
    /// explained query, or the belief-authority weight is on), so the hot,
    /// non-explained default path pays nothing. A page id with no evidence rows
    /// is absent from the map; the caller reads that as
    /// [`BeliefInputs::default`] (confidence 0, i.e. no ranking effect).
    ///
    /// `distinct_sessions` counts distinct `source_id`s over the `session` and
    /// `reconsolidation` kinds — the breadth signal — and `newest_evidence_us`
    /// is `MAX(created_at)`. The contradiction count is the number of
    /// `contradicts` edges the page declares whose target resolves to a *live*
    /// (latest unexpired) page; a stale (dangling or expired) contradiction does
    /// not weaken the belief, matching the lint's resolved/stale split.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn page_belief_inputs(
        &self,
        page_ids: &[PageId],
    ) -> StoreResult<std::collections::HashMap<PageId, crate::belief::BeliefInputs>> {
        if page_ids.is_empty() {
            return Ok(std::collections::HashMap::new());
        }
        let page_id_blobs: Vec<Value> = page_ids
            .iter()
            .map(|id| Value::Blob(id.as_bytes().to_vec()))
            .collect();
        self.with_conn(move |conn| {
            let placeholders = std::iter::repeat_n("?", page_id_blobs.len())
                .collect::<Vec<_>>()
                .join(", ");
            let mut out: std::collections::HashMap<PageId, crate::belief::BeliefInputs> =
                std::collections::HashMap::new();

            // Evidence aggregate: total rows, distinct supporting sessions, and
            // the newest sighting, in one grouped pass.
            let evidence_sql = format!(
                "SELECT page_id, COUNT(*), \
                        COUNT(DISTINCT CASE WHEN source_kind IN ('session','reconsolidation') \
                                            THEN source_id END), \
                        MAX(created_at) \
                 FROM page_evidence \
                 WHERE page_id IN ({placeholders}) GROUP BY page_id"
            );
            let mut stmt = conn.prepare(&evidence_sql)?;
            let rows = stmt.query_map(params_from_iter(page_id_blobs.iter()), |row| {
                let id: Vec<u8> = row.get(0)?;
                let count: i64 = row.get(1)?;
                let distinct: i64 = row.get(2)?;
                let newest: Option<i64> = row.get(3)?;
                Ok((id, count, distinct, newest))
            })?;
            for r in rows {
                let (id, count, distinct, newest) = r?;
                out.insert(
                    PageId::from_slice(&id)?,
                    crate::belief::BeliefInputs {
                        evidence_count: u32::try_from(count).unwrap_or(u32::MAX),
                        distinct_sessions: u32::try_from(distinct).unwrap_or(u32::MAX),
                        newest_evidence_us: newest,
                        unresolved_contradictions: 0,
                    },
                );
            }

            // Live contradictions each page declares. Only edges whose target
            // resolves to a latest unexpired page count — a dangling or
            // expired `contradicts` is stale, not an active disagreement
            // (mirrors the lint split).
            let now = now_us();
            let to_ttl = not_expired("tp", "?");
            let contradiction_sql = format!(
                "SELECT l.from_page_id, COUNT(*) \
                 FROM links l \
                 JOIN pages tp ON tp.id = l.to_page_id AND tp.is_latest = 1{to_ttl} \
                 WHERE l.link_type = 'contradicts' \
                   AND l.from_page_id IN ({placeholders}) \
                 GROUP BY l.from_page_id"
            );
            let mut stmt = conn.prepare(&contradiction_sql)?;
            let now_val = Value::Integer(now);
            let rows = stmt.query_map(
                params_from_iter(std::iter::once(&now_val).chain(page_id_blobs.iter())),
                |row| {
                    let id: Vec<u8> = row.get(0)?;
                    let n: i64 = row.get(1)?;
                    Ok((id, n))
                },
            )?;
            for r in rows {
                let (id, n) = r?;
                let entry = out.entry(PageId::from_slice(&id)?).or_default();
                entry.unresolved_contradictions = u32::try_from(n).unwrap_or(u32::MAX);
            }

            Ok(out)
        })
        .await
    }

    /// Best-effort harness attribution for the web UI: for every
    /// `is_latest = 1` page in scope, the [`AgentKind`] of the most
    /// recently cited session in its `page_evidence` (P2, kind
    /// `'session'`). Pages with no session evidence — hand-written pages,
    /// or writes from before the P2 evidence substrate shipped — are
    /// simply absent from the map, the same "unknown, not unsupported"
    /// convention as [`Self::page_evidence_counts`].
    ///
    /// Two queries total regardless of page count: evidence rows for the
    /// scope, then one batched `sessions` lookup for the distinct session
    /// ids involved. A malformed session id (evidence is only ever written
    /// by us) or a session row that no longer exists is skipped rather than
    /// failing the whole call — this is decorative UI metadata, not a
    /// correctness-critical read.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn latest_page_agent_kinds(
        &self,
        workspace: &str,
        project: &str,
    ) -> StoreResult<std::collections::HashMap<String, AgentKind>> {
        let workspace = workspace.to_owned();
        let project = project.to_owned();
        let evidence_rows: Vec<(String, String, i64)> = self
            .with_conn(move |conn| {
                let mut stmt = conn.prepare(
                    "SELECT pg.path, pe.source_id, pe.created_at \
                     FROM pages pg \
                     JOIN page_evidence pe ON pe.page_id = pg.id AND pe.source_kind = 'session' \
                     JOIN projects p ON p.id = pg.project_id \
                     JOIN workspaces w ON w.id = pg.workspace_id \
                     WHERE w.name = ?1 AND p.name = ?2 AND pg.is_latest = 1",
                )?;
                let rows = stmt.query_map(params![workspace, project], |row| {
                    Ok((
                        row.get::<_, String>(0)?,
                        row.get::<_, String>(1)?,
                        row.get::<_, i64>(2)?,
                    ))
                })?;
                rows.collect::<rusqlite::Result<Vec<_>>>()
                    .map_err(StoreError::from)
            })
            .await?;

        let mut latest_session_by_path: std::collections::HashMap<String, (SessionId, i64)> =
            std::collections::HashMap::new();
        for (path, session_id_str, created_at) in evidence_rows {
            let Ok(session_id) = SessionId::from_str(&session_id_str) else {
                continue;
            };
            latest_session_by_path
                .entry(path)
                .and_modify(|(existing_id, existing_at)| {
                    if created_at > *existing_at {
                        *existing_id = session_id;
                        *existing_at = created_at;
                    }
                })
                .or_insert((session_id, created_at));
        }
        if latest_session_by_path.is_empty() {
            return Ok(std::collections::HashMap::new());
        }

        let session_ids: Vec<SessionId> = latest_session_by_path
            .values()
            .map(|(id, _)| *id)
            .collect::<std::collections::HashSet<_>>()
            .into_iter()
            .collect();
        let session_id_blobs: Vec<Value> = session_ids
            .iter()
            .map(|id| Value::Blob(id.as_bytes().to_vec()))
            .collect();
        let agent_by_session: std::collections::HashMap<SessionId, AgentKind> = self
            .with_conn(move |conn| {
                let placeholders = std::iter::repeat_n("?", session_id_blobs.len())
                    .collect::<Vec<_>>()
                    .join(", ");
                let sql =
                    format!("SELECT id, agent_kind FROM sessions WHERE id IN ({placeholders})");
                let mut stmt = conn.prepare(&sql)?;
                let rows = stmt.query_map(params_from_iter(session_id_blobs.iter()), |row| {
                    Ok((row.get::<_, Vec<u8>>(0)?, row.get::<_, String>(1)?))
                })?;
                let mut out = std::collections::HashMap::new();
                for r in rows {
                    let (id_bytes, agent) = r?;
                    if let Ok(id) = SessionId::from_slice(&id_bytes) {
                        out.insert(id, AgentKind::from_wire(&agent));
                    }
                }
                Ok(out)
            })
            .await?;

        Ok(latest_session_by_path
            .into_iter()
            .filter_map(|(path, (session_id, _))| {
                agent_by_session.get(&session_id).map(|kind| (path, *kind))
            })
            .collect())
    }

    /// Rank pages by how many of the query's tokens match their indexed
    /// entities, weighting each match by inverse entity frequency — a
    /// query token matching an entity that appears on 2 pages is a much
    /// stronger signal than one matching an entity on 200.
    ///
    /// Matching is lexical (exact name, name prefix, or a compound-word
    /// prefix) so this stays a plain SQL stream with no LLM call. It returns
    /// no candidates when the project has no entities indexed, as in the
    /// common zero-LLM case without hand-edited entity frontmatter.
    ///
    /// `expiry_cutoff_us`: see [`Self::search_pages_for_project`].
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    #[cfg(test)]
    pub(crate) async fn entity_hits_for_project(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        query: &str,
        limit: usize,
        expiry_cutoff_us: Option<i64>,
    ) -> StoreResult<Vec<EntityHit>> {
        self.entity_hits_for_project_at(
            workspace_id,
            project_id,
            query,
            limit,
            expiry_cutoff_us,
            None,
            false,
        )
        .await
    }

    /// Entity hits with an optional ingestion-time instant
    /// (docs/temporal.md). `as_of_us: None` = current knowledge (latest
    /// versions, expiry honoured). `Some(T)` = the page versions whose
    /// entity-link windows contain `T` — expiry is deliberately ignored
    /// there: a page valid at `T` that has since expired was still what
    /// we knew at `T`.
    #[allow(clippy::too_many_arguments)]
    pub async fn entity_hits_for_project_at(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        query: &str,
        limit: usize,
        expiry_cutoff_us: Option<i64>,
        as_of_us: Option<i64>,
        include_superseded: bool,
    ) -> StoreResult<Vec<EntityHit>> {
        self.entity_hits_filtered(
            workspace_id,
            project_id,
            query,
            limit,
            expiry_cutoff_us,
            as_of_us,
            include_superseded,
            PageFilter::default(),
        )
        .await
    }

    /// [`Self::entity_hits_for_project_at`] returning only pages `filter`
    /// keeps. Entity frequencies still count every page.
    #[allow(clippy::too_many_arguments)]
    async fn entity_hits_filtered(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        query: &str,
        limit: usize,
        expiry_cutoff_us: Option<i64>,
        as_of_us: Option<i64>,
        include_superseded: bool,
        filter: PageFilter<'_>,
    ) -> StoreResult<Vec<EntityHit>> {
        let tokens = entity_query_tokens(query);
        if tokens.is_empty() || limit == 0 {
            return Ok(Vec::new());
        }
        let cutoff = expiry_cutoff_us.unwrap_or_else(now_us);
        let (kept, kept_params) = filter.sql("pg", anonymous_placeholder);
        self.with_conn(move |conn| {
            let mut placeholders = String::with_capacity(tokens.len() * 96);
            let mut sql_params: Vec<Value> = Vec::with_capacity(tokens.len() * 5 + 7);
            for (idx, token) in tokens.iter().enumerate() {
                if idx > 0 {
                    placeholders.push_str(" OR ");
                }
                // Match exact names, name prefixes, and word prefixes after
                // any accepted entity separator. The latter lets `actor`
                // find `writer actor`, `writer-actor`, and `writer_actor`.
                //
                // `?` is positional-by-order, same as the graph query.
                placeholders.push_str(
                    "(e.name = ? \
                      OR e.name LIKE ? || '%' ESCAPE '\\' \
                      OR e.name LIKE '% ' || ? || '%' ESCAPE '\\' \
                      OR e.name LIKE '%-' || ? || '%' ESCAPE '\\' \
                      OR e.name LIKE '%\\_' || ? || '%' ESCAPE '\\')",
                );
                sql_params.push(Value::Text(token.clone()));
                let escaped = like_escape(token);
                for _ in 0..4 {
                    sql_params.push(Value::Text(escaped.clone()));
                }
            }
            sql_params.push(Value::Blob(workspace_id.as_bytes().to_vec()));
            sql_params.push(Value::Blob(project_id.as_bytes().to_vec()));
            match as_of_us {
                Some(t) => {
                    // freq window + outer window: two params each.
                    sql_params.push(Value::Integer(t));
                    sql_params.push(Value::Integer(t));
                    sql_params.push(Value::Blob(workspace_id.as_bytes().to_vec()));
                    sql_params.push(Value::Blob(project_id.as_bytes().to_vec()));
                    sql_params.push(Value::Integer(t));
                    sql_params.push(Value::Integer(t));
                }
                None => {
                    sql_params.push(Value::Integer(cutoff));
                    sql_params.push(Value::Blob(workspace_id.as_bytes().to_vec()));
                    sql_params.push(Value::Blob(project_id.as_bytes().to_vec()));
                    sql_params.push(Value::Integer(cutoff));
                }
            }
            sql_params.extend(kept_params);
            sql_params.push(Value::Integer(i64::try_from(limit).unwrap_or(i64::MAX)));

            let mut sql = String::with_capacity(placeholders.len() + 1_200);
            write!(
                &mut sql,
                // `freq` is how many current pages in this project carry
                // the entity; 1/freq is the inverse-frequency weight.
                "WITH matched AS ( \
                   SELECT e.id AS entity_id, e.name AS name \
                   FROM entities e \
                   WHERE ({placeholders}) \
                     AND e.workspace_id = ? AND e.project_id = ? \
                 ), \
                 freq AS ( \
                   SELECT m.entity_id, m.name, COUNT(*) AS pages \
                   FROM matched m \
                   JOIN entity_page_links l ON l.entity_id = m.entity_id \
                   JOIN pages p ON p.id = l.page_id \
                   WHERE 1 = 1{freq_version_filter} \
                   GROUP BY m.entity_id, m.name \
                 ) \
                 SELECT pg.id, pg.path, pg.title, {descriptor} AS snippet, \
                        SUM(1.0 / f.pages) AS weight, \
                        COUNT(*) AS matches, \
                        json_group_array(f.name) AS names \
                 FROM freq f \
                 JOIN entity_page_links l ON l.entity_id = f.entity_id \
                 JOIN pages pg ON pg.id = l.page_id \
                 WHERE pg.workspace_id = ? AND pg.project_id = ?{version_filter}{kept} \
                 GROUP BY pg.id, pg.path, pg.title \
                 ORDER BY weight DESC, matches DESC, pg.path ASC \
                 LIMIT ?",
                descriptor = page_descriptor_expr("pg.body", "pg.frontmatter_json"),
                version_filter = if as_of_us.is_some() {
                    // Window containment (docs/temporal.md); no expiry.
                    " AND l.valid_from <= ? \
                      AND (l.superseded_at IS NULL OR l.superseded_at > ?)"
                        .to_string()
                } else {
                    format!(
                        "{}{}",
                        latest_only("pg", include_superseded),
                        not_expired("pg", "?")
                    )
                },
                freq_version_filter = if as_of_us.is_some() {
                    " AND l.valid_from <= ? \
                      AND (l.superseded_at IS NULL OR l.superseded_at > ?)"
                        .to_string()
                } else {
                    format!(
                        "{}{}",
                        latest_only("p", include_superseded),
                        not_expired("p", "?")
                    )
                },
            )
            .expect("writing SQL into String cannot fail");

            let mut stmt = conn.prepare(&sql)?;
            let rows = stmt.query_map(params_from_iter(sql_params.iter()), |row| {
                let id_bytes: Vec<u8> = row.get(0)?;
                let path: String = row.get(1)?;
                let title: String = row.get(2)?;
                let snippet = page_descriptor(&row.get::<_, String>(3)?, &title);
                let weight: f64 = row.get(4)?;
                let names_json: String = row.get(6)?;
                Ok((id_bytes, path, title, snippet, weight, names_json))
            })?;
            let mut out = Vec::new();
            for row in rows {
                let (id_bytes, path, title, snippet, weight, names_json) = row?;
                let mut matched: Vec<String> = serde_json::from_str(&names_json)?;
                matched.sort_unstable();
                matched.dedup();
                out.push(EntityHit {
                    hit: PageHit {
                        id: PageId::from_slice(&id_bytes)?,
                        path: PagePath::new(path)?,
                        title,
                        snippet,
                        rank: 0.0,
                        superseded: false,
                        pinned: false,
                    },
                    weight,
                    matched,
                });
            }
            Ok(out)
        })
        .await
    }

    /// Return `stale` / `wrong` feedback still attached to a *current* unexpired
    /// page version in one project, grouped by (page, kind) — the input
    /// for the lint pass's `feedback_flagged` findings. Rewriting a
    /// flagged page supersedes the version the feedback points at, so
    /// the finding drops out here without any explicit dismissal.
    /// Most-recent signal first.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn open_feedback_findings(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> StoreResult<Vec<FeedbackFinding>> {
        self.with_conn(move |conn| {
            let ttl = not_expired("pg", "?3");
            let sql = format!(
                "SELECT pg.path, f.kind, COUNT(*) AS signal_count, MAX(f.created_at) AS latest, \
                        (SELECT reason FROM page_feedback r \
                          WHERE r.page_id = f.page_id AND r.kind = f.kind \
                            AND r.reason IS NOT NULL \
                          ORDER BY r.created_at DESC, r.id DESC LIMIT 1) AS reason \
                 FROM page_feedback f \
                 JOIN pages pg ON pg.id = f.page_id AND pg.is_latest = 1{ttl} \
                 WHERE f.workspace_id = ?1 AND f.project_id = ?2 \
                   AND f.kind IN ('stale', 'wrong') \
                 GROUP BY f.page_id, pg.path, f.kind \
                 ORDER BY latest DESC, pg.path ASC, f.kind ASC",
            );
            let mut stmt = conn.prepare_cached(&sql)?;
            let now = now_us();
            let rows = stmt.query_map(
                params![workspace_id.as_bytes(), project_id.as_bytes(), now],
                |row| {
                    let path: String = row.get(0)?;
                    let kind: String = row.get(1)?;
                    let signal_count: i64 = row.get(2)?;
                    let latest_us: i64 = row.get(3)?;
                    let reason: Option<String> = row.get(4)?;
                    Ok((path, kind, signal_count, latest_us, reason))
                },
            )?;
            let mut out = Vec::new();
            for row in rows {
                let (path, kind, signal_count, latest_us, reason) = row?;
                out.push(FeedbackFinding {
                    path,
                    kind,
                    signal_count: u32::try_from(signal_count.max(0)).unwrap_or(u32::MAX),
                    latest_at: jiff::Timestamp::from_microsecond(latest_us)
                        .map(|ts| ts.to_string())
                        .unwrap_or_default(),
                    reason,
                });
            }
            Ok(out)
        })
        .await
    }

    /// Return pages linked to or from the seed pages, scoped to latest pages
    /// in the same project.
    ///
    /// `expiry_cutoff_us`: see [`Self::search_pages_for_project`].
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn graph_neighbors_for_project(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        seed_ids: Vec<PageId>,
        limit: usize,
        expiry_cutoff_us: Option<i64>,
    ) -> StoreResult<Vec<PageHit>> {
        Ok(self
            .graph_neighbors_for_project_explained(
                workspace_id,
                project_id,
                seed_ids,
                limit,
                expiry_cutoff_us,
                false,
                PageFilter::default(),
            )
            .await?
            .into_iter()
            .map(|n| n.hit)
            .collect())
    }

    /// [`Self::graph_neighbors_for_project`] plus provenance: which seed
    /// produced each neighbour (`seed_ord` indexes into the caller's
    /// `seed_ids`) and in which direction the link points. Feeds the
    /// `memory_query` explain surface.
    #[allow(clippy::too_many_arguments)]
    async fn graph_neighbors_for_project_explained(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        seed_ids: Vec<PageId>,
        limit: usize,
        expiry_cutoff_us: Option<i64>,
        include_superseded: bool,
        filter: PageFilter<'_>,
    ) -> StoreResult<Vec<GraphNeighbor>> {
        if seed_ids.is_empty() || limit == 0 {
            return Ok(Vec::new());
        }
        let cutoff = expiry_cutoff_us.unwrap_or_else(now_us);
        let (out_kept, out_kept_params) = filter.sql("tp", anonymous_placeholder);
        let (in_kept, in_kept_params) = filter.sql("fp", anonymous_placeholder);
        self.with_conn(move |conn| {
            let mut seen = std::collections::HashSet::new();
            let mut out = Vec::new();

            let mut values_clause = String::with_capacity(seed_ids.len() * 8);
            let mut sql_params = Vec::with_capacity(seed_ids.len() * 2 + 6);
            for (idx, seed_id) in seed_ids.iter().enumerate() {
                if idx > 0 {
                    values_clause.push_str(", ");
                }
                values_clause.push_str("(?, ?)");
                sql_params.push(Value::Blob(seed_id.as_bytes().to_vec()));
                sql_params.push(Value::Integer(idx as i64));
            }
            let now = cutoff;
            sql_params.push(Value::Blob(workspace_id.as_bytes().to_vec()));
            sql_params.push(Value::Blob(project_id.as_bytes().to_vec()));
            sql_params.push(Value::Integer(now));
            sql_params.extend(out_kept_params);
            sql_params.push(Value::Blob(workspace_id.as_bytes().to_vec()));
            sql_params.push(Value::Blob(project_id.as_bytes().to_vec()));
            sql_params.push(Value::Integer(now));
            sql_params.extend(in_kept_params);

            let out_descriptor = page_descriptor_expr("tp.body", "tp.frontmatter_json");
            let in_descriptor = page_descriptor_expr("fp.body", "fp.frontmatter_json");
            let out_latest = latest_only("tp", include_superseded);
            let in_latest = latest_only("fp", include_superseded);
            let out_not_expired = not_expired("tp", "?");
            let in_not_expired = not_expired("fp", "?");
            let mut sql = String::with_capacity(values_clause.len() + 1_500);
            write!(
                &mut sql,
                "WITH seeds(seed_id, seed_ord) AS (VALUES {values_clause}), \
                 neighbors AS ( \
                   SELECT tp.id AS id, tp.path AS path, tp.title AS title, \
                          {out_descriptor} AS snippet, \
                          seeds.seed_ord * 2 AS stream_ord, tp.updated_at AS updated_at, \
                          l.link_type AS link_type \
                   FROM seeds \
                   JOIN links l ON l.from_page_id = seeds.seed_id \
                   JOIN pages tp ON tp.id = l.to_page_id \
                   WHERE tp.workspace_id = ? AND tp.project_id = ?{out_latest}{out_not_expired}{out_kept} \
                   UNION ALL \
                   SELECT fp.id AS id, fp.path AS path, fp.title AS title, \
                          {in_descriptor} AS snippet, \
                          seeds.seed_ord * 2 + 1 AS stream_ord, fp.updated_at AS updated_at, \
                          l.link_type AS link_type \
                   FROM seeds \
                   JOIN links l ON l.to_page_id = seeds.seed_id \
                   JOIN pages fp ON fp.id = l.from_page_id \
                   WHERE fp.workspace_id = ? AND fp.project_id = ?{in_latest}{in_not_expired}{in_kept} \
                 ) \
                 SELECT id, path, title, snippet, stream_ord, link_type \
                 FROM neighbors \
                 WHERE NOT EXISTS (SELECT 1 FROM seeds s WHERE s.seed_id = neighbors.id) \
                 ORDER BY stream_ord ASC, updated_at DESC, path ASC"
            )
            .expect("writing SQL into String cannot fail");

            let mut stmt = conn.prepare(&sql)?;
            let rows = stmt.query_map(params_from_iter(sql_params.iter()), |row| {
                let id_bytes: Vec<u8> = row.get(0)?;
                let path: String = row.get(1)?;
                let title: String = row.get(2)?;
                let snippet = page_descriptor(&row.get::<_, String>(3)?, &title);
                let stream_ord: i64 = row.get(4)?;
                let link_type: String = row.get(5)?;
                Ok((id_bytes, path, title, snippet, stream_ord, link_type))
            })?;

            for row in rows {
                let (id_bytes, path, title, snippet, stream_ord, link_type) = row?;
                let id = PageId::from_slice(&id_bytes)?;
                if !seen.insert(id) {
                    continue;
                }
                #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
                let seed_ord = (stream_ord / 2).max(0) as usize;
                out.push(GraphNeighbor {
                    hit: PageHit {
                        id,
                        path: PagePath::new(path)?,
                        title,
                        snippet,
                        rank: 0.0,
                        superseded: false,
                        pinned: false,
                    },
                    seed_ord,
                    incoming: stream_ord % 2 == 1,
                    edge: (link_type != "references").then_some(link_type),
                });
                if out.len() >= limit {
                    break;
                }
            }
            Ok(out)
        })
        .await
    }

    /// Title and descriptor for a bounded set of already-fused page ids
    /// (#486).
    ///
    /// The vector stream returns `(PageId, PagePath, f32)` and nothing else,
    /// so a page it reaches first is inserted into the fusion map with empty
    /// strings and — because every fusion site uses `or_insert_with` — stays
    /// empty even when entity or graph later find it with a real descriptor
    /// already computed.
    ///
    /// Deliberately a post-fusion lookup rather than a wider embedding query.
    /// `top_embedding_hits_for_project` has no SQL `LIMIT`: it scores every
    /// embedded page in the project in Rust and takes top-k afterwards, so a
    /// descriptor column there would compute one for the whole corpus on
    /// every search. Here the input is only the handful of ids that survived
    /// fusion and still lack a title.
    /// Open handoffs for a project, oldest first (#513).
    ///
    /// `memory_handoff_cancel` takes an exact id and nothing exposed one, so a
    /// backlog could be observed in `status` counts but never addressed. Oldest
    /// first because the operator's question is "what is stale", and the
    /// automatic expiry deliberately spares manual and sibling-directory
    /// handoffs — which is how a months-old entry survives to be listed here.
    pub async fn open_handoffs_for_project(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        limit: usize,
    ) -> StoreResult<Vec<OpenHandoff>> {
        self.with_conn(move |conn| {
            let mut stmt = conn.prepare(
                "SELECT id, from_agent, to_agent, cwd, created_at \
                 FROM handoffs \
                 WHERE workspace_id = ?1 AND project_id = ?2 AND state = 'open' \
                 ORDER BY created_at ASC, id ASC \
                 LIMIT ?3",
            )?;
            let rows = stmt.query_map(
                params![
                    workspace_id.as_bytes(),
                    project_id.as_bytes(),
                    u64::try_from(limit).unwrap_or(u64::MAX),
                ],
                |row| {
                    let id: Vec<u8> = row.get(0)?;
                    Ok((
                        id,
                        row.get::<_, String>(1)?,
                        row.get::<_, Option<String>>(2)?,
                        row.get::<_, Option<String>>(3)?,
                        row.get::<_, i64>(4)?,
                    ))
                },
            )?;
            let mut out = Vec::new();
            for row in rows {
                let (id, from_agent, to_agent, cwd, created_at) = row?;
                let Ok(id) = HandoffId::from_slice(&id) else {
                    continue;
                };
                out.push(OpenHandoff {
                    id: id.to_string(),
                    from_agent,
                    to_agent,
                    cwd,
                    created_at_ms: created_at / 1_000,
                });
            }
            Ok(out)
        })
        .await
    }

    async fn page_descriptors_for_ids(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        page_ids: Vec<PageId>,
        include_superseded: bool,
    ) -> StoreResult<std::collections::HashMap<PageId, (String, String)>> {
        if page_ids.is_empty() {
            return Ok(std::collections::HashMap::new());
        }
        self.with_conn(move |conn| {
            let mut values_clause = String::with_capacity(page_ids.len() * 5);
            let mut sql_params = Vec::with_capacity(page_ids.len() + 2);
            for (idx, page_id) in page_ids.iter().enumerate() {
                if idx > 0 {
                    values_clause.push_str(", ");
                }
                values_clause.push_str("(?)");
                sql_params.push(Value::Blob(page_id.as_bytes().to_vec()));
            }
            sql_params.push(Value::Blob(workspace_id.as_bytes().to_vec()));
            sql_params.push(Value::Blob(project_id.as_bytes().to_vec()));

            let sql = format!(
                "WITH requested(id) AS (VALUES {values_clause}) \
                 SELECT pages.id, pages.title, {descriptor} AS descriptor \
                 FROM requested \
                 JOIN pages ON pages.id = requested.id \
                 WHERE pages.workspace_id = ? \
                   AND pages.project_id = ?{latest}",
                descriptor = page_descriptor_expr("pages.body", "pages.frontmatter_json"),
                latest = latest_only("pages", include_superseded),
            );
            let mut stmt = conn.prepare(&sql)?;
            let rows = stmt.query_map(params_from_iter(sql_params.iter()), |row| {
                let id_bytes: Vec<u8> = row.get(0)?;
                let title: String = row.get(1)?;
                let descriptor: String = row.get(2)?;
                Ok((id_bytes, title, descriptor))
            })?;

            let mut out = std::collections::HashMap::new();
            for row in rows {
                let (id_bytes, title, descriptor) = row?;
                if let Ok(id) = PageId::from_slice(&id_bytes) {
                    out.insert(id, (title, descriptor));
                }
            }
            Ok(out)
        })
        .await
    }

    async fn page_authorities_for_project(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        page_ids: Vec<PageId>,
    ) -> StoreResult<std::collections::HashMap<PageId, PageAuthority>> {
        self.page_authorities_for_ids(workspace_id, project_id, page_ids, true)
            .await
    }

    /// Authority inputs for specific page versions, without the
    /// latest-only filter: audit mode ranks superseded versions too
    /// (issue #656).
    async fn page_authorities_for_versions(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        page_ids: Vec<PageId>,
    ) -> StoreResult<std::collections::HashMap<PageId, PageAuthority>> {
        self.page_authorities_for_ids(workspace_id, project_id, page_ids, false)
            .await
    }

    async fn page_authorities_for_ids(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        page_ids: Vec<PageId>,
        latest_only: bool,
    ) -> StoreResult<std::collections::HashMap<PageId, PageAuthority>> {
        if page_ids.is_empty() {
            return Ok(std::collections::HashMap::new());
        }
        self.with_conn(move |conn| {
            let mut values_clause = String::with_capacity(page_ids.len() * 5);
            let mut sql_params = Vec::with_capacity(page_ids.len() + 2);
            for (idx, page_id) in page_ids.iter().enumerate() {
                if idx > 0 {
                    values_clause.push_str(", ");
                }
                values_clause.push_str("(?)");
                sql_params.push(Value::Blob(page_id.as_bytes().to_vec()));
            }
            sql_params.push(Value::Blob(workspace_id.as_bytes().to_vec()));
            sql_params.push(Value::Blob(project_id.as_bytes().to_vec()));

            let kind_expr = page_kind_expr("pages.path", "pages.frontmatter_json");
            let latest_filter = if latest_only {
                "AND pages.is_latest = 1"
            } else {
                ""
            };
            let sql = format!(
                "WITH requested(id) AS (VALUES {values_clause}) \
                 SELECT pages.id, pages.path, pages.tier, pages.pinned, \
                        pages.frontmatter_json, {kind_expr} AS kind \
                 FROM requested \
                 JOIN pages ON pages.id = requested.id \
                 WHERE pages.workspace_id = ? \
                   AND pages.project_id = ? \
                   {latest_filter}"
            );
            let mut stmt = conn.prepare(&sql)?;
            let rows = stmt.query_map(params_from_iter(sql_params.iter()), |row| {
                let id_bytes: Vec<u8> = row.get(0)?;
                let path: String = row.get(1)?;
                let tier: String = row.get(2)?;
                let pinned = row.get::<_, i64>(3)? != 0;
                let frontmatter_json: String = row.get(4)?;
                let kind: String = row.get(5)?;
                Ok((id_bytes, path, tier, pinned, frontmatter_json, kind))
            })?;

            let mut authorities = std::collections::HashMap::new();
            for row in rows {
                let (id_bytes, path, tier, pinned, frontmatter_json, kind) = row?;
                authorities.insert(
                    PageId::from_slice(&id_bytes)?,
                    PageAuthority::from_stored(&path, &kind, &tier, pinned, &frontmatter_json),
                );
            }
            Ok(authorities)
        })
        .await
    }

    /// Hybrid search: RRF-fuse FTS5 results with cosine-similarity
    /// over the stored embeddings of the matching `(provider, model,
    /// dim)`, entity matches, and link-neighbour expansion — four RRF
    /// streams. Applies the bounded page-authority adjustment after
    /// fusion and returns the top-`limit` pages by adjusted fused score.
    ///
    /// Each stream degrades independently to contributing nothing: no
    /// `query_vec` skips the vector stream, an empty `entities` table
    /// skips the entity stream, and graph expansion still runs from
    /// whatever seeds the other streams produced.
    ///
    /// `expiry_cutoff_us`: see [`Self::search_pages_for_project`]. The
    /// cutoff resolves once here so all streams agree on it.
    ///
    /// `include_superseded`: `false` — the default — restricts every stream
    /// to the current page version (`is_latest = 1`), the exact hot-path
    /// behaviour. `true` drops that predicate so superseded versions enter
    /// the candidate pool too; each returned [`PageHit`] carries
    /// `superseded` so the caller can tell historical versions from the
    /// current one (invariant #16: the superseded loser stays reachable).
    ///
    /// k=60 is the canonical RRF constant.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    #[allow(clippy::too_many_arguments)]
    pub async fn hybrid_search(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        query: String,
        query_vec: Option<Vec<f32>>,
        provider: String,
        model: String,
        dim: u32,
        limit: usize,
        expiry_cutoff_us: Option<i64>,
        include_superseded: bool,
    ) -> StoreResult<Vec<PageHit>> {
        Ok(self
            .hybrid_search_inner(
                workspace_id,
                project_id,
                query,
                query_vec,
                provider,
                model,
                dim,
                limit,
                expiry_cutoff_us,
                false,
                include_superseded,
                &OwnerFilter::Any,
                PageFilter::default(),
            )
            .await?
            .0
            .into_iter()
            .map(|(hit, _)| hit)
            .collect())
    }

    /// [`Self::hybrid_search`] plus a [`SearchExplain`] per hit — the
    /// per-stream ranks, raw scores, and RRF contributions the fusion
    /// otherwise discards. Callers that don't need the bounded provenance
    /// bookkeeping use `hybrid_search`.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    #[allow(clippy::too_many_arguments)]
    pub async fn hybrid_search_explained(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        query: String,
        query_vec: Option<Vec<f32>>,
        provider: String,
        model: String,
        dim: u32,
        limit: usize,
        expiry_cutoff_us: Option<i64>,
        include_superseded: bool,
    ) -> StoreResult<Vec<(PageHit, SearchExplain)>> {
        Ok(self
            .hybrid_search_explained_timed(
                workspace_id,
                project_id,
                query,
                query_vec,
                provider,
                model,
                dim,
                limit,
                expiry_cutoff_us,
                include_superseded,
            )
            .await?
            .0)
    }

    /// [`Self::hybrid_search_explained`] plus the wall time of each stream.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    #[allow(clippy::too_many_arguments)]
    pub async fn hybrid_search_explained_timed(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        query: String,
        query_vec: Option<Vec<f32>>,
        provider: String,
        model: String,
        dim: u32,
        limit: usize,
        expiry_cutoff_us: Option<i64>,
        include_superseded: bool,
    ) -> StoreResult<(Vec<(PageHit, SearchExplain)>, StreamTimings)> {
        let (hits, timings, _) = self
            .hybrid_search_inner(
                workspace_id,
                project_id,
                query,
                query_vec,
                provider,
                model,
                dim,
                limit,
                expiry_cutoff_us,
                true,
                include_superseded,
                &OwnerFilter::Any,
                PageFilter::default(),
            )
            .await?;
        // Belief-strength fields (`evidence_count`, `confidence`,
        // `belief_factor`; P2, docs/design-hindsight-borrowings.md §3) are
        // populated inside the explained path of `hybrid_search_inner` from one
        // batched query — never per-hit — so no second pass is needed here.
        Ok((
            hits.into_iter()
                .map(|(hit, explain)| (hit, explain.unwrap_or_default()))
                .collect(),
            timings,
        ))
    }

    /// The hybrid ranker over one or more resolved scopes — the single entry
    /// point `memory_query` and the web search both rank project/scopes
    /// results through.
    ///
    /// One scope returns [`Self::hybrid_search`]'s order untouched. Several
    /// scopes are searched one at a time and merged: a page id found in more
    /// than one keeps its best rank, then the union is sorted by rank, path
    /// and id and cut to `search.limit`. Per-hit [`SearchExplain`] and the
    /// summed [`StreamTimings`] are returned only when `search.explain` asks
    /// for them; the normal path reads no clock for them.
    ///
    /// The caller resolves `scopes` (and so decides who may read them); this
    /// never widens past them.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn hybrid_search_scopes(
        &self,
        scopes: &[(WorkspaceId, ProjectId)],
        search: HybridSearch<'_>,
    ) -> StoreResult<(Vec<(PageHit, Option<SearchExplain>)>, Option<StreamTimings>)> {
        let outcome = self.hybrid_search_scopes_outcome(scopes, search).await?;
        Ok((outcome.hits, outcome.timings))
    }

    /// [`Self::hybrid_search_scopes`] plus whether any scope matched the
    /// query's own terms ([`HybridSearchOutcome::lexical_match`]).
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn hybrid_search_scopes_outcome(
        &self,
        scopes: &[(WorkspaceId, ProjectId)],
        search: HybridSearch<'_>,
    ) -> StoreResult<HybridSearchOutcome> {
        // Provider/model/dim only select which stored vectors are eligible;
        // with no query vector the vector stream never runs, so the empty
        // triple is inert rather than a fake identity.
        let (vector, provider, model, dim) = match search.vector {
            Some(v) => (
                Some(v.vector.to_vec()),
                v.provider.to_owned(),
                v.model.to_owned(),
                v.dim,
            ),
            None => (None, String::new(), String::new(), 0),
        };
        let mut timings: Option<StreamTimings> = None;
        let mut lexical_match = false;
        let mut per_scope = Vec::with_capacity(scopes.len());
        for &(workspace_id, project_id) in scopes {
            let (hits, scope_timings, scope_lexical_match) = self
                .hybrid_search_inner(
                    workspace_id,
                    project_id,
                    search.query.to_owned(),
                    vector.clone(),
                    provider.clone(),
                    model.clone(),
                    dim,
                    search.limit,
                    search.expiry_cutoff_us,
                    search.explain,
                    search.include_superseded,
                    search.owner,
                    search.filter,
                )
                .await?;
            if search.explain {
                timings
                    .get_or_insert_with(Default::default)
                    .accumulate(&scope_timings);
            }
            lexical_match |= scope_lexical_match;
            per_scope.push(hits);
        }
        let hits = if per_scope.len() == 1 {
            per_scope.pop().unwrap_or_default()
        } else {
            let mut hits_by_id: std::collections::HashMap<
                PageId,
                (PageHit, Option<SearchExplain>),
            > = std::collections::HashMap::new();
            for hit in per_scope.into_iter().flatten() {
                match hits_by_id.entry(hit.0.id) {
                    std::collections::hash_map::Entry::Occupied(mut existing) => {
                        if hit.0.rank < existing.get().0.rank {
                            existing.insert(hit);
                        }
                    }
                    std::collections::hash_map::Entry::Vacant(slot) => {
                        slot.insert(hit);
                    }
                }
            }
            let mut hits: Vec<(PageHit, Option<SearchExplain>)> =
                hits_by_id.into_values().collect();
            hits.sort_by(|a, b| {
                a.0.rank
                    .partial_cmp(&b.0.rank)
                    .unwrap_or(std::cmp::Ordering::Equal)
                    .then_with(|| a.0.path.as_str().cmp(b.0.path.as_str()))
                    .then_with(|| a.0.id.as_bytes().cmp(b.0.id.as_bytes()))
            });
            hits.truncate(search.limit);
            hits
        };
        let hits = if search.explain {
            hits.into_iter()
                .map(|(hit, explain)| (hit, Some(explain.unwrap_or_default())))
                .collect()
        } else {
            hits
        };
        Ok(HybridSearchOutcome {
            hits,
            timings,
            lexical_match,
        })
    }

    /// The streams [`Self::hybrid_search_scopes`] runs for a query, in the
    /// order `memory_query` reports them as `streams_active`.
    #[must_use]
    pub fn active_streams(&self, has_query_vector: bool) -> Vec<&'static str> {
        let mut streams = vec!["fts", "entity"];
        if has_query_vector {
            streams.push("vector");
            if self.tuning.abstract_vectors {
                streams.push("abstract");
            }
        }
        streams.push("graph");
        if self.tuning.observation_stream {
            streams.push("observation");
        }
        streams
    }

    #[allow(clippy::too_many_arguments)]
    async fn hybrid_search_inner(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        query: String,
        query_vec: Option<Vec<f32>>,
        provider: String,
        model: String,
        dim: u32,
        limit: usize,
        expiry_cutoff_us: Option<i64>,
        explain: bool,
        include_superseded: bool,
        owner_filter: &OwnerFilter,
        filter: PageFilter<'_>,
    ) -> StoreResult<(Vec<(PageHit, Option<SearchExplain>)>, StreamTimings, bool)> {
        let cutoff = expiry_cutoff_us.unwrap_or_else(now_us);
        // Stream timings exist only for explain: `explain.then(Instant::now)`
        // reads no clock on the normal path.
        let mut timings = StreamTimings::default();
        // The routing decision is read off the query before the FTS call
        // consumes it; with routing disabled this is a no-op `false`.
        let tuning = self.tuning;
        let session_recall = tuning.session_recall_routing && is_session_recall_query(&query);
        // Authority is applied after RRF, so every stream needs the same
        // bounded candidate window used by FTS-only search. A `limit * 2`
        // window was too narrow at small limits for a canonical page to enter
        // the fused pool and receive its bounded promotion.
        let candidate_limit = authority_candidate_limit(limit);
        // Tokenize the borrowed query before the FTS candidate call consumes
        // it. This avoids cloning a caller-controlled query on the hot path.
        // The default path uses the latest-only entry; the opt-in path reaches
        // superseded versions through the `_at` entry with no `as_of` instant.
        let started = explain.then(std::time::Instant::now);
        let entity_hits = self
            .entity_hits_filtered(
                workspace_id,
                project_id,
                &query,
                candidate_limit,
                Some(cutoff),
                None,
                include_superseded,
                filter,
            )
            .await?;
        timings.entity_ms = elapsed_ms(started);
        // The stream-off hot path keeps moving the query without a clone.
        let observation_query = if tuning.observation_stream {
            query.clone()
        } else {
            String::new()
        };
        let started = explain.then(std::time::Instant::now);
        let fts_candidates = self
            .search_page_candidates_for_project(
                workspace_id,
                project_id,
                query,
                candidate_limit,
                Some(cutoff),
                include_superseded,
                filter,
            )
            .await?;
        timings.fts_ms = elapsed_ms(started);
        let mut authorities: std::collections::HashMap<PageId, PageAuthority> = fts_candidates
            .iter()
            .map(|(hit, authority)| (hit.id, *authority))
            .collect();
        let fts_hits: Vec<PageHit> = fts_candidates
            .into_iter()
            .map(|(hit, _authority)| hit)
            .collect();
        let mut vec_hits: Vec<(PageId, PagePath, f32)> = Vec::new();
        let mut abstract_hits: Vec<(PageId, PagePath, f32)> = Vec::new();
        if let Some(qv) = query_vec {
            let started = explain.then(std::time::Instant::now);
            if tuning.abstract_vectors {
                abstract_hits = self
                    .top_embedding_hits_in_table(
                        EmbeddingTable::Abstract,
                        workspace_id,
                        project_id,
                        qv.clone(),
                        provider.clone(),
                        model.clone(),
                        dim,
                        candidate_limit,
                        cutoff,
                        include_superseded,
                        filter,
                    )
                    .await?;
            }
            vec_hits = self
                .top_embedding_hits_for_project(
                    workspace_id,
                    project_id,
                    qv,
                    provider,
                    model,
                    dim,
                    candidate_limit,
                    cutoff,
                    include_superseded,
                    filter,
                )
                .await?;
            timings.vector_ms = elapsed_ms(started);
        }

        let mut seed_seen = std::collections::HashSet::new();
        let mut seed_ids = Vec::new();
        let mut seed_paths = explain.then(Vec::new);
        for hit in &fts_hits {
            if seed_seen.insert(hit.id) {
                seed_ids.push(hit.id);
                if let Some(paths) = &mut seed_paths {
                    paths.push(hit.path.as_str().to_string());
                }
            }
        }
        for (id, path, _) in vec_hits.iter().chain(abstract_hits.iter()) {
            if seed_seen.insert(*id) {
                seed_ids.push(*id);
                if let Some(paths) = &mut seed_paths {
                    paths.push(path.as_str().to_string());
                }
            }
        }
        for e in &entity_hits {
            if seed_seen.insert(e.hit.id) {
                seed_ids.push(e.hit.id);
                if let Some(paths) = &mut seed_paths {
                    paths.push(e.hit.path.as_str().to_string());
                }
            }
        }
        let started = explain.then(std::time::Instant::now);
        let graph_hits = self
            .graph_neighbors_for_project_explained(
                workspace_id,
                project_id,
                seed_ids,
                candidate_limit,
                Some(cutoff),
                include_superseded,
                filter,
            )
            .await?;
        timings.graph_ms = elapsed_ms(started);
        // R1: the observation-evidence stream. It votes only for latest
        // session pages, so it does not seed graph expansion.
        let observation_votes = if tuning.observation_stream {
            let started = explain.then(std::time::Instant::now);
            let votes = self
                .observation_stream_votes(
                    workspace_id,
                    project_id,
                    &observation_query,
                    candidate_limit,
                    cutoff,
                    owner_filter.clone(),
                    filter,
                )
                .await?;
            timings.observation_ms = elapsed_ms(started);
            votes
        } else {
            Vec::new()
        };

        // Whether a stream that matches the query's own terms found a page.
        // The vector streams have no similarity floor, so once any page has
        // an embedding they answer every query, and graph expansion follows
        // their seeds: a result without one of these is not a match.
        let lexical_match =
            !fts_hits.is_empty() || !entity_hits.is_empty() || !observation_votes.is_empty();

        // RRF fuse: score(d) = Σ 1/(k + rank_i(d)) over rankers.
        let k = 60.0_f64;
        struct Fused {
            path: PagePath,
            title: String,
            snippet: String,
            score: f64,
            explain: Option<SearchExplain>,
            /// Whether page FTS matched this page, which decides whose
            /// snippet explains the hit.
            fts_matched: bool,
            /// The best matching observation's excerpt (observation stream).
            observation_snippet: Option<String>,
        }
        let mut fused: std::collections::HashMap<PageId, Fused> = std::collections::HashMap::new();

        // A session page's indexed body is only the titles of its own
        // observations, and the observation stream already ranks that
        // session by the full observation text. Counting page FTS as well
        // would let a session that merely shares topic words in its titles
        // outvote the session holding the answer, so a page the stream voted
        // for takes its lexical evidence from the stream alone. Its FTS rank
        // and snippet are kept; only the RRF contribution is dropped.
        let observation_voted: std::collections::HashSet<PageId> =
            observation_votes.iter().map(|vote| vote.page_id).collect();
        for (rank, h) in fts_hits.iter().enumerate() {
            let contrib = if observation_voted.contains(&h.id) {
                0.0
            } else {
                1.0 / (k + (rank + 1) as f64)
            };
            let entry = fused.entry(h.id).or_insert_with(|| Fused {
                path: h.path.clone(),
                title: h.title.clone(),
                snippet: h.snippet.clone(),
                score: 0.0,
                explain: explain.then(SearchExplain::default),
                fts_matched: false,
                observation_snippet: None,
            });
            entry.score += contrib;
            entry.fts_matched = true;
            if let Some(details) = &mut entry.explain {
                details.fts_rank = Some(rank + 1);
                details.fts_score = Some(h.rank);
                details.rrf.fts = contrib;
                details.fused += contrib;
            }
        }
        for (rank, (id, path, cosine)) in vec_hits.iter().enumerate() {
            let contrib = 1.0 / (k + (rank + 1) as f64);
            let entry = fused.entry(*id).or_insert_with(|| Fused {
                path: path.clone(),
                title: String::new(),
                snippet: String::new(),
                score: 0.0,
                explain: explain.then(SearchExplain::default),
                fts_matched: false,
                observation_snippet: None,
            });
            entry.score += contrib;
            if let Some(details) = &mut entry.explain {
                details.vector_rank = Some(rank + 1);
                details.cosine = Some(*cosine);
                details.rrf.vector = contrib;
                details.fused += contrib;
            }
        }
        for (rank, (id, path, cosine)) in abstract_hits.iter().enumerate() {
            let contrib = 1.0 / (k + (rank + 1) as f64);
            let entry = fused.entry(*id).or_insert_with(|| Fused {
                path: path.clone(),
                title: String::new(),
                snippet: String::new(),
                score: 0.0,
                explain: explain.then(SearchExplain::default),
                fts_matched: false,
                observation_snippet: None,
            });
            entry.score += contrib;
            if let Some(details) = &mut entry.explain {
                details.abstract_rank = Some(rank + 1);
                details.abstract_cosine = Some(*cosine);
                details.rrf.abstract_vector = contrib;
                details.fused += contrib;
            }
        }
        for (rank, e) in entity_hits.iter().enumerate() {
            let contrib = 1.0 / (k + (rank + 1) as f64);
            let entry = fused.entry(e.hit.id).or_insert_with(|| Fused {
                path: e.hit.path.clone(),
                title: e.hit.title.clone(),
                snippet: e.hit.snippet.clone(),
                score: 0.0,
                explain: explain.then(SearchExplain::default),
                fts_matched: false,
                observation_snippet: None,
            });
            entry.score += contrib;
            if let Some(details) = &mut entry.explain {
                details.entity_rank = Some(rank + 1);
                details.entity_weight = Some(e.weight);
                details.matched_entities = e.matched.clone();
                details.rrf.entity = contrib;
                details.fused += contrib;
            }
        }
        for (rank, n) in graph_hits.iter().enumerate() {
            let contrib = 1.0 / (k + (rank + 1) as f64);
            let entry = fused.entry(n.hit.id).or_insert_with(|| Fused {
                path: n.hit.path.clone(),
                title: n.hit.title.clone(),
                snippet: n.hit.snippet.clone(),
                score: 0.0,
                explain: explain.then(SearchExplain::default),
                fts_matched: false,
                observation_snippet: None,
            });
            entry.score += contrib;
            if let Some(details) = &mut entry.explain {
                details.graph_rank = Some(rank + 1);
                details.graph_via = Some(GraphVia {
                    seed_path: seed_paths
                        .as_ref()
                        .and_then(|paths| paths.get(n.seed_ord))
                        .cloned()
                        .unwrap_or_default(),
                    direction: if n.incoming { "incoming" } else { "outgoing" },
                    edge: n.edge.clone(),
                });
                details.rrf.graph = contrib;
                details.fused += contrib;
            }
        }

        for (rank, vote) in observation_votes.into_iter().enumerate() {
            let contrib = 1.0 / (k + (rank + 1) as f64);
            let entry = fused.entry(vote.page_id).or_insert_with(|| Fused {
                path: vote.path,
                title: String::new(),
                snippet: String::new(),
                score: 0.0,
                explain: explain.then(SearchExplain::default),
                fts_matched: false,
                observation_snippet: None,
            });
            entry.score += contrib;
            // A vote from a session the caller may not read still ranks the
            // shared page, but leaves its title empty so the descriptor fill
            // below gives the hit the page's own title and snippet.
            if vote.snippet.is_some() {
                if entry.title.is_empty() {
                    entry.title = vote.title;
                }
                entry.observation_snippet = vote.snippet;
            }
            if let Some(details) = &mut entry.explain {
                details.observation_rank = Some(rank + 1);
                details.observation_ids = vote.observation_ids;
                details.rrf.observation = contrib;
                details.fused += contrib;
            }
        }

        // Pages whose snippet is the observation excerpt; the descriptor fill
        // below must not overwrite it.
        let mut observation_excerpts: std::collections::HashSet<PageId> =
            std::collections::HashSet::new();
        let mut out: Vec<(PageHit, Option<SearchExplain>)> = fused
            .into_iter()
            .map(|(id, entry)| {
                // A page FTS matched keeps its own snippet. The observation
                // excerpt stands in only when FTS missed the page, so the
                // hit still shows the text that matched.
                let snippet = match entry.observation_snippet {
                    Some(excerpt) if !entry.fts_matched => {
                        observation_excerpts.insert(id);
                        excerpt
                    }
                    _ => entry.snippet,
                };
                (
                    PageHit {
                        id,
                        path: entry.path,
                        title: entry.title,
                        snippet,
                        rank: -entry.score, // lower = better (matches FTS5 convention)
                        superseded: false,
                        pinned: false,
                    },
                    entry.explain,
                )
            })
            .collect();
        // #486: fill in hits the vector stream reached first. Only those with
        // an empty title are looked up — a page fts, entity or graph already
        // described keeps the descriptor those streams computed, which is the
        // whole reason not to recompute it here.
        let undescribed: Vec<PageId> = out
            .iter()
            .filter_map(|(hit, _)| hit.title.is_empty().then_some(hit.id))
            .collect();
        if !undescribed.is_empty() {
            let descriptors = self
                .page_descriptors_for_ids(workspace_id, project_id, undescribed, include_superseded)
                .await?;
            for (hit, _) in &mut out {
                if let Some((title, descriptor)) = descriptors.get(&hit.id) {
                    hit.title = title.clone();
                    if !observation_excerpts.contains(&hit.id) {
                        hit.snippet = descriptor.clone();
                    }
                }
            }
        }

        let missing_authorities: Vec<PageId> = out
            .iter()
            .filter_map(|(hit, _)| (!authorities.contains_key(&hit.id)).then_some(hit.id))
            .collect();
        // With `include_superseded`, some fused ids are non-latest versions
        // reached by the vector/graph streams; their authority inputs must be
        // read without the latest-only filter or they'd get the neutral
        // default and misrank.
        let extra_authorities = if include_superseded {
            self.page_authorities_for_versions(workspace_id, project_id, missing_authorities)
                .await?
        } else {
            self.page_authorities_for_project(workspace_id, project_id, missing_authorities)
                .await?
        };
        authorities.extend(extra_authorities);

        // Belief-strength (P2, docs/design-hindsight-borrowings.md §3).
        // Fetched only when needed: an explained query exposes
        // `confidence`/`evidence_count` inertly, and a positive weight folds
        // confidence into the authority factor. The default, non-explained,
        // weight-off path skips the query entirely and ranks byte-identically.
        let belief_weight = tuning.belief_authority_weight;
        let need_belief = explain || belief_weight > 0.0;
        let belief_inputs = if need_belief {
            let ids: Vec<PageId> = out.iter().map(|(hit, _)| hit.id).collect();
            self.page_belief_inputs(&ids).await?
        } else {
            std::collections::HashMap::new()
        };
        // Anti-entrenchment: a supersession always wins regardless of count
        // (invariant #16). A superseded version's stale evidence must not boost
        // it, so the fold skips those ids. Only needed on the opt-in
        // include_superseded path — the default path returns latest only.
        let boost_skip = if belief_weight > 0.0 && include_superseded {
            let ids: Vec<PageId> = out.iter().map(|(hit, _)| hit.id).collect();
            self.superseded_page_ids(workspace_id, project_id, ids)
                .await?
        } else {
            std::collections::HashSet::new()
        };
        let belief_now = now_us();
        for (hit, explain) in &mut out {
            if let Some(authority) = authorities.get(&hit.id) {
                let base = authority.factor_for(session_recall, tuning.session_recall_bonus);
                // Belief confidence is one more bounded factor folded *inside*
                // the existing authority clamp — never a new multiplier tower.
                let (confidence, belief_add) = if need_belief {
                    let inputs = belief_inputs.get(&hit.id).copied().unwrap_or_default();
                    let confidence = crate::belief::confidence(&inputs, belief_now);
                    let add = if belief_weight > 0.0 && !boost_skip.contains(&hit.id) {
                        Some(belief_weight * confidence)
                    } else {
                        None
                    };
                    (Some((inputs, confidence)), add)
                } else {
                    (None, None)
                };
                let factor = match belief_add {
                    Some(add) => (base + add).clamp(0.55, 1.50),
                    None => base,
                };
                hit.rank = apply_rank_multiplier(hit.rank, factor);
                // `fused` stays the raw RRF sum; without the multiplier
                // beside it the explain could not account for the rank it
                // returns, which is the whole point of the surface.
                if let Some(details) = explain {
                    details.authority = Some(factor);
                    if let Some((inputs, confidence)) = confidence {
                        details.evidence_count = Some(inputs.evidence_count);
                        details.confidence = Some(confidence);
                        details.belief_factor = belief_add;
                    }
                    if session_recall {
                        details.intent = Some("session_recall");
                        // Report the routing lift over the pre-belief base so
                        // the two factors stay separable in explain.
                        details.intent_boost = Some(base / authority.factor);
                    }
                }
            }
        }
        out.sort_by(|a, b| {
            a.0.rank
                .partial_cmp(&b.0.rank)
                .unwrap_or(std::cmp::Ordering::Equal)
                // Deterministic tiebreak: equal fused scores (common when
                // two streams each contribute a rank-1 hit) previously fell
                // back to HashMap iteration order.
                .then_with(|| a.0.path.as_str().cmp(b.0.path.as_str()))
        });
        out.truncate(limit);
        // Label the superseded versions among the final hits so the caller can
        // tell historical versions from the current one. Only the opt-in path
        // can surface a non-latest id, so the default path skips this lookup
        // entirely and every hit keeps `superseded = false`.
        if include_superseded {
            let result_ids: Vec<PageId> = out.iter().map(|(hit, _)| hit.id).collect();
            let superseded = self
                .superseded_page_ids(workspace_id, project_id, result_ids)
                .await?;
            for (hit, _) in &mut out {
                hit.superseded = superseded.contains(&hit.id);
            }
        }
        Ok((out, timings, lexical_match))
    }

    /// The subset of `page_ids` that are superseded (non-latest) versions in
    /// the given project. Used by [`Self::hybrid_search`] to label opt-in
    /// `include_superseded` hits; the default path never calls it.
    async fn superseded_page_ids(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        page_ids: Vec<PageId>,
    ) -> StoreResult<std::collections::HashSet<PageId>> {
        if page_ids.is_empty() {
            return Ok(std::collections::HashSet::new());
        }
        self.with_conn(move |conn| {
            let mut values_clause = String::with_capacity(page_ids.len() * 5);
            let mut sql_params = Vec::with_capacity(page_ids.len() + 2);
            for (idx, page_id) in page_ids.iter().enumerate() {
                if idx > 0 {
                    values_clause.push_str(", ");
                }
                values_clause.push_str("(?)");
                sql_params.push(Value::Blob(page_id.as_bytes().to_vec()));
            }
            sql_params.push(Value::Blob(workspace_id.as_bytes().to_vec()));
            sql_params.push(Value::Blob(project_id.as_bytes().to_vec()));

            let sql = format!(
                "WITH requested(id) AS (VALUES {values_clause}) \
                 SELECT pages.id \
                 FROM requested \
                 JOIN pages ON pages.id = requested.id \
                 WHERE pages.workspace_id = ? \
                   AND pages.project_id = ? \
                   AND pages.is_latest = 0"
            );
            let mut stmt = conn.prepare(&sql)?;
            let rows = stmt.query_map(params_from_iter(sql_params.iter()), |row| {
                row.get::<_, Vec<u8>>(0)
            })?;
            let mut out = std::collections::HashSet::new();
            for row in rows {
                out.insert(PageId::from_slice(&row?)?);
            }
            Ok(out)
        })
        .await
    }

    /// Return the open handoff the next session should pick up.
    ///
    /// A manual handoff (`memory_handoff_begin`, which always sets
    /// `from_session_id = None`) is project-wide and always a candidate,
    /// whatever cwd it carries. An auto SessionEnd handoff
    /// (`from_session_id = Some`) is a candidate only when its cwd is an
    /// ancestor-or-equal of `cwd_filter` (path-boundary, the prior art's
    /// check rather than exact equality: a handoff left in `/repo` reaches a
    /// session in `/repo/api`, but never `/repo-other`). Among candidates a
    /// manual handoff wins over an auto one, then the most recent, with cwd
    /// specificity only breaking timestamp ties — so an explicit "where we left off" baton
    /// deterministically beats the heuristic SessionEnd handoff, regardless of
    /// whether the model passed a cwd. With `cwd_filter == None` every open
    /// handoff is a candidate (project-wide read, e.g. the web overview). The
    /// path-boundary is computed in Rust rather than SQL `LIKE` so `%`/`_` in a
    /// path can never act as a wildcard.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn latest_open_handoff(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        cwd_filter: Option<String>,
        owner_filter: OwnerFilter,
    ) -> StoreResult<Option<Handoff>> {
        self.open_handoff_for(workspace_id, project_id, cwd_filter, owner_filter, None)
            .await
    }

    /// [`Self::latest_open_handoff`] for automatic delivery to a starting
    /// session: the baton of a session that is still open and captured
    /// anything after `busy_since` is not a candidate.
    ///
    /// A turn checkpoint publishes a live session's baton, and nothing tells
    /// a closed terminal apart from a parallel session still at work in the
    /// same directory. Handing the baton of a session in use to a new one
    /// gives that session another conversation's context and consumes the
    /// baton its own successor needed. Once the session has been quiet since
    /// `busy_since`, its baton is deliverable again; ended sessions and
    /// manual handoffs are unaffected.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn startup_handoff(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        cwd_filter: Option<String>,
        owner_filter: OwnerFilter,
        busy_since: Timestamp,
    ) -> StoreResult<Option<Handoff>> {
        self.open_handoff_for(
            workspace_id,
            project_id,
            cwd_filter,
            owner_filter,
            Some(busy_since.as_microsecond()),
        )
        .await
    }

    async fn open_handoff_for(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        cwd_filter: Option<String>,
        owner_filter: OwnerFilter,
        busy_since: Option<i64>,
    ) -> StoreResult<Option<Handoff>> {
        self.with_conn(move |conn| {
            // Ownership belongs in the query, not just in
            // `is_handoff_candidate`: prompt-derived fields from another
            // operator must never be loaded or deserialized for this caller.
            let (owner_clause, owner_param) = handoff_owner_sql(&owner_filter, 3);
            let busy_index = if owner_param.is_some() { 4 } else { 3 };
            let busy_clause = if busy_since.is_some() {
                format!(
                    " AND NOT EXISTS (SELECT 1 FROM sessions s \
                         WHERE s.id = handoffs.from_session_id AND s.ended_at IS NULL \
                           AND EXISTS (SELECT 1 FROM observations o \
                                       WHERE o.session_id = s.id AND o.created_at > ?{busy_index}))"
                )
            } else {
                String::new()
            };
            let sql = format!(
                "SELECT id, workspace_id, project_id, from_session_id, from_agent, to_agent, \
                        cwd, summary, open_questions, next_steps, files_touched, state, \
                        created_at, accepted_by, accepted_at, accepted_by_session, \
                        owner_user, accepted_by_user \
                 FROM handoffs \
                 WHERE workspace_id = ?1 AND project_id = ?2 AND state = 'open'{owner_clause}{busy_clause} \
                 ORDER BY created_at DESC"
            );
            let mut stmt = conn.prepare(&sql)?;
            let mut binds: Vec<&dyn rusqlite::ToSql> =
                vec![workspace_id.as_bytes(), project_id.as_bytes()];
            if let Some(owner) = owner_param.as_ref() {
                binds.push(owner);
            }
            if let Some(since) = busy_since.as_ref() {
                binds.push(since);
            }
            let rows = stmt.query_map(binds.as_slice(), row_to_handoff)?;
            let mut selected: Option<Handoff> = None;
            for r in rows {
                let handoff = r??;
                if is_handoff_candidate(&handoff, cwd_filter.as_deref(), &owner_filter)
                    && selected
                        .as_ref()
                        .is_none_or(|current| prefer_handoff(&handoff, current).is_gt())
                {
                    selected = Some(handoff);
                }
            }
            Ok(selected)
        })
        .await
    }

    /// List pending cross-project messages for one side of a project's mailbox
    /// (V64). `Inbox` = mail addressed to the project (what it can pop);
    /// `Outbox` = mail the project has sent and can still cancel. Oldest first,
    /// capped at `limit`. See `docs/agent-messaging.md`.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn list_messages(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        mailbox: MessageBox,
        limit: usize,
    ) -> StoreResult<Vec<AgentMessage>> {
        let limit = limit.clamp(1, 200);
        self.with_conn(move |conn| {
            // Scope by the coordinate that owns this side of the mailbox: a
            // project only ever sees mail TO it (inbox) or FROM it (outbox).
            let predicate = match mailbox {
                MessageBox::Inbox => "to_workspace_id = ?1 AND to_project_id = ?2",
                MessageBox::Outbox => "from_workspace_id = ?1 AND from_project_id = ?2",
            };
            let sql = format!(
                "SELECT {cols} FROM agent_messages \
                 WHERE {predicate} AND state = 'pending' \
                 ORDER BY created_at ASC LIMIT {limit}",
                cols = crate::ops::MESSAGE_COLUMNS,
            );
            let mut stmt = conn.prepare(&sql)?;
            let rows = stmt.query_map(
                params![workspace_id.as_bytes(), project_id.as_bytes()],
                crate::ops::row_to_agent_message,
            )?;
            let mut out = Vec::new();
            for row in rows {
                out.push(row??);
            }
            Ok(out)
        })
        .await
    }

    /// Count pending messages per recipient project, in one grouped query.
    ///
    /// Backs the web project cards, which would otherwise pay one
    /// [`Self::pending_message_count`] per card. `viewer` filters recipients
    /// like [`Self::list_projects_with_stats`], so a repository the viewer may
    /// not read gets no row either.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn pending_inbox_counts(
        &self,
        viewer: Option<UserId>,
    ) -> StoreResult<Vec<InboxCount>> {
        self.with_conn(move |conn| {
            let visible = readable_repository_predicate("p.id", viewer);
            let mut stmt = conn.prepare(&format!(
                "SELECT w.name, p.name, COUNT(*) \
                 FROM agent_messages m \
                 JOIN projects p ON p.id = m.to_project_id AND p.workspace_id = m.to_workspace_id \
                 JOIN workspaces w ON w.id = p.workspace_id \
                 WHERE m.state = 'pending'{visible} \
                 GROUP BY p.id"
            ))?;
            let rows = stmt.query_map([], |row| {
                let pending: i64 = row.get(2)?;
                Ok(InboxCount {
                    workspace_name: row.get(0)?,
                    project_name: row.get(1)?,
                    pending: u64::try_from(pending).unwrap_or(0),
                })
            })?;
            let mut out = Vec::new();
            for row in rows {
                out.push(row?);
            }
            Ok(out)
        })
        .await
    }

    /// List a project's pending inbox with each sender named for display,
    /// oldest first, capped at `limit`.
    ///
    /// The sender's names come back only when `viewer` may read the sender's
    /// repository: the recipient is entitled to the message, not to learn the
    /// name of a restricted project it came from. See
    /// [`Self::list_messages`] for the unnamed form agents use.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn list_inbox_with_senders(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        viewer: Option<UserId>,
        limit: usize,
    ) -> StoreResult<Vec<InboxEntry>> {
        let limit = limit.clamp(1, 200);
        self.with_conn(move |conn| {
            let sender_visible = readable_repository_predicate("sp.id", viewer);
            let columns = crate::ops::MESSAGE_COLUMNS;
            // The sender names follow the message columns.
            let sender_at = columns.split(',').count();
            let mut stmt = conn.prepare(&format!(
                "SELECT m.*, sw.name, sp.name \
                 FROM (SELECT {columns} FROM agent_messages \
                       WHERE to_workspace_id = ?1 AND to_project_id = ?2 AND state = 'pending' \
                       ORDER BY created_at ASC LIMIT {limit}) m \
                 LEFT JOIN projects sp ON sp.id = m.from_project_id \
                                      AND sp.workspace_id = m.from_workspace_id{sender_visible} \
                 LEFT JOIN workspaces sw ON sw.id = sp.workspace_id \
                 ORDER BY m.created_at ASC"
            ))?;
            let rows = stmt.query_map(
                params![workspace_id.as_bytes(), project_id.as_bytes()],
                |row| {
                    let message = crate::ops::row_to_agent_message(row)?;
                    let workspace: Option<String> = row.get(sender_at)?;
                    let project: Option<String> = row.get(sender_at + 1)?;
                    Ok((message, workspace.zip(project)))
                },
            )?;
            let mut out = Vec::new();
            for row in rows {
                let (message, sender) = row?;
                out.push(InboxEntry {
                    message: message?,
                    sender,
                });
            }
            Ok(out)
        })
        .await
    }

    /// Count pending messages addressed to a project's inbox (V64). Backs the
    /// on-start inbox notice and `memory_briefing`'s `pending_message_count`.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn pending_message_count(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> StoreResult<u64> {
        self.with_conn(move |conn| {
            count_bound(
                conn,
                "SELECT COUNT(*) FROM agent_messages \
                 WHERE to_workspace_id = ?1 AND to_project_id = ?2 AND state = 'pending'",
                &[workspace_id.as_bytes(), project_id.as_bytes()],
            )
        })
        .await
    }

    /// List a project's handoffs, newest first.
    ///
    /// The system had no handoff listing at all: every reader fetched "the
    /// single open one" and consumed it. That made a mis-delivered or
    /// prematurely consumed baton unrecoverable and invisible — there was no
    /// way to ask what happened to it. `state = None` returns every state so an
    /// operator can find an already-accepted handoff and read it back.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn list_handoffs(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        state: Option<HandoffState>,
        owner_filter: OwnerFilter,
        limit: usize,
    ) -> StoreResult<Vec<Handoff>> {
        let state = state.map(|s| s.as_str().to_string());
        self.with_conn(move |conn| {
            // Push the owner predicate and the limit into SQL rather than
            // filtering a fully materialised result set in Rust: without them
            // this reads (and sorts) every handoff the project has ever
            // accumulated, and the caller's limit provides no protection
            // because it is applied after the rows are already loaded.
            let (sql, owner_param) = handoff_listing_sql(state.is_some(), &owner_filter, limit);
            let mut stmt = conn.prepare(&sql)?;
            let mut binds: Vec<&dyn rusqlite::ToSql> =
                vec![workspace_id.as_bytes(), project_id.as_bytes()];
            if let Some(state) = state.as_ref() {
                binds.push(state);
            }
            if let Some(owner) = owner_param.as_ref() {
                binds.push(owner);
            }
            let rows = stmt.query_map(binds.as_slice(), row_to_handoff)?;
            let mut out = Vec::new();
            for row in rows {
                out.push(row??);
            }
            Ok(out)
        })
        .await
    }

    /// Look up a handoff by id.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn handoff_by_id(&self, handoff_id: HandoffId) -> StoreResult<Option<Handoff>> {
        self.with_conn(move |conn| {
            let row = conn
                .query_row(
                    "SELECT id, workspace_id, project_id, from_session_id, from_agent, to_agent, \
                            cwd, summary, open_questions, next_steps, files_touched, state, \
                            created_at, accepted_by, accepted_at, accepted_by_session, \
                            owner_user, accepted_by_user \
                     FROM handoffs WHERE id = ?1",
                    params![handoff_id.as_bytes()],
                    row_to_handoff,
                )
                .optional()?;
            row.transpose()
        })
        .await
    }

    /// Look up a handoff by id within an exact scope and ownership boundary.
    ///
    /// This is the object-authorization form used by exact-id operations. The
    /// scope and owner predicates run before prompt-derived columns are loaded,
    /// so callers cannot distinguish a foreign id from an absent one or inspect
    /// another operator's malformed/private row as a side effect of checking it.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn handoff_by_id_in_scope(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        handoff_id: HandoffId,
        owner_filter: OwnerFilter,
    ) -> StoreResult<Option<Handoff>> {
        self.with_conn(move |conn| {
            let (owner_clause, owner_param) = handoff_owner_sql(&owner_filter, 4);
            let sql = format!(
                "SELECT id, workspace_id, project_id, from_session_id, from_agent, to_agent, \
                        cwd, summary, open_questions, next_steps, files_touched, state, \
                        created_at, accepted_by, accepted_at, accepted_by_session, \
                        owner_user, accepted_by_user \
                 FROM handoffs \
                 WHERE workspace_id = ?1 AND project_id = ?2 AND id = ?3{owner_clause}"
            );
            let mut stmt = conn.prepare(&sql)?;
            let mut binds: Vec<&dyn rusqlite::ToSql> = vec![
                workspace_id.as_bytes(),
                project_id.as_bytes(),
                handoff_id.as_bytes(),
            ];
            if let Some(owner) = owner_param.as_ref() {
                binds.push(owner);
            }
            let row = stmt
                .query_row(binds.as_slice(), row_to_handoff)
                .optional()?;
            row.transpose()
        })
        .await
    }

    /// The handoff `session` claimed in this scope while it is still running —
    /// its own SessionStart delivery, so the baton is already in that session's
    /// context — or `None`.
    ///
    /// The session id is a routing coordinate the caller supplies, never
    /// identity: the scope and owner predicates bound the answer, so a forged
    /// id can only confirm a claim on a row the caller could have claimed
    /// itself. A receiving session holds at most one baton, and one that ended
    /// no longer has a context the baton could be in.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn handoff_claimed_by_live_session(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        session: SessionId,
        owner_filter: OwnerFilter,
    ) -> StoreResult<Option<HandoffId>> {
        self.with_conn(move |conn| {
            let (owner_clause, owner_param) = handoff_owner_sql(&owner_filter, 4);
            let sql = format!(
                "SELECT id FROM handoffs \
                 WHERE workspace_id = ?1 AND project_id = ?2 \
                   AND state = 'accepted' AND accepted_by_session = ?3{owner_clause} \
                   AND EXISTS (SELECT 1 FROM sessions s \
                               WHERE s.id = ?3 AND s.ended_at IS NULL) \
                 ORDER BY accepted_at DESC LIMIT 1"
            );
            let mut binds: Vec<&dyn rusqlite::ToSql> = vec![
                workspace_id.as_bytes(),
                project_id.as_bytes(),
                session.as_bytes(),
            ];
            if let Some(owner) = owner_param.as_ref() {
                binds.push(owner);
            }
            let id: Option<Vec<u8>> = conn
                .query_row(&sql, binds.as_slice(), |row| row.get(0))
                .optional()?;
            Ok(id.map(|id| HandoffId::from_slice(&id)).transpose()?)
        })
        .await
    }

    /// Snapshot the database to `dest_path` using SQLite's online backup
    /// API. The source DB stays writable for the duration of the copy.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn snapshot_to(&self, dest_path: PathBuf) -> StoreResult<()> {
        self.with_conn(move |conn| {
            conn.backup(rusqlite::DatabaseName::Main, &dest_path, None)
                .map_err(StoreError::from)
        })
        .await
    }

    /// Assemble a [`BriefingSnapshot`] — pure SQL aggregation across
    /// the `pages` / `sessions` / `observations` / `handoffs` tables.
    /// No LLM, no schema reads outside what's already there.
    ///
    /// `recent_pages_limit` caps the `recent_pages` array; pass a
    /// small number (5-20) — this is meant to be skimmed, not paged
    /// through.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    #[allow(clippy::too_many_lines)]
    pub async fn briefing(
        &self,
        recent_pages_limit: usize,
        owner_filter: OwnerFilter,
    ) -> StoreResult<BriefingSnapshot> {
        self.briefing_with_slot_visibility(
            recent_pages_limit,
            owner_filter,
            &ai_memory_core::SlotVisibility::All,
        )
        .await
    }

    /// Assemble a global briefing while filtering operator-owned slot pages.
    ///
    /// This additive variant preserves [`Self::briefing`] for existing callers.
    /// The filter only controls agent-context injection; exact page reads remain
    /// project-wide.
    pub async fn briefing_with_slot_visibility(
        &self,
        recent_pages_limit: usize,
        owner_filter: OwnerFilter,
        slot_visibility: &ai_memory_core::SlotVisibility,
    ) -> StoreResult<BriefingSnapshot> {
        let recent_limit = recent_pages_limit.clamp(1, 100) as i64;
        let slot_visibility = slot_visibility.clone();
        let (recent_slot_sql, recent_glob) = slot_exclusion_sql(&slot_visibility, 3);
        self.with_conn(move |conn| {
            let kind_expr = page_kind_expr("path", "frontmatter_json");
            let now_us = jiff::Timestamp::now().as_microsecond();
            let day_us: i64 = 86_400 * 1_000_000;
            let cutoff_7d = now_us - 7 * day_us;
            let cutoff_30d = now_us - 30 * day_us;

            let counts = StatusCounts {
                // Every page list in this snapshot hides TTL-expired pages, so
                // the headline count has to hide them too or the brief
                // advertises pages the agent cannot see anywhere in it.
                // `pages_all` is deliberately the raw all-versions total.
                pages_latest: count_bound(
                    conn,
                    &format!(
                        "SELECT COUNT(*) FROM pages WHERE is_latest = 1{not_expired}",
                        not_expired = not_expired("pages", "?1"),
                    ),
                    &[&now_us],
                )?,
                pages_all: count(conn, "SELECT COUNT(*) FROM pages")?,
                sessions: count(conn, "SELECT COUNT(*) FROM sessions")?,
                observations: count(conn, "SELECT COUNT(*) FROM observations")?,
                evidence_rows: count(conn, "SELECT COUNT(*) FROM page_evidence")?,
            };

            let activity_7d = window_activity(conn, 7, cutoff_7d, now_us)?;
            let activity_30d = window_activity(conn, 30, cutoff_30d, now_us)?;

            let last_observation_at: Option<i64> = conn
                .query_row("SELECT MAX(created_at) FROM observations", [], |row| {
                    row.get::<_, Option<i64>>(0)
                })
                .optional()?
                .flatten();
            let last_observation_at = last_observation_at
                .and_then(|us| jiff::Timestamp::from_microsecond(us).ok())
                .map(|ts| ts.to_string());

            let (owner_clause, owner_param) = handoff_owner_sql(&owner_filter, 1);
            let mut owner_binds: Vec<&dyn rusqlite::ToSql> = Vec::new();
            if let Some(owner) = owner_param.as_ref() {
                owner_binds.push(owner);
            }
            let pending_handoff_count: u64 = count_bound(
                conn,
                &format!("SELECT COUNT(*) FROM handoffs WHERE state = 'open'{owner_clause}"),
                &owner_binds,
            )?;

            // Rules: any `is_latest = 1` page under `_rules/`.
            // Routed there automatically by the consolidator when
            // `kind = "rule"` — see consolidator.rs::slugify_for_rule.
            let mut rules_stmt = conn.prepare_cached(&format!(
                "SELECT path, title, {kind_expr} AS kind, \
                        updated_at \
                 FROM pages \
                  WHERE is_latest = 1 AND path GLOB '_rules/*'{not_expired} \
                  ORDER BY updated_at DESC",
                not_expired = not_expired("pages", "?1"),
            ))?;
            let rules: Vec<BriefingPage> = rules_stmt
                .query_map(params![now_us], briefing_page_from_row)?
                .collect::<Result<Vec<_>, _>>()?
                .into_iter()
                .collect::<Result<Vec<_>, _>>()?;

            let mut slots_stmt = conn.prepare_cached(&format!(
                "SELECT path, title, {kind_expr} AS kind, \
                        updated_at \
                 FROM pages \
                  WHERE is_latest = 1 AND path GLOB '_slots/*'{not_expired} \
                  ORDER BY path ASC",
                not_expired = not_expired("pages", "?1"),
            ))?;
            let slots: Vec<BriefingPage> = slots_stmt
                .query_map(params![now_us], briefing_page_from_row)?
                .collect::<Result<Vec<_>, _>>()?
                .into_iter()
                .collect::<Result<Vec<_>, _>>()?;

            let mut recent_stmt = conn.prepare_cached(&format!(
                "SELECT path, title, {kind_expr} AS kind, \
                        updated_at \
                 FROM pages \
                 WHERE is_latest = 1 AND ({recent_slot_sql}){not_expired} \
                 ORDER BY updated_at DESC \
                 LIMIT ?1",
                not_expired = not_expired("pages", "?2"),
            ))?;
            let recent_rows = match recent_glob.as_deref() {
                Some(glob) => recent_stmt
                    .query_map(params![recent_limit, now_us, glob], briefing_page_from_row)?,
                None => {
                    recent_stmt.query_map(params![recent_limit, now_us], briefing_page_from_row)?
                }
            };
            let recent_pages: Vec<BriefingPage> = recent_rows
                .collect::<Result<Vec<_>, _>>()?
                .into_iter()
                .collect::<Result<Vec<_>, _>>()?;

            let mut snapshot = BriefingSnapshot {
                counts,
                activity_7d,
                activity_30d,
                last_observation_at,
                pending_handoff_count,
                // No single recipient project for a current/default- or
                // workspace-scope briefing; the inbox count is project-scoped.
                pending_message_count: 0,
                rules,
                slots,
                recent_pages,
                cross_project_dependents: 0,
                cross_project_dependencies: 0,
                settled: Vec::new(),
                // The pinned standing-context list is a project-scoped signal;
                // an aggregate current/workspace briefing leaves it empty.
                pinned: Vec::new(),
            };
            filter_briefing_slots(&mut snapshot, &slot_visibility);
            Ok(snapshot)
        })
        .await
    }

    /// Assemble a project-scoped [`BriefingSnapshot`].
    ///
    /// `settled_first` opts into populating [`BriefingSnapshot::settled`]
    /// with the project's highest-standing `rule`/`decision` pages (P4,
    /// docs/design-hindsight-borrowings.md §5); `false` leaves the
    /// snapshot byte-for-byte as before.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    #[allow(clippy::too_many_lines)]
    pub async fn briefing_for_project(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        recent_pages_limit: usize,
        owner_filter: OwnerFilter,
        settled_first: bool,
    ) -> StoreResult<BriefingSnapshot> {
        self.briefing_for_project_with_slot_visibility(
            workspace_id,
            project_id,
            recent_pages_limit,
            owner_filter,
            &ai_memory_core::SlotVisibility::All,
            settled_first,
        )
        .await
    }

    /// Assemble a project briefing while filtering operator-owned slot
    /// pages. See [`ReaderPool::briefing_for_project`] for `settled_first`.
    pub async fn briefing_for_project_with_slot_visibility(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        recent_pages_limit: usize,
        owner_filter: OwnerFilter,
        slot_visibility: &ai_memory_core::SlotVisibility,
        settled_first: bool,
    ) -> StoreResult<BriefingSnapshot> {
        let recent_limit = recent_pages_limit.clamp(1, 100) as i64;
        let slot_visibility = slot_visibility.clone();
        let (recent_slot_sql, recent_glob) = slot_exclusion_sql(&slot_visibility, 5);
        self.with_conn(move |conn| {
            let kind_expr = page_kind_expr("path", "frontmatter_json");
            let now_us = jiff::Timestamp::now().as_microsecond();
            let day_us: i64 = 86_400 * 1_000_000;
            let cutoff_7d = now_us - 7 * day_us;
            let cutoff_30d = now_us - 30 * day_us;

            let counts = StatusCounts {
                // See the TTL note in `briefing_with_slot_visibility`.
                pages_latest: count_bound(
                    conn,
                    &format!(
                        "SELECT COUNT(*) FROM pages \
                         WHERE workspace_id = ?1 AND project_id = ?2 AND is_latest = 1{not_expired}",
                        not_expired = not_expired("pages", "?3"),
                    ),
                    &[workspace_id.as_bytes(), project_id.as_bytes(), &now_us],
                )?,
                pages_all: count_project(
                    conn,
                    "SELECT COUNT(*) FROM pages WHERE workspace_id = ?1 AND project_id = ?2",
                    workspace_id,
                    project_id,
                )?,
                sessions: count_project(
                    conn,
                    "SELECT COUNT(*) FROM sessions WHERE workspace_id = ?1 AND project_id = ?2",
                    workspace_id,
                    project_id,
                )?,
                observations: count_project(
                    conn,
                    "SELECT COUNT(*) FROM observations WHERE workspace_id = ?1 AND project_id = ?2",
                    workspace_id,
                    project_id,
                )?,
                evidence_rows: count_project(
                    conn,
                    "SELECT COUNT(*) FROM page_evidence pe \
                     JOIN pages p ON p.id = pe.page_id \
                     WHERE p.workspace_id = ?1 AND p.project_id = ?2",
                    workspace_id,
                    project_id,
                )?,
            };

            let activity_7d =
                window_activity_project(conn, 7, cutoff_7d, now_us, workspace_id, project_id)?;
            let activity_30d =
                window_activity_project(conn, 30, cutoff_30d, now_us, workspace_id, project_id)?;

            let last_observation_at: Option<i64> = conn
                .query_row(
                    "SELECT MAX(created_at) FROM observations WHERE workspace_id = ?1 AND project_id = ?2",
                    params![workspace_id.as_bytes(), project_id.as_bytes()],
                    |row| row.get::<_, Option<i64>>(0),
                )
                .optional()?
                .flatten();
            let last_observation_at = last_observation_at
                .and_then(|us| jiff::Timestamp::from_microsecond(us).ok())
                .map(|ts| ts.to_string());

            let (owner_clause, owner_param) = handoff_owner_sql(&owner_filter, 3);
            let mut owner_binds: Vec<&dyn rusqlite::ToSql> =
                vec![workspace_id.as_bytes(), project_id.as_bytes()];
            if let Some(owner) = owner_param.as_ref() {
                owner_binds.push(owner);
            }
            let pending_handoff_count = count_bound(
                conn,
                &format!(
                    "SELECT COUNT(*) FROM handoffs \
                     WHERE workspace_id = ?1 AND project_id = ?2 AND state = 'open'{owner_clause}"
                ),
                &owner_binds,
            )?;
            // Pending cross-project inbox mail addressed to THIS project (V64).
            // Not owner-filtered: the inbox is project-addressed and shared.
            let pending_message_count = count_bound(
                conn,
                "SELECT COUNT(*) FROM agent_messages \
                 WHERE to_workspace_id = ?1 AND to_project_id = ?2 AND state = 'pending'",
                &[workspace_id.as_bytes(), project_id.as_bytes()],
            )?;

            let mut rules_stmt = conn.prepare_cached(&format!(
                "SELECT path, title, {kind_expr} AS kind, \
                        updated_at \
                 FROM pages \
                  WHERE workspace_id = ?1 AND project_id = ?2 AND is_latest = 1 AND path GLOB '_rules/*'{not_expired} \
                  ORDER BY updated_at DESC",
                not_expired = not_expired("pages", "?3"),
            ))?;
            let rules: Vec<BriefingPage> = rules_stmt
                .query_map(params![workspace_id.as_bytes(), project_id.as_bytes(), now_us], briefing_page_from_row)?
                .collect::<Result<Vec<_>, _>>()?
                .into_iter()
                .collect::<Result<Vec<_>, _>>()?;

            let mut slots_stmt = conn.prepare_cached(&format!(
                "SELECT path, title, {kind_expr} AS kind, \
                        updated_at \
                 FROM pages \
                  WHERE workspace_id = ?1 AND project_id = ?2 AND is_latest = 1 AND path GLOB '_slots/*'{not_expired} \
                  ORDER BY path ASC",
                not_expired = not_expired("pages", "?3"),
            ))?;
            let slots: Vec<BriefingPage> = slots_stmt
                .query_map(params![workspace_id.as_bytes(), project_id.as_bytes(), now_us], briefing_page_from_row)?
                .collect::<Result<Vec<_>, _>>()?
                .into_iter()
                .collect::<Result<Vec<_>, _>>()?;

            let mut recent_stmt = conn.prepare_cached(&format!(
                "SELECT path, title, {kind_expr} AS kind, \
                        updated_at \
                 FROM pages \
                 WHERE workspace_id = ?1 AND project_id = ?2 AND is_latest = 1 \
                   AND ({recent_slot_sql}){not_expired} \
                 ORDER BY updated_at DESC \
                 LIMIT ?3",
                not_expired = not_expired("pages", "?4"),
            ))?;
            let recent_rows = match recent_glob.as_deref() {
                Some(glob) => recent_stmt.query_map(
                    params![
                        workspace_id.as_bytes(),
                        project_id.as_bytes(),
                        recent_limit,
                        now_us,
                        glob
                    ],
                    briefing_page_from_row,
                )?,
                None => recent_stmt.query_map(
                    params![
                        workspace_id.as_bytes(),
                        project_id.as_bytes(),
                        recent_limit,
                        now_us
                    ],
                    briefing_page_from_row,
                )?,
            };
            let recent_pages: Vec<BriefingPage> = recent_rows
                .collect::<Result<Vec<_>, _>>()?
                .into_iter()
                .collect::<Result<Vec<_>, _>>()?;

            let (cross_project_dependents, cross_project_dependencies) =
                cross_project_degree(conn, workspace_id, project_id, now_us)?;

            let settled: Vec<SettledPage> = if settled_first {
                let settled_kind_expr = page_kind_expr("pages.path", "pages.frontmatter_json");
                let mut settled_stmt = conn.prepare_cached(&format!(
                    "SELECT pages.path, pages.title, {settled_kind_expr} AS kind, \
                            COUNT(page_evidence.source_id) AS evidence_count \
                     FROM pages \
                     LEFT JOIN page_evidence ON page_evidence.page_id = pages.id \
                     WHERE pages.workspace_id = ?1 AND pages.project_id = ?2 \
                       AND pages.is_latest = 1 \
                       AND ({settled_kind_expr}) IN ('rule', 'decision'){not_expired} \
                     GROUP BY pages.id \
                     ORDER BY evidence_count DESC, pages.updated_at DESC \
                     LIMIT 8",
                    not_expired = not_expired("pages", "?3"),
                ))?;
                settled_stmt
                    .query_map(
                        params![workspace_id.as_bytes(), project_id.as_bytes(), now_us],
                        settled_page_from_row,
                    )?
                    .collect::<Result<Vec<_>, _>>()?
            } else {
                Vec::new()
            };

            // Pinned latest pages (`pinned = 1`), newest first and bounded —
            // standing operator-curated context for SessionStart hot-context
            // ("pin before search"). Empty result → the field is skipped in
            // JSON, so a project with no pins keeps the prior briefing shape.
            let mut pinned_stmt = conn.prepare_cached(&format!(
                "SELECT path, title, {kind_expr} AS kind, \
                        updated_at \
                 FROM pages \
                  WHERE workspace_id = ?1 AND project_id = ?2 AND is_latest = 1 AND pinned = 1{not_expired} \
                  ORDER BY updated_at DESC \
                  LIMIT {BRIEFING_PINNED_LIMIT}",
                not_expired = not_expired("pages", "?3"),
            ))?;
            let pinned: Vec<BriefingPage> = pinned_stmt
                .query_map(params![workspace_id.as_bytes(), project_id.as_bytes(), now_us], briefing_page_from_row)?
                .collect::<Result<Vec<_>, _>>()?
                .into_iter()
                .collect::<Result<Vec<_>, _>>()?;

            let mut snapshot = BriefingSnapshot {
                counts,
                activity_7d,
                activity_30d,
                last_observation_at,
                pending_handoff_count,
                pending_message_count,
                rules,
                slots,
                recent_pages,
                cross_project_dependents,
                cross_project_dependencies,
                settled,
                pinned,
            };
            filter_briefing_slots(&mut snapshot, &slot_visibility);
            Ok(snapshot)
        })
        .await
    }

    /// Fetch the pages that make up a session-start project brief: the
    /// "core" pages WITH bodies (pinned, plus everything under `_rules/`
    /// and `_slots/` — the operator-curated, highest-signal memory), and
    /// the most-recently-updated page titles WITHOUT bodies (pointers the
    /// agent can follow up on via `memory_query`).
    ///
    /// Core pages are ordered pinned-first then by path, so a char-budget
    /// cut in the renderer drops the least-curated content last. Both
    /// limits are clamped defensively; the renderer applies the actual
    /// byte budget.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn session_brief_pages(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        core_pages_limit: usize,
        recent_pages_limit: usize,
    ) -> StoreResult<(Vec<BriefPageBody>, Vec<BriefingPage>)> {
        self.session_brief_pages_with_slot_visibility(
            workspace_id,
            project_id,
            core_pages_limit,
            recent_pages_limit,
            ai_memory_core::SlotVisibility::All,
        )
        .await
    }

    /// Fetch session-start pages while excluding other operators' slot pages.
    pub async fn session_brief_pages_with_slot_visibility(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        core_pages_limit: usize,
        recent_pages_limit: usize,
        slot_visibility: ai_memory_core::SlotVisibility,
    ) -> StoreResult<(Vec<BriefPageBody>, Vec<BriefingPage>)> {
        let core_limit = core_pages_limit.clamp(1, 100) as i64;
        let recent_limit = recent_pages_limit.clamp(1, 100) as i64;
        let (slot_sql, slot_glob) = slot_visibility_sql(&slot_visibility, 5);
        let (recent_slot_sql, recent_glob) = slot_exclusion_sql(&slot_visibility, 5);
        self.with_conn(move |conn| {
            let kind_expr = page_kind_expr("path", "frontmatter_json");
            let core_sql = format!(
                "SELECT path, title, body, pinned, updated_at, frontmatter_json \
                 FROM pages \
                 WHERE workspace_id = ?1 AND project_id = ?2 AND is_latest = 1{not_expired} \
                   AND (path GLOB '_rules/*' \
                        OR (pinned = 1 AND path NOT GLOB '_slots/*') \
                        OR ({slot_sql})) \
                 ORDER BY pinned DESC, path ASC \
                 LIMIT ?3",
                not_expired = not_expired("pages", "?4"),
            );
            let mut core_stmt = conn.prepare_cached(&core_sql)?;
            let core_row = |row: &rusqlite::Row<'_>| {
                let updated_us: i64 = row.get(4)?;
                Ok((
                    row.get::<_, String>(0)?,
                    row.get::<_, String>(1)?,
                    row.get::<_, String>(2)?,
                    row.get::<_, i64>(3)? != 0,
                    updated_us,
                    row.get::<_, String>(5)?,
                ))
            };
            let core_rows = match slot_glob.as_deref() {
                Some(glob) => core_stmt.query_map(
                    params![
                        workspace_id.as_bytes(),
                        project_id.as_bytes(),
                        core_limit,
                        now_us(),
                        glob
                    ],
                    core_row,
                )?,
                None => core_stmt.query_map(
                    params![
                        workspace_id.as_bytes(),
                        project_id.as_bytes(),
                        core_limit,
                        now_us()
                    ],
                    core_row,
                )?,
            };
            let core: Vec<BriefPageBody> = core_rows
                .collect::<Result<Vec<_>, _>>()?
                .into_iter()
                .map(|(path, title, body, pinned, updated_us, frontmatter)| {
                    jiff::Timestamp::from_microsecond(updated_us)
                        .map(|ts| BriefPageBody {
                            path,
                            title,
                            body,
                            pinned,
                            updated_at: ts.to_string(),
                            frontmatter_json: serde_json::from_str(&frontmatter)
                                .unwrap_or_else(|_| serde_json::json!({})),
                        })
                        .map_err(|e| {
                            StoreError::Memory(ai_memory_core::MemoryError::MalformedRecord(
                                format!("bad updated_at: {e}"),
                            ))
                        })
                })
                .collect::<StoreResult<Vec<_>>>()?;

            let mut recent_stmt = conn.prepare_cached(&format!(
                "SELECT path, title, {kind_expr} AS kind, \
                        updated_at \
                 FROM pages \
                 WHERE workspace_id = ?1 AND project_id = ?2 AND is_latest = 1 \
                   AND ({recent_slot_sql}){not_expired} \
                 ORDER BY updated_at DESC \
                 LIMIT ?3",
                not_expired = not_expired("pages", "?4"),
            ))?;
            let recent_rows = match recent_glob.as_deref() {
                Some(glob) => recent_stmt.query_map(
                    params![
                        workspace_id.as_bytes(),
                        project_id.as_bytes(),
                        recent_limit,
                        now_us(),
                        glob
                    ],
                    briefing_page_from_row,
                )?,
                None => recent_stmt.query_map(
                    params![
                        workspace_id.as_bytes(),
                        project_id.as_bytes(),
                        recent_limit,
                        now_us()
                    ],
                    briefing_page_from_row,
                )?,
            };
            let recent: Vec<BriefingPage> = recent_rows
                .collect::<Result<Vec<_>, _>>()?
                .into_iter()
                .collect::<Result<Vec<_>, _>>()?;

            Ok((core, recent))
        })
        .await
    }

    /// Return the latest open handoff for the workspace, aggregating
    /// across all of its projects (no project filter).
    ///
    /// `viewer` confines "all of its projects" to those that user may read. A
    /// handoff with no owner is visible to everyone who can see its
    /// repository, which is exactly why it must not be visible to someone who
    /// cannot: its summary, next steps and project name are the repository's
    /// content. Filtered in SQL for the same reason as the owner predicate —
    /// the query keeps its `LIMIT 1`.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn latest_open_handoff_for_workspace(
        &self,
        workspace_id: WorkspaceId,
        owner_filter: OwnerFilter,
        viewer: Option<UserId>,
    ) -> StoreResult<Option<Handoff>> {
        let visible = readable_repository_predicate("project_id", viewer);
        self.with_conn(move |conn| {
            // The owner predicate is pushed into SQL (rather than filtered after
            // the fact like the project-scoped lookup) because this query keeps
            // its `LIMIT 1`: filtering afterwards would return nothing whenever
            // the newest open handoff in the workspace happened to belong to
            // somebody else.
            let owner_clause = match &owner_filter {
                OwnerFilter::Any => "",
                OwnerFilter::User(_) => " AND (owner_user IS NULL OR owner_user = ?2)",
                OwnerFilter::Unattributed => " AND owner_user IS NULL",
            };
            let sql = format!(
                "SELECT id, workspace_id, project_id, from_session_id, from_agent, to_agent, \
                        cwd, summary, open_questions, next_steps, files_touched, state, \
                        created_at, accepted_by, accepted_at, accepted_by_session, \
                        owner_user, accepted_by_user \
                 FROM handoffs \
                 WHERE workspace_id = ?1 AND state = 'open'{owner_clause}{visible} \
                 ORDER BY created_at DESC LIMIT 1"
            );
            let row_opt = match &owner_filter {
                OwnerFilter::User(user) => conn
                    .query_row(&sql, params![workspace_id.as_bytes(), user], row_to_handoff)
                    .optional()?,
                _ => conn
                    .query_row(&sql, params![workspace_id.as_bytes()], row_to_handoff)
                    .optional()?,
            };
            row_opt.transpose()
        })
        .await
    }

    /// Look up a workspace name by id.
    ///
    /// Returns `None` when no matching workspace exists. Used by the
    /// admission webhook chain to populate `AdmissionContext.workspace`
    /// so external webhooks can address the page by human name without
    /// re-implementing UUID→name lookup against the engine's store.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn workspace_name_by_id(
        &self,
        workspace_id: WorkspaceId,
    ) -> StoreResult<Option<String>> {
        self.with_conn(move |conn| {
            let row_opt = conn
                .query_row(
                    "SELECT name FROM workspaces WHERE id = ?1",
                    params![workspace_id.as_bytes()],
                    |row| row.get::<_, String>(0),
                )
                .optional()?;
            Ok(row_opt)
        })
        .await
    }

    /// Look up a project name by id within a workspace.
    ///
    /// Returns `None` when no matching project exists.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn project_name_by_id(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> StoreResult<Option<String>> {
        self.with_conn(move |conn| {
            let row_opt = conn
                .query_row(
                    "SELECT name FROM projects WHERE id = ?1 AND workspace_id = ?2",
                    params![project_id.as_bytes(), workspace_id.as_bytes()],
                    |row| row.get::<_, String>(0),
                )
                .optional()?;
            Ok(row_opt)
        })
        .await
    }

    /// Build a [`BriefingSnapshot`] aggregated across all projects in a
    /// workspace.
    ///
    /// Mirrors [`ReaderPool::briefing_for_project`] but scopes every query
    /// to the workspace only (no `project_id` filter).
    ///
    /// `viewer` narrows "all projects" to the ones that user may read (#708):
    /// every count, window, rule, slot and recent page below is taken over
    /// those alone, so an aggregate cannot be used to learn how much is
    /// happening in repositories they cannot open. `None` aggregates the whole
    /// workspace, as before.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn briefing_for_workspace(
        &self,
        workspace_id: WorkspaceId,
        recent_pages_limit: usize,
        owner_filter: OwnerFilter,
        viewer: Option<UserId>,
    ) -> StoreResult<BriefingSnapshot> {
        self.briefing_for_workspace_with_slot_visibility(
            workspace_id,
            recent_pages_limit,
            owner_filter,
            &ai_memory_core::SlotVisibility::All,
            viewer,
        )
        .await
    }

    /// Assemble a workspace briefing while filtering operator-owned slots.
    /// `viewer` as for [`Self::briefing_for_workspace`].
    pub async fn briefing_for_workspace_with_slot_visibility(
        &self,
        workspace_id: WorkspaceId,
        recent_pages_limit: usize,
        owner_filter: OwnerFilter,
        slot_visibility: &ai_memory_core::SlotVisibility,
        viewer: Option<UserId>,
    ) -> StoreResult<BriefingSnapshot> {
        let recent_limit = recent_pages_limit.clamp(1, 100) as i64;
        let slot_visibility = slot_visibility.clone();
        let (recent_slot_sql, recent_glob) = slot_exclusion_sql(&slot_visibility, 4);
        // Spliced rather than bound: this function runs a dozen statements
        // with their own parameter numbering. See `readable_repository_predicate`.
        let visible = readable_repository_predicate("project_id", viewer);
        self.with_conn(move |conn| {
            let kind_expr = page_kind_expr("path", "frontmatter_json");
            let now_us = jiff::Timestamp::now().as_microsecond();
            let day_us: i64 = 86_400 * 1_000_000;
            let cutoff_7d = now_us - 7 * day_us;
            let cutoff_30d = now_us - 30 * day_us;

            let counts = StatusCounts {
                // See the TTL note in `briefing_with_slot_visibility`.
                pages_latest: count_bound(
                    conn,
                    &format!(
                        "SELECT COUNT(*) FROM pages \
                         WHERE workspace_id = ?1 AND is_latest = 1{visible}{not_expired}",
                        not_expired = not_expired("pages", "?2"),
                    ),
                    &[workspace_id.as_bytes(), &now_us],
                )?,
                pages_all: count_workspace(
                    conn,
                    &format!("SELECT COUNT(*) FROM pages WHERE workspace_id = ?1{visible}"),
                    workspace_id,
                )?,
                sessions: count_workspace(
                    conn,
                    &format!("SELECT COUNT(*) FROM sessions WHERE workspace_id = ?1{visible}"),
                    workspace_id,
                )?,
                observations: count_workspace(
                    conn,
                    &format!("SELECT COUNT(*) FROM observations WHERE workspace_id = ?1{visible}"),
                    workspace_id,
                )?,
                evidence_rows: count_workspace(
                    conn,
                    "SELECT COUNT(*) FROM page_evidence pe \
                     JOIN pages p ON p.id = pe.page_id \
                     WHERE p.workspace_id = ?1",
                    workspace_id,
                )?,
            };

            let activity_7d =
                window_activity_workspace(conn, 7, cutoff_7d, now_us, workspace_id, &visible)?;
            let activity_30d =
                window_activity_workspace(conn, 30, cutoff_30d, now_us, workspace_id, &visible)?;

            let last_observation_at: Option<i64> = conn
                .query_row(
                    &format!(
                        "SELECT MAX(created_at) FROM observations WHERE workspace_id = ?1{visible}"
                    ),
                    params![workspace_id.as_bytes()],
                    |row| row.get::<_, Option<i64>>(0),
                )
                .optional()?
                .flatten();
            let last_observation_at = last_observation_at
                .and_then(|us| jiff::Timestamp::from_microsecond(us).ok())
                .map(|ts| ts.to_string());

            let (owner_clause, owner_param) = handoff_owner_sql(&owner_filter, 2);
            let mut owner_binds: Vec<&dyn rusqlite::ToSql> = vec![workspace_id.as_bytes()];
            if let Some(owner) = owner_param.as_ref() {
                owner_binds.push(owner);
            }
            let pending_handoff_count = count_bound(
                conn,
                &format!(
                    "SELECT COUNT(*) FROM handoffs \
                     WHERE workspace_id = ?1 AND state = 'open'{owner_clause}{visible}"
                ),
                &owner_binds,
            )?;

            let mut rules_stmt = conn.prepare_cached(&format!(
                "SELECT path, title, {kind_expr} AS kind, \
                        updated_at \
                 FROM pages \
                  WHERE workspace_id = ?1 AND is_latest = 1 AND path GLOB '_rules/*'{not_expired}{visible} \
                  ORDER BY updated_at DESC",
                not_expired = not_expired("pages", "?2"),
            ))?;
            let rules: Vec<BriefingPage> = rules_stmt
                .query_map(
                    params![workspace_id.as_bytes(), now_us],
                    briefing_page_from_row,
                )?
                .collect::<Result<Vec<_>, _>>()?
                .into_iter()
                .collect::<Result<Vec<_>, _>>()?;

            let mut slots_stmt = conn.prepare_cached(&format!(
                "SELECT path, title, {kind_expr} AS kind, \
                        updated_at \
                 FROM pages \
                  WHERE workspace_id = ?1 AND is_latest = 1 AND path GLOB '_slots/*'{not_expired}{visible} \
                  ORDER BY path ASC",
                not_expired = not_expired("pages", "?2"),
            ))?;
            let slots: Vec<BriefingPage> = slots_stmt
                .query_map(
                    params![workspace_id.as_bytes(), now_us],
                    briefing_page_from_row,
                )?
                .collect::<Result<Vec<_>, _>>()?
                .into_iter()
                .collect::<Result<Vec<_>, _>>()?;

            let mut recent_stmt = conn.prepare_cached(&format!(
                "SELECT path, title, {kind_expr} AS kind, \
                        updated_at \
                 FROM pages \
                 WHERE workspace_id = ?1 AND is_latest = 1 AND ({recent_slot_sql}){not_expired}{visible} \
                 ORDER BY updated_at DESC \
                 LIMIT ?2",
                not_expired = not_expired("pages", "?3"),
            ))?;
            let recent_rows = match recent_glob.as_deref() {
                Some(glob) => recent_stmt.query_map(
                    params![workspace_id.as_bytes(), recent_limit, now_us, glob],
                    briefing_page_from_row,
                )?,
                None => recent_stmt.query_map(
                    params![workspace_id.as_bytes(), recent_limit, now_us],
                    briefing_page_from_row,
                )?,
            };
            let recent_pages: Vec<BriefingPage> = recent_rows
                .collect::<Result<Vec<_>, _>>()?
                .into_iter()
                .collect::<Result<Vec<_>, _>>()?;

            let mut snapshot = BriefingSnapshot {
                counts,
                activity_7d,
                activity_30d,
                last_observation_at,
                pending_handoff_count,
                // No single recipient project for a current/default- or
                // workspace-scope briefing; the inbox count is project-scoped.
                pending_message_count: 0,
                rules,
                slots,
                recent_pages,
                cross_project_dependents: 0,
                cross_project_dependencies: 0,
                settled: Vec::new(),
                // The pinned standing-context list is a project-scoped signal;
                // an aggregate current/workspace briefing leaves it empty.
                pinned: Vec::new(),
            };
            filter_briefing_slots(&mut snapshot, &slot_visibility);
            Ok(snapshot)
        })
        .await
    }

    /// Compute basic memory-health counters for a workspace.
    ///
    /// Returns `(stale, duplicates, orphans)`:
    /// - `stale`: latest episodic pages not updated within `STALE_DAYS` (30).
    /// - `duplicates`: extra latest pages that share a title.
    /// - `orphans`: latest pages with no inbound or outbound links.
    ///
    /// `viewer` counts only repositories that user may read; `None` counts
    /// the whole workspace.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn memory_health_for_workspace(
        &self,
        workspace_id: WorkspaceId,
        viewer: Option<UserId>,
    ) -> StoreResult<(u64, u64, u64)> {
        self.memory_health_scoped(workspace_id, None, viewer).await
    }

    /// Per-project variant of [`ReaderPool::memory_health_for_workspace`]:
    /// the same stale / duplicate / orphan counters, confined to one project.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn memory_health_for_project(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> StoreResult<(u64, u64, u64)> {
        // A single project is already authorized by whoever resolved it.
        self.memory_health_scoped(workspace_id, Some(project_id), None)
            .await
    }

    async fn memory_health_scoped(
        &self,
        workspace_id: WorkspaceId,
        project_id: Option<ProjectId>,
        viewer: Option<UserId>,
    ) -> StoreResult<(u64, u64, u64)> {
        self.with_conn(move |conn| {
            let now_us = jiff::Timestamp::now().as_microsecond();
            let cutoff_30d = now_us - 30 * 86_400 * 1_000_000;
            let proj = project_id.map(|p| Value::Blob(p.as_bytes().to_vec()));
            let ws = || Value::Blob(workspace_id.as_bytes().to_vec());
            // Optional project filter, anonymous-`?` style. The orphan query
            // aliases pages as `p`, so it needs its own qualified clause. The
            // readable-repository predicate binds nothing, so it can follow
            // either without disturbing the anonymous parameter order.
            let clause = format!(
                "{}{}",
                if proj.is_some() {
                    " AND project_id = ?"
                } else {
                    ""
                },
                readable_repository_predicate("project_id", viewer),
            );
            let clause_p = format!(
                "{}{}",
                if proj.is_some() {
                    " AND p.project_id = ?"
                } else {
                    ""
                },
                readable_repository_predicate("p.project_id", viewer),
            );

            let ttl = not_expired("pages", "?");
            let ttl_p = not_expired("p", "?");
            // Incoming links are only evidence of a reference when their
            // source page is itself a live page. `replace_links_in_tx` deletes
            // rows only for the new version's id, so a superseded version's
            // links survive, and `refresh_incoming_links_for_path` repoints
            // them at the new latest id without filtering on `is_latest` — so
            // a link removed by an edit still answers for the target.
            let ttl_fp = not_expired("fp", "?");

            let stale: i64 = conn
                .query_row(
                    &format!(
                        "SELECT COUNT(*) FROM pages \
                         WHERE workspace_id = ? AND is_latest = 1 \
                           AND tier = 'episodic' AND updated_at < ?{clause}{ttl}"
                    ),
                    params_from_iter(
                        [ws(), Value::Integer(cutoff_30d)]
                            .into_iter()
                            .chain(proj.clone())
                            .chain(std::iter::once(Value::Integer(now_us))),
                    ),
                    |row| row.get(0),
                )
                .optional()?
                .unwrap_or(0);

            let duplicates: i64 = conn
                .query_row(
                    &format!(
                        "SELECT COALESCE(SUM(c - 1), 0) FROM ( \
                            SELECT COUNT(*) c FROM pages \
                            WHERE workspace_id = ? AND is_latest = 1{clause}{ttl} \
                            GROUP BY title HAVING c > 1 \
                         )"
                    ),
                    params_from_iter(
                        std::iter::once(ws())
                            .chain(proj.clone())
                            .chain(std::iter::once(Value::Integer(now_us))),
                    ),
                    |row| row.get(0),
                )
                .optional()?
                .unwrap_or(0);

            let orphans: i64 = conn
                .query_row(
                    &format!(
                        "SELECT COUNT(*) FROM pages p \
                         WHERE p.workspace_id = ? AND p.is_latest = 1{clause_p}{ttl_p} \
                           AND NOT EXISTS (SELECT 1 FROM links l WHERE l.from_page_id = p.id) \
                           AND NOT EXISTS ( \
                               SELECT 1 FROM links l \
                               JOIN pages fp ON fp.id = l.from_page_id \
                                 AND fp.is_latest = 1{ttl_fp} \
                               WHERE l.to_page_id = p.id)"
                    ),
                    params_from_iter(
                        std::iter::once(ws())
                            .chain(proj.clone())
                            .chain(std::iter::once(Value::Integer(now_us)))
                            .chain(std::iter::once(Value::Integer(now_us))),
                    ),
                    |row| row.get(0),
                )
                .optional()?
                .unwrap_or(0);

            Ok((
                u64::try_from(stale).unwrap_or(0),
                u64::try_from(duplicates).unwrap_or(0),
                u64::try_from(orphans).unwrap_or(0),
            ))
        })
        .await
    }

    /// Drill-down lists behind [`ReaderPool::memory_health_for_workspace`]'s
    /// counters: the actual stale / duplicate / orphan pages, each capped at
    /// `limit`. Definitions mirror the counters exactly so the lists explain
    /// the headline numbers — including `viewer`, which lists only pages in
    /// repositories that user may read, before the `LIMIT`.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn health_detail_for_workspace(
        &self,
        workspace_id: WorkspaceId,
        limit: usize,
        viewer: Option<UserId>,
    ) -> StoreResult<HealthDetail> {
        self.health_detail_scoped(workspace_id, None, limit, viewer)
            .await
    }

    /// Per-project variant of [`ReaderPool::health_detail_for_workspace`].
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn health_detail_for_project(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        limit: usize,
    ) -> StoreResult<HealthDetail> {
        // A single project is already authorized by whoever resolved it.
        self.health_detail_scoped(workspace_id, Some(project_id), limit, None)
            .await
    }

    async fn health_detail_scoped(
        &self,
        workspace_id: WorkspaceId,
        project_id: Option<ProjectId>,
        limit: usize,
        viewer: Option<UserId>,
    ) -> StoreResult<HealthDetail> {
        let limit = i64::try_from(limit).unwrap_or(i64::MAX);
        self.with_conn(move |conn| {
            let now_us = jiff::Timestamp::now().as_microsecond();
            let cutoff_30d = now_us - 30 * 86_400 * 1_000_000;
            let proj = project_id.map(|p| Value::Blob(p.as_bytes().to_vec()));
            let ws = || Value::Blob(workspace_id.as_bytes().to_vec());
            // The duplicate list's inner query must see the same repositories
            // as the outer one, or a hidden page sharing a title would still
            // make a visible one show up as a duplicate.
            let clause = format!(
                "{}{}",
                if proj.is_some() {
                    " AND pg.project_id = ?"
                } else {
                    ""
                },
                readable_repository_predicate("pg.project_id", viewer),
            );
            let inner_clause = format!(
                "{}{}",
                if proj.is_some() {
                    " AND project_id = ?"
                } else {
                    ""
                },
                readable_repository_predicate("project_id", viewer),
            );

            // Shared SELECT prefix: identity + path-inferred `kind`.
            let kind_expr = page_kind_expr("pg.path", "pg.frontmatter_json");
            let select = format!(
                "SELECT w.name, p.name, pg.path, pg.title, {kind_expr} \
                   FROM pages pg \
                   JOIN projects p ON p.id = pg.project_id \
                   JOIN workspaces w ON w.id = pg.workspace_id "
            );

            let ttl_pg = not_expired("pg", "?");
            let ttl_fp = not_expired("fp", "?");
            let ttl_inner = not_expired("pages", "?");

            // Params follow placeholder order: ws, cutoff, [proj], now_us, limit.
            let stale_sql = format!(
                "{select} WHERE pg.workspace_id = ? AND pg.is_latest = 1 \
                   AND pg.tier = 'episodic' AND pg.updated_at < ?{clause}{ttl_pg} \
                 ORDER BY pg.updated_at ASC LIMIT ?"
            );
            let mut stale_stmt = conn.prepare(&stale_sql)?;
            let stale = stale_stmt
                .query_map(
                    params_from_iter(
                        [ws(), Value::Integer(cutoff_30d)]
                            .into_iter()
                            .chain(proj.clone())
                            .chain(std::iter::once(Value::Integer(now_us)))
                            .chain(std::iter::once(Value::Integer(limit))),
                    ),
                    health_page_from_row,
                )?
                .collect::<Result<Vec<_>, _>>()?;

            // Params: ws, [proj], now_us, ws(inner), [proj(inner)], now_us(inner), limit.
            let dup_sql = format!(
                "{select} WHERE pg.workspace_id = ? AND pg.is_latest = 1{clause}{ttl_pg} \
                   AND pg.title IN ( \
                       SELECT title FROM pages \
                       WHERE workspace_id = ? AND is_latest = 1{inner_clause}{ttl_inner} \
                       GROUP BY title HAVING COUNT(*) > 1 \
                   ) \
                 ORDER BY pg.title, p.name LIMIT ?"
            );
            let mut dup_stmt = conn.prepare(&dup_sql)?;
            let duplicates = dup_stmt
                .query_map(
                    params_from_iter(
                        std::iter::once(ws())
                            .chain(proj.clone())
                            .chain(std::iter::once(Value::Integer(now_us)))
                            .chain(std::iter::once(ws()))
                            .chain(proj.clone())
                            .chain(std::iter::once(Value::Integer(now_us)))
                            .chain(std::iter::once(Value::Integer(limit))),
                    ),
                    health_page_from_row,
                )?
                .collect::<Result<Vec<_>, _>>()?;

            // Params: ws, [proj], now_us, now_us, limit.
            let orphan_sql = format!(
                "{select} WHERE pg.workspace_id = ? AND pg.is_latest = 1{clause}{ttl_pg} \
                   AND NOT EXISTS (SELECT 1 FROM links l WHERE l.from_page_id = pg.id) \
                   AND NOT EXISTS ( \
                       SELECT 1 FROM links l \
                       JOIN pages fp ON fp.id = l.from_page_id \
                         AND fp.is_latest = 1{ttl_fp} \
                       WHERE l.to_page_id = pg.id) \
                 ORDER BY pg.updated_at DESC LIMIT ?"
            );
            let mut orphan_stmt = conn.prepare(&orphan_sql)?;
            let orphans = orphan_stmt
                .query_map(
                    params_from_iter(
                        std::iter::once(ws())
                            .chain(proj.clone())
                            .chain(std::iter::once(Value::Integer(now_us)))
                            .chain(std::iter::once(Value::Integer(now_us)))
                            .chain(std::iter::once(Value::Integer(limit))),
                    ),
                    health_page_from_row,
                )?
                .collect::<Result<Vec<_>, _>>()?;

            Ok(HealthDetail {
                stale,
                duplicates,
                orphans,
            })
        })
        .await
    }

    /// Look up a page's workspace and project names by page id.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn page_meta_by_id(&self, page_id: PageId) -> StoreResult<Option<PageMeta>> {
        self.with_conn(move |conn| {
            let kind_expr = page_kind_expr("pg.path", "pg.frontmatter_json");
            let created_expr = PAGE_FIRST_CREATED_EXPR;
            let sql = format!(
                "SELECT w.name, p.name, w.id, p.id, pg.path, pg.title, \
                        {kind_expr}, \
                        pg.tier, pg.pinned, {created_expr}, pg.updated_at, \
                        sp.path AS supersedes_path, \
                        au.username, au.name, au.email, pg.expires_at, pg.id \
                 FROM pages pg \
                 JOIN projects p ON p.id = pg.project_id \
                 JOIN workspaces w ON w.id = pg.workspace_id \
                 LEFT JOIN pages sp ON sp.id = pg.supersedes \
                 LEFT JOIN users au ON au.id = pg.author_id \
                 WHERE pg.id = ?1 AND pg.is_latest = 1"
            );
            let row_opt = conn
                .query_row(&sql, params![page_id.as_bytes()], page_meta_from_row)
                .optional()?;
            row_opt.transpose()
        })
        .await
    }

    /// Look up a page's workspace and project names by its path (across all
    /// workspaces and projects). Returns the first `is_latest = 1` match.
    ///
    /// Used by the web search handler to resolve workspace/project for a hit
    /// without a per-hit SQL join.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn page_meta_by_path(&self, path: &str) -> StoreResult<Option<PageMeta>> {
        let path = path.to_owned();
        self.with_conn(move |conn| {
            let kind_expr = page_kind_expr("pg.path", "pg.frontmatter_json");
            let created_expr = PAGE_FIRST_CREATED_EXPR;
            let sql = format!(
                "SELECT w.name, p.name, w.id, p.id, pg.path, pg.title, \
                        {kind_expr}, \
                        pg.tier, pg.pinned, {created_expr}, pg.updated_at, \
                        sp.path AS supersedes_path, \
                        au.username, au.name, au.email, pg.expires_at, pg.id \
                 FROM pages pg \
                 JOIN projects p ON p.id = pg.project_id \
                 JOIN workspaces w ON w.id = pg.workspace_id \
                 LEFT JOIN pages sp ON sp.id = pg.supersedes \
                 LEFT JOIN users au ON au.id = pg.author_id \
                 WHERE pg.path = ?1 AND pg.is_latest = 1 \
                 LIMIT 1"
            );
            let row_opt = conn
                .query_row(&sql, params![path], page_meta_from_row)
                .optional()?;
            row_opt.transpose()
        })
        .await
    }

    /// Resolve the outgoing links and incoming back-links for the latest
    /// version of a page identified by `(workspace_id, project_id, path)`.
    ///
    /// Both ends are constrained to `is_latest = 1`, so superseded versions
    /// never leak into the link panel, and to [`not_expired`] so a TTL'd
    /// neighbour is hidden the same way search / recent / briefing /
    /// [`Self::graph_neighbors_for_project`] already hide it. The seed
    /// lookup is an exact-path read and still finds an expired page.
    /// Returns empty lists when the page is missing or has no links.
    /// `viewer` drops links whose far end is in a repository that user may
    /// not read; `None` keeps them all.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn page_links(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: String,
        viewer: Option<UserId>,
    ) -> StoreResult<PageLinks> {
        let preview = self
            .page_links_rows(workspace_id, project_id, path, viewer, None)
            .await?;
        Ok(PageLinks {
            links: preview.links,
            backlinks: preview.backlinks,
        })
    }

    /// [`Self::page_links`] cut to the first `limit` of each direction in
    /// SQL, with the visible totals counted under the same filters, so a
    /// page with many neighbours does not load them all to show a few.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn page_links_preview(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: String,
        viewer: Option<UserId>,
        limit: usize,
    ) -> StoreResult<PageLinksPreview> {
        self.page_links_rows(workspace_id, project_id, path, viewer, Some(limit))
            .await
    }

    async fn page_links_rows(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: String,
        viewer: Option<UserId>,
        limit: Option<usize>,
    ) -> StoreResult<PageLinksPreview> {
        self.with_conn(move |conn| {
            let id_opt: Option<Vec<u8>> = conn
                .query_row(
                    "SELECT id FROM pages \
                     WHERE workspace_id = ?1 AND project_id = ?2 AND path = ?3 \
                       AND is_latest = 1",
                    params![workspace_id.as_bytes(), project_id.as_bytes(), path],
                    |row| row.get(0),
                )
                .optional()?;
            let Some(id_bytes) = id_opt else {
                return Ok(PageLinksPreview::default());
            };

            // Outgoing: latest unexpired pages this page links to.
            // Incoming: latest unexpired pages that link here. Both reuse
            // the path-inference `kind` fallback so untagged pages still
            // classify. `?2` is the retrieval TTL cutoff; the viewer
            // predicate inlines its id, so the placeholder is free.
            let kind_expr = page_kind_expr("pg.path", "pg.frontmatter_json");
            // A link into a repository the viewer cannot read would show them
            // its name and a page title and path inside it — the same leak as a
            // graph edge — so the far end is filtered like one. The total is
            // counted over the same filtered rows.
            let visible = readable_repository_predicate("pg.project_id", viewer);
            let ttl = not_expired("pg", "?2");
            let now = now_us();
            let select = |far: &str, near: &str| {
                format!(
                    "SELECT DISTINCT pg.path, pg.title, {kind_expr}, \
                                ws.name, pr.name \
                         FROM links l \
                         JOIN pages pg ON pg.id = l.{far} \
                         JOIN projects pr ON pr.id = pg.project_id \
                         JOIN workspaces ws ON ws.id = pg.workspace_id \
                         WHERE l.{near} = ?1 AND pg.is_latest = 1{visible}{ttl}"
                )
            };
            let outgoing = select("to_page_id", "from_page_id");
            let incoming = select("from_page_id", "to_page_id");
            let cut = limit.map_or_else(String::new, |n| format!(" LIMIT {n}"));

            let collect = |base: &str| -> StoreResult<(Vec<RelatedPage>, usize)> {
                let sql = format!("{base} ORDER BY ws.name, pr.name, pg.path{cut}");
                let mut stmt = conn.prepare(&sql)?;
                let rows = stmt.query_map(params![id_bytes, now], |row| {
                    Ok(RelatedPage {
                        path: row.get(0)?,
                        title: row.get(1)?,
                        kind: row.get(2)?,
                        workspace: row.get(3)?,
                        project: row.get(4)?,
                    })
                })?;
                let mut out = Vec::new();
                for r in rows {
                    out.push(r?);
                }
                let total = if limit.is_some_and(|n| out.len() >= n) {
                    let count: i64 = conn.query_row(
                        &format!("SELECT COUNT(*) FROM ({base})"),
                        params![id_bytes, now],
                        |row| row.get(0),
                    )?;
                    usize::try_from(count).unwrap_or(usize::MAX)
                } else {
                    out.len()
                };
                Ok((out, total))
            };

            let (links, links_total) = collect(&outgoing)?;
            let (backlinks, backlinks_total) = collect(&incoming)?;
            Ok(PageLinksPreview {
                links,
                links_total,
                backlinks,
                backlinks_total,
            })
        })
        .await
    }

    /// Bounded breadth-first walk of the link graph outward from one seed
    /// page, following both outgoing links and incoming back-links.
    ///
    /// This is the multi-hop generalisation of [`Self::page_links`]: depth 1
    /// returns exactly the seed's direct neighbours (the union of `links` and
    /// `backlinks`), and each further hop expands the frontier by one edge.
    /// Like `page_links`, both ends are constrained to `is_latest = 1` and
    /// [`not_expired`], so an expired neighbour is neither returned nor
    /// walked through. Neighbours in sibling projects/workspaces resolve
    /// and carry their real coordinate — the walk is cross-project aware.
    /// The seed lookup is an exact-path read and still starts from an
    /// expired page.
    ///
    /// Bounds (all enforced regardless of the caller):
    /// - `depth` is clamped into `1..=`[`RELATED_WALK_MAX_DEPTH`].
    /// - A global visited set makes the walk dedup- and cycle-safe: no page is
    ///   returned twice, cycles terminate, and the seed itself is never
    ///   returned.
    /// - At most [`RELATED_WALK_MAX_NODES`] nodes are returned; the walk stops
    ///   as soon as the cap is reached.
    ///
    /// Returns an empty vec when the seed is missing or has no neighbours.
    ///
    /// `viewer` filters every hop the way [`Self::page_links`] filters its far
    /// end: a page in a project the viewer cannot read is neither returned
    /// nor walked through, so nothing reachable only through it is returned
    /// either. `None` (root, or per-repository authorization off) walks every
    /// latest unexpired page.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn related_walk(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: String,
        depth: u8,
        viewer: Option<UserId>,
    ) -> StoreResult<Vec<RelatedNode>> {
        let depth = depth.clamp(1, RELATED_WALK_MAX_DEPTH);
        self.with_conn(move |conn| {
            let seed: Option<Vec<u8>> = conn
                .query_row(
                    "SELECT id FROM pages \
                     WHERE workspace_id = ?1 AND project_id = ?2 AND path = ?3 \
                       AND is_latest = 1",
                    params![workspace_id.as_bytes(), project_id.as_bytes(), path],
                    |row| row.get(0),
                )
                .optional()?;
            let Some(seed) = seed else {
                return Ok(Vec::new());
            };

            // Per-node expansion reuses the exact `page_links` resolution
            // (latest-only, unexpired, cross-project) but also selects
            // `pg.id` so the walk can continue from each neighbour. One
            // cutoff for every hop of this walk.
            let kind_expr = page_kind_expr("pg.path", "pg.frontmatter_json");
            let visible = readable_repository_predicate("pg.project_id", viewer);
            let ttl = not_expired("pg", "?2");
            let now = now_us();
            let outgoing = format!(
                "SELECT DISTINCT pg.id, pg.path, pg.title, {kind_expr}, ws.name, pr.name \
                     FROM links l \
                     JOIN pages pg ON pg.id = l.to_page_id \
                     JOIN projects pr ON pr.id = pg.project_id \
                     JOIN workspaces ws ON ws.id = pg.workspace_id \
                     WHERE l.from_page_id = ?1 AND pg.is_latest = 1{visible}{ttl} \
                     ORDER BY ws.name, pr.name, pg.path"
            );
            let incoming = format!(
                "SELECT DISTINCT pg.id, pg.path, pg.title, {kind_expr}, ws.name, pr.name \
                     FROM links l \
                     JOIN pages pg ON pg.id = l.from_page_id \
                     JOIN projects pr ON pr.id = pg.project_id \
                     JOIN workspaces ws ON ws.id = pg.workspace_id \
                     WHERE l.to_page_id = ?1 AND pg.is_latest = 1{visible}{ttl} \
                     ORDER BY ws.name, pr.name, pg.path"
            );
            let mut out_stmt = conn.prepare(&outgoing)?;
            let mut in_stmt = conn.prepare(&incoming)?;

            let mut visited: std::collections::HashSet<Vec<u8>> = std::collections::HashSet::new();
            visited.insert(seed.clone());
            let mut results: Vec<RelatedNode> = Vec::new();
            let mut frontier: Vec<Vec<u8>> = vec![seed];

            'walk: for hop in 1..=depth {
                let mut next: Vec<Vec<u8>> = Vec::new();
                for node in &frontier {
                    // Outgoing edges are labelled "link", incoming "backlink";
                    // a node reachable both ways keeps its first-reached label.
                    for (direction, stmt) in [("link", &mut out_stmt), ("backlink", &mut in_stmt)] {
                        let rows = stmt.query_map(params![node, now], |row| {
                            let id: Vec<u8> = row.get(0)?;
                            Ok((
                                id,
                                RelatedPage {
                                    path: row.get(1)?,
                                    title: row.get(2)?,
                                    kind: row.get(3)?,
                                    workspace: row.get(4)?,
                                    project: row.get(5)?,
                                },
                            ))
                        })?;
                        for row in rows {
                            let (id, page) = row?;
                            if !visited.insert(id.clone()) {
                                continue;
                            }
                            results.push(RelatedNode {
                                id: PageId::from_slice(&id)?,
                                page,
                                depth: hop,
                                direction,
                            });
                            next.push(id);
                            if results.len() >= RELATED_WALK_MAX_NODES {
                                break 'walk;
                            }
                        }
                    }
                }
                if next.is_empty() {
                    break;
                }
                frontier = next;
            }

            Ok(results)
        })
        .await
    }

    /// List unresolved cross-project links authored by latest unexpired pages
    /// in this project — declared dependencies on another project's page that
    /// don't resolve to an existing, latest, unexpired page. Each row says
    /// whether the named target project exists, so the lint can tell a
    /// typo'd project name from a missing / renamed target page.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn dangling_cross_project_links(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> StoreResult<Vec<DanglingCrossLink>> {
        self.with_conn(move |conn| {
            let from_ttl = not_expired("fp", "?3");
            let to_ttl = not_expired("tp", "?3");
            let sql = format!(
                "SELECT fp.path, l.to_workspace, l.to_project, l.to_path, \
                        EXISTS ( \
                            SELECT 1 FROM projects pr \
                            JOIN workspaces ws ON ws.id = pr.workspace_id \
                            WHERE pr.name = l.to_project \
                              AND ws.name = COALESCE( \
                                  l.to_workspace, \
                                  (SELECT name FROM workspaces WHERE id = ?1) \
                              ) \
                        ) AS project_exists \
                 FROM links l \
                 JOIN pages fp ON fp.id = l.from_page_id \
                     AND fp.workspace_id = ?1 AND fp.project_id = ?2 AND fp.is_latest = 1{from_ttl} \
                 LEFT JOIN pages tp ON tp.id = l.to_page_id AND tp.is_latest = 1{to_ttl} \
                 WHERE tp.id IS NULL AND l.to_project IS NOT NULL \
                 ORDER BY fp.path, l.to_project, l.to_path"
            );
            let mut stmt = conn.prepare(&sql)?;
            let now = now_us();
            let rows = stmt.query_map(
                params![workspace_id.as_bytes(), project_id.as_bytes(), now],
                |row| {
                    let exists: i64 = row.get(4)?;
                    Ok(DanglingCrossLink {
                        from_path: row.get(0)?,
                        workspace: row.get(1)?,
                        project: row.get(2)?,
                        path: row.get(3)?,
                        project_exists: exists != 0,
                    })
                },
            )?;
            let mut out = Vec::new();
            for r in rows {
                out.push(r?);
            }
            Ok(out)
        })
        .await
    }

    /// Cross-session pass cadence probe: completed sessions newer than
    /// the pass's last run for this scope (docs/experience.md).
    ///
    /// # Errors
    /// Propagates SQL errors from the read pool.
    pub async fn experience_pass_due(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> StoreResult<(u64, i64)> {
        self.with_conn(move |conn| {
            crate::auto_improve::experience_pass_due(conn, workspace_id, project_id)
        })
        .await
    }

    /// Typed `contradicts` edges declared by latest unexpired pages of one
    /// project (docs/okf.md relations vocabulary). Each row feeds one
    /// rule-based lint finding; `resolved` is true when the target resolves
    /// to a latest unexpired page.
    ///
    /// # Errors
    /// Propagates SQL errors from the read pool.
    pub async fn contradiction_edges(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> StoreResult<Vec<ContradictionEdge>> {
        self.with_conn(move |conn| {
            let from_ttl = not_expired("fp", "?3");
            let to_ttl = not_expired("tp", "?3");
            let sql = format!(
                "SELECT fp.path, l.to_path, \
                        tp.id IS NOT NULL AS resolved \
                 FROM links l \
                 JOIN pages fp ON fp.id = l.from_page_id \
                     AND fp.workspace_id = ?1 AND fp.project_id = ?2 AND fp.is_latest = 1{from_ttl} \
                 LEFT JOIN pages tp ON tp.id = l.to_page_id AND tp.is_latest = 1{to_ttl} \
                 WHERE l.link_type = 'contradicts' \
                 ORDER BY fp.path, l.to_path"
            );
            let mut stmt = conn.prepare(&sql)?;
            let now = now_us();
            let rows = stmt.query_map(
                params![workspace_id.as_bytes(), project_id.as_bytes(), now],
                |row| {
                    let resolved: i64 = row.get(2)?;
                    Ok(ContradictionEdge {
                        from_path: row.get(0)?,
                        to_path: row.get(1)?,
                        resolved: resolved != 0,
                    })
                },
            )?;
            let mut out = Vec::new();
            for r in rows {
                out.push(r?);
            }
            Ok(out)
        })
        .await
    }

    /// Resolved cross-project edges (links whose endpoints are in different
    /// projects). When `scope` is `Some((ws, proj))`, only edges that touch
    /// that project (as source or target) are returned; `None` returns the
    /// whole cross-project graph. Powers `/api/v1/graph`.
    ///
    /// `viewer` keeps only edges whose *both* endpoints the user may read
    /// (#708). One readable end is not enough: an edge carries the other end's
    /// workspace, project and path, so a link from a page bob can read into a
    /// repository he cannot would hand him the hidden repository's name and a
    /// page path inside it. `None` returns the graph unfiltered.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn cross_project_edges(
        &self,
        scope: Option<(WorkspaceId, ProjectId)>,
        viewer: Option<UserId>,
    ) -> StoreResult<Vec<CrossProjectEdge>> {
        self.with_conn(move |conn| {
            let visible = format!(
                "{}{}",
                readable_repository_predicate("fp.project_id", viewer),
                readable_repository_predicate("tp.project_id", viewer),
            );
            // An edge to or from an expired page is hidden like the page
            // itself (#1141); `now` is bound at the placeholder each query
            // passes in.
            let base = |now_param: &str| {
                format!(
                    "SELECT fw.name, fpr.name, fp.path, tw.name, tpr.name, tp.path \
                     FROM links l \
                     JOIN pages fp ON fp.id = l.from_page_id AND fp.is_latest = 1{from_ttl} \
                     JOIN pages tp ON tp.id = l.to_page_id AND tp.is_latest = 1{to_ttl} \
                     JOIN projects fpr ON fpr.id = fp.project_id \
                     JOIN workspaces fw ON fw.id = fp.workspace_id \
                     JOIN projects tpr ON tpr.id = tp.project_id \
                     JOIN workspaces tw ON tw.id = tp.workspace_id \
                     WHERE fp.project_id != tp.project_id{visible}",
                    from_ttl = not_expired("fp", now_param),
                    to_ttl = not_expired("tp", now_param),
                )
            };
            let now = now_us();
            let map_row = |row: &rusqlite::Row<'_>| {
                Ok(CrossProjectEdge {
                    from_workspace: row.get(0)?,
                    from_project: row.get(1)?,
                    from_path: row.get(2)?,
                    to_workspace: row.get(3)?,
                    to_project: row.get(4)?,
                    to_path: row.get(5)?,
                })
            };
            let mut out = Vec::new();
            if let Some((_ws, proj)) = scope {
                let sql = format!(
                    "{} AND (fp.project_id = ?1 OR tp.project_id = ?1) ORDER BY fw.name, fpr.name, fp.path",
                    base("?2")
                );
                let mut stmt = conn.prepare(&sql)?;
                let rows = stmt.query_map(params![proj.as_bytes(), now], map_row)?;
                for r in rows {
                    out.push(r?);
                }
            } else {
                let sql = format!("{} ORDER BY fw.name, fpr.name, fp.path", base("?1"));
                let mut stmt = conn.prepare(&sql)?;
                let rows = stmt.query_map(params![now], map_row)?;
                for r in rows {
                    out.push(r?);
                }
            }
            Ok(out)
        })
        .await
    }

    /// Latest unexpired pages in one project and the resolved wikilinks
    /// among them.
    ///
    /// Cross-project and unresolved links are omitted: this is the in-project
    /// map the project graph page draws. Expired pages are hidden the same way
    /// other retrieval surfaces hide them. When the project has more live
    /// pages than [`PROJECT_LINK_GRAPH_MAX_NODES`], pages with the fewest
    /// same-project neighbours drop first, then the oldest of those.
    ///
    /// Personal slots are included, matching [`Self::list_pages`]: the caller
    /// has already authorized the project.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn project_link_graph(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> StoreResult<LinkGraph> {
        self.with_conn(move |conn| {
            let now = now_us();
            let ttl = not_expired("pg", "?3");
            let from_ttl = not_expired("fp", "?3");
            let to_ttl = not_expired("tp", "?3");
            let mut page_stmt = conn.prepare(&format!(
                "WITH live(id, path, title, updated_at) AS ( \
                     SELECT pg.id, pg.path, pg.title, pg.updated_at \
                     FROM pages pg \
                     WHERE pg.workspace_id = ?1 AND pg.project_id = ?2 \
                       AND pg.is_latest = 1{ttl} \
                 ), \
                 live_edges(from_id, to_id) AS ( \
                     SELECT DISTINCT fp.id, tp.id \
                     FROM links l \
                     JOIN pages fp ON fp.id = l.from_page_id \
                       AND fp.is_latest = 1{from_ttl} \
                     JOIN pages tp ON tp.id = l.to_page_id \
                       AND tp.is_latest = 1{to_ttl} \
                     WHERE fp.workspace_id = ?1 AND fp.project_id = ?2 \
                       AND tp.workspace_id = ?1 AND tp.project_id = ?2 \
                 ), \
                 endpoints(page_id) AS ( \
                     SELECT from_id FROM live_edges \
                     UNION ALL \
                     SELECT to_id FROM live_edges WHERE to_id != from_id \
                 ), \
                 ranked(id, path, title, updated_at, degree) AS ( \
                     SELECT live.id, live.path, live.title, live.updated_at, \
                            COUNT(endpoints.page_id) \
                     FROM live \
                     LEFT JOIN endpoints ON endpoints.page_id = live.id \
                     GROUP BY live.id, live.path, live.title, live.updated_at \
                 ) \
                 SELECT id, path, title, degree, COUNT(*) OVER() \
                 FROM ranked \
                 ORDER BY degree DESC, updated_at DESC, path \
                 LIMIT ?4"
            ))?;
            let page_rows = page_stmt.query_map(
                params![
                    workspace_id.as_bytes(),
                    project_id.as_bytes(),
                    now,
                    PROJECT_LINK_GRAPH_MAX_NODES as i64
                ],
                |row| {
                    let id: Vec<u8> = row.get(0)?;
                    Ok((
                        id,
                        row.get(1)?,
                        row.get(2)?,
                        row.get::<_, i64>(3)?,
                        row.get::<_, i64>(4)?,
                    ))
                },
            )?;
            let mut pages: Vec<(PageId, LinkGraphNode)> = Vec::new();
            let mut total_pages = 0_i64;
            for row in page_rows {
                let (id, path, title, degree, total) = row?;
                total_pages = total;
                pages.push((
                    PageId::from_slice(&id)?,
                    LinkGraphNode {
                        path,
                        title,
                        degree: degree as u64,
                    },
                ));
            }

            let mut edges = Vec::new();
            if !pages.is_empty() {
                let mut placeholders = String::new();
                for i in 0..pages.len() {
                    if i > 0 {
                        placeholders.push_str(", ");
                    }
                    let _ = write!(placeholders, "?{}", i + 4);
                }
                let edge_sql = format!(
                    "SELECT DISTINCT fp.path, tp.path \
                     FROM links l \
                     JOIN pages fp ON fp.id = l.from_page_id \
                       AND fp.is_latest = 1{from_ttl} \
                     JOIN pages tp ON tp.id = l.to_page_id \
                       AND tp.is_latest = 1{to_ttl} \
                     WHERE fp.workspace_id = ?1 AND fp.project_id = ?2 \
                       AND tp.workspace_id = ?1 AND tp.project_id = ?2 \
                       AND fp.id IN ({placeholders}) \
                       AND tp.id IN ({placeholders}) \
                     ORDER BY fp.path, tp.path"
                );
                let mut bound = Vec::with_capacity(3 + pages.len());
                bound.push(Value::Blob(workspace_id.as_bytes().to_vec()));
                bound.push(Value::Blob(project_id.as_bytes().to_vec()));
                bound.push(Value::Integer(now));
                bound.extend(
                    pages
                        .iter()
                        .map(|(id, _)| Value::Blob(id.as_bytes().to_vec())),
                );
                let mut edge_stmt = conn.prepare(&edge_sql)?;
                let edge_rows = edge_stmt.query_map(params_from_iter(bound.iter()), |row| {
                    Ok(LinkGraphEdge {
                        from_path: row.get(0)?,
                        to_path: row.get(1)?,
                    })
                })?;
                for row in edge_rows {
                    edges.push(row?);
                }
            }

            let truncated = total_pages > PROJECT_LINK_GRAPH_MAX_NODES as i64;
            let nodes = pages.into_iter().map(|(_, node)| node).collect();
            Ok(LinkGraph {
                nodes,
                edges,
                truncated,
            })
        })
        .await
    }

    /// Return one row per (workspace, project) with page-count and
    /// last-updated aggregates. Used by the web UI project-list view.
    ///
    /// Only unexpired `is_latest = 1` pages are counted. `viewer` lists only the
    /// repositories that user may read — see [`readable_repository_filter`];
    /// `None` lists every one.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn list_projects_with_stats(
        &self,
        viewer: Option<UserId>,
    ) -> StoreResult<Vec<ProjectSummary>> {
        self.list_projects_with_stats_filtered(None, viewer).await
    }

    /// Return one row per project within one workspace.
    ///
    /// Only unexpired `is_latest = 1` pages are counted. `viewer` as for
    /// [`Self::list_projects_with_stats`].
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn list_projects_with_stats_for_workspace(
        &self,
        workspace: String,
        viewer: Option<UserId>,
    ) -> StoreResult<Vec<ProjectSummary>> {
        self.list_projects_with_stats_filtered(Some(workspace), viewer)
            .await
    }

    async fn list_projects_with_stats_filtered(
        &self,
        workspace: Option<String>,
        viewer: Option<UserId>,
    ) -> StoreResult<Vec<ProjectSummary>> {
        self.with_conn(move |conn| {
            // A repository's name is itself the leak here — client work from
            // three organisations listed by name — so the filter is on the
            // project row, not only on the pages counted beside it.
            let visible = readable_repository_predicate("p.id", viewer);
            let ttl = not_expired("pg", "?2");
            let mut stmt = conn.prepare(&format!(
                "SELECT w.id AS workspace_id, \
                        w.name AS workspace_name, \
                        p.id AS project_id, \
                        p.name AS project_name, \
                        COUNT(pg.id) AS page_count, \
                        MAX(pg.updated_at) AS last_updated_us, \
                        (SELECT COUNT(*) FROM sessions s WHERE s.project_id = p.id), \
                        (SELECT COUNT(*) FROM observations o WHERE o.project_id = p.id), \
                        (SELECT COUNT(*) FROM sessions s WHERE s.project_id = p.id AND s.ended_at IS NULL), \
                        COALESCE((SELECT MAX(o.created_at) FROM observations o WHERE o.project_id = p.id), \
                            (SELECT MAX(s.started_at) FROM sessions s WHERE s.project_id = p.id), \
                            MAX(pg.updated_at)) AS last_activity \
                 FROM workspaces w \
                 JOIN projects p ON p.workspace_id = w.id \
                 LEFT JOIN pages pg ON pg.project_id = p.id AND pg.is_latest = 1{ttl} \
                 WHERE (?1 IS NULL OR w.name = ?1){visible} \
                 GROUP BY w.id, p.id \
                 ORDER BY last_activity DESC NULLS LAST"
            ))?;
            let now = now_us();
            let rows = stmt.query_map(params![workspace, now], |row| {
                let workspace_id: Vec<u8> = row.get(0)?;
                let workspace_name: String = row.get(1)?;
                let project_id: Vec<u8> = row.get(2)?;
                let project_name: String = row.get(3)?;
                let page_count: i64 = row.get(4)?;
                let last_updated_us: Option<i64> = row.get(5)?;
                let session_count: i64 = row.get(6)?;
                let observation_count: i64 = row.get(7)?;
                let open_session_count: i64 = row.get(8)?;
                let last_activity_us: Option<i64> = row.get(9)?;
                Ok((
                    workspace_id,
                    workspace_name,
                    project_id,
                    project_name,
                    page_count,
                    last_updated_us,
                    session_count, observation_count, open_session_count, last_activity_us,
                ))
            })?;
            let mut out = Vec::new();
            for r in rows {
                let (
                    workspace_id,
                    workspace_name,
                    project_id,
                    project_name,
                    page_count,
                    last_updated_us,
                    session_count, observation_count, open_session_count, last_activity_us,
                ) = r?;
                let workspace_id = WorkspaceId::from_slice(&workspace_id)?;
                let project_id = ProjectId::from_slice(&project_id)?;
                let last_updated = last_updated_us
                    .and_then(|us| jiff::Timestamp::from_microsecond(us).ok())
                    .map(|ts| ts.to_string());
                let last_activity = last_activity_us
                    .and_then(|us| jiff::Timestamp::from_microsecond(us).ok())
                    .map(|ts| ts.to_string());
                out.push(ProjectSummary {
                    workspace_id: workspace_id.to_string(),
                    workspace_name,
                    project_id: project_id.to_string(),
                    project_name,
                    page_count: u64::try_from(page_count).unwrap_or(0),
                    session_count: u64::try_from(session_count).unwrap_or(0),
                    observation_count: u64::try_from(observation_count).unwrap_or(0),
                    open_session_count: u64::try_from(open_session_count).unwrap_or(0),
                    last_updated,
                    last_activity,
                });
            }
            Ok(out)
        })
        .await
    }

    /// Return one `(workspace, project)` scope by id, with the names and
    /// `repo_path` its `_meta.md` manifest is written from. `None` when the
    /// pair has no row.
    ///
    /// The single-scope counterpart of [`list_all_scopes`]: the wiki
    /// materializes a manifest for one scope the first time it writes into
    /// it, on a path where enumerating every scope in the store would be an
    /// N+1 over the whole tree.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn scope_row_by_ids(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> StoreResult<Option<ScopeRow>> {
        type RawScope = (
            String,
            String,
            Option<String>,
            Option<String>,
            Option<String>,
            Option<String>,
            Option<String>,
        );
        let raw: Option<RawScope> = self
            .with_conn(move |conn| {
                let row = conn
                    .query_row(
                        "SELECT w.name, p.name, p.repo_path, NULLIF(p.identity, ''), \
                         NULLIF(p.identity_source, ''), NULLIF(p.canonical_name, ''), \
                         NULLIF(p.legacy_name, '') \
                         FROM projects p JOIN workspaces w ON w.id = p.workspace_id \
                         WHERE p.id = ?1 AND p.workspace_id = ?2",
                        params![project_id.as_bytes(), workspace_id.as_bytes()],
                        |row| {
                            Ok((
                                row.get(0)?,
                                row.get(1)?,
                                row.get(2)?,
                                row.get(3)?,
                                row.get(4)?,
                                row.get(5)?,
                                row.get(6)?,
                            ))
                        },
                    )
                    .optional()?;
                Ok(row)
            })
            .await?;
        Ok(raw.map(
            |(
                workspace_name,
                project_name,
                repo_path,
                identity,
                identity_source,
                canonical_name,
                legacy_name,
            )| ScopeRow {
                workspace_id,
                workspace_name,
                project_id,
                project_name,
                repo_path,
                identity,
                identity_source,
                canonical_name,
                legacy_name,
            },
        ))
    }

    /// Return every `(workspace, project)` scope with its ids, names and
    /// `repo_path` — the data needed to write each scope's self-describing
    /// `_meta.md` manifest. Unlike [`list_projects_with_stats`], this carries
    /// the surrogate ids (not just names), so a rebuild can key the wiki tree.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn list_all_scopes(&self) -> StoreResult<Vec<ScopeRow>> {
        type RawScope = (
            Vec<u8>,
            String,
            Vec<u8>,
            String,
            Option<String>,
            Option<String>,
            Option<String>,
            Option<String>,
            Option<String>,
        );
        let raw: Vec<RawScope> = self
            .with_conn(|conn| {
                let mut stmt = conn.prepare(
                    "SELECT w.id, w.name, p.id, p.name, p.repo_path, \
                     NULLIF(p.identity, ''), NULLIF(p.identity_source, ''), \
                     NULLIF(p.canonical_name, ''), NULLIF(p.legacy_name, '') \
                     FROM projects p JOIN workspaces w ON w.id = p.workspace_id",
                )?;
                let rows = stmt.query_map([], |row| {
                    Ok((
                        row.get(0)?,
                        row.get(1)?,
                        row.get(2)?,
                        row.get(3)?,
                        row.get(4)?,
                        row.get(5)?,
                        row.get(6)?,
                        row.get(7)?,
                        row.get(8)?,
                    ))
                })?;
                let out: rusqlite::Result<Vec<_>> = rows.collect();
                Ok(out?)
            })
            .await?;
        raw.into_iter()
            .map(
                |(wi, wn, pi, pn, rp, identity, identity_source, canonical_name, legacy_name)| {
                    Ok(ScopeRow {
                        workspace_id: WorkspaceId::from_slice(&wi)?,
                        workspace_name: wn,
                        project_id: ProjectId::from_slice(&pi)?,
                        project_name: pn,
                        repo_path: rp,
                        identity,
                        identity_source,
                        canonical_name,
                        legacy_name,
                    })
                },
            )
            .collect()
    }

    /// Return every workspace with its id and name so manifest backfill can
    /// describe even empty workspaces that have no project rows yet.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn list_all_workspace_scopes(&self) -> StoreResult<Vec<WorkspaceScopeRow>> {
        let raw: Vec<(Vec<u8>, String)> = self
            .with_conn(|conn| {
                let mut stmt = conn.prepare("SELECT id, name FROM workspaces")?;
                let rows = stmt.query_map([], |row| Ok((row.get(0)?, row.get(1)?)))?;
                let out: rusqlite::Result<Vec<_>> = rows.collect();
                Ok(out?)
            })
            .await?;
        raw.into_iter()
            .map(|(wi, wn)| {
                Ok(WorkspaceScopeRow {
                    workspace_id: WorkspaceId::from_slice(&wi)?,
                    workspace_name: wn,
                })
            })
            .collect()
    }

    /// Return counts that must be zero before `ai-memory reindex` runs.
    ///
    /// `reindex` is a rebuild-from-files operation, not an in-place repair of a
    /// dirty DB. If rows already exist, stale derived rows or DB-only episodic
    /// state could survive and contradict the "rebuilt from wiki" contract.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn reindex_target_status(&self) -> StoreResult<ReindexTargetStatus> {
        self.with_conn(|conn| {
            Ok(conn.query_row(
                "SELECT \
                    (SELECT COUNT(*) FROM workspaces), \
                    (SELECT COUNT(*) FROM projects), \
                    (SELECT COUNT(*) FROM pages), \
                    (SELECT COUNT(*) FROM links), \
                    (SELECT COUNT(*) FROM page_embeddings), \
                    (SELECT COUNT(*) FROM sessions), \
                    (SELECT COUNT(*) FROM observations), \
                    (SELECT COUNT(*) FROM handoffs), \
                    (SELECT COUNT(*) FROM users), \
                    (SELECT COUNT(*) FROM audit_log)",
                [],
                |row| {
                    Ok(ReindexTargetStatus {
                        workspaces: row.get(0)?,
                        projects: row.get(1)?,
                        pages: row.get(2)?,
                        links: row.get(3)?,
                        page_embeddings: row.get(4)?,
                        sessions: row.get(5)?,
                        observations: row.get(6)?,
                        handoffs: row.get(7)?,
                        users: row.get(8)?,
                        audit_log: row.get(9)?,
                    })
                },
            )?)
        })
        .await
    }

    /// Return one row per workspace with project/page-count and
    /// last-updated aggregates. Used by custom frontends that need a
    /// workspace chooser before narrowing into projects.
    ///
    /// Only unexpired `is_latest = 1` pages are counted.
    ///
    /// With a `viewer`, a workspace is listed only when it holds at least one
    /// repository that user may read, and its counts cover only those. A
    /// workspace name is often an organisation's name, so listing an empty
    /// shell of somebody else's workspace would leak exactly what the project
    /// filter hides. `None` lists every workspace, empty ones included, as
    /// before.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn list_workspaces_with_stats(
        &self,
        viewer: Option<UserId>,
    ) -> StoreResult<Vec<WorkspaceSummary>> {
        self.with_conn(move |conn| {
            // In the join, not the WHERE: unreadable projects drop out of the
            // counts while the LEFT JOIN still yields the workspace row, and
            // the HAVING then removes workspaces left with nothing readable.
            let visible = readable_repository_predicate("p.id", viewer);
            let only_readable = if viewer.is_some() {
                " HAVING COUNT(DISTINCT p.id) > 0"
            } else {
                ""
            };
            let ttl = not_expired("pg", "?1");
            let mut stmt = conn.prepare(&format!(
                "SELECT w.name AS workspace_name, \
                        COUNT(DISTINCT p.id) AS project_count, \
                        COUNT(pg.id) AS page_count, \
                        MAX(pg.updated_at) AS last_updated_us \
                 FROM workspaces w \
                 LEFT JOIN projects p ON p.workspace_id = w.id{visible} \
                 LEFT JOIN pages pg ON pg.project_id = p.id AND pg.is_latest = 1{ttl} \
                 GROUP BY w.id{only_readable} \
                 ORDER BY w.name ASC"
            ))?;
            let now = now_us();
            let rows = stmt.query_map(params![now], |row| {
                let workspace_name: String = row.get(0)?;
                let project_count: i64 = row.get(1)?;
                let page_count: i64 = row.get(2)?;
                let last_updated_us: Option<i64> = row.get(3)?;
                Ok((workspace_name, project_count, page_count, last_updated_us))
            })?;
            let mut out = Vec::new();
            for r in rows {
                let (workspace_name, project_count, page_count, last_updated_us) = r?;
                let last_updated = last_updated_us
                    .and_then(|us| jiff::Timestamp::from_microsecond(us).ok())
                    .map(|ts| ts.to_string());
                out.push(WorkspaceSummary {
                    workspace_name,
                    project_count: u64::try_from(project_count).unwrap_or(0),
                    page_count: u64::try_from(page_count).unwrap_or(0),
                    last_updated,
                });
            }
            Ok(out)
        })
        .await
    }

    /// All `is_latest = 1` pages under a given (workspace, project),
    /// ordered by path ascending, TTL-expired pages included: a project
    /// move copies every current page. Reader-facing listings and curator
    /// reports use [`Self::list_unexpired_pages`].
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn list_pages(
        &self,
        workspace: &str,
        project: &str,
    ) -> StoreResult<Vec<PageSummary>> {
        self.list_latest_pages(workspace, project, false).await
    }

    /// [`Self::list_pages`] without the pages whose `expires_at` TTL has
    /// passed. The web tree, the namespace listing and the `/api/v1` page
    /// lists read this, so a listing hides an expired page the way search
    /// and recent do; an exact-path read still returns it.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn list_unexpired_pages(
        &self,
        workspace: &str,
        project: &str,
    ) -> StoreResult<Vec<PageSummary>> {
        self.list_latest_pages(workspace, project, true).await
    }

    /// The query behind both listings; `hide_expired` adds the TTL guard.
    async fn list_latest_pages(
        &self,
        workspace: &str,
        project: &str,
        hide_expired: bool,
    ) -> StoreResult<Vec<PageSummary>> {
        let workspace = workspace.to_owned();
        let project = project.to_owned();
        self.with_conn(move |conn| {
            let kind_expr = page_kind_expr("pg.path", "pg.frontmatter_json");
            let ttl = if hide_expired {
                not_expired("pg", "?3")
            } else {
                String::new()
            };
            let mut stmt = conn.prepare(&format!(
                "SELECT pg.path, pg.title, {kind_expr} AS kind, \
                        pg.tier, pg.updated_at \
                 FROM pages pg \
                 JOIN projects p ON p.id = pg.project_id \
                 JOIN workspaces w ON w.id = pg.workspace_id \
                 WHERE w.name = ?1 AND p.name = ?2 AND pg.is_latest = 1{ttl} \
                 ORDER BY pg.path ASC"
            ))?;
            let now = now_us();
            let mut bound: Vec<&dyn rusqlite::ToSql> = Vec::with_capacity(3);
            bound.push(&workspace);
            bound.push(&project);
            if hide_expired {
                bound.push(&now);
            }
            let rows = stmt.query_map(params_from_iter(bound.iter()), |row| {
                let path: String = row.get(0)?;
                let title: String = row.get(1)?;
                let kind: String = row.get(2)?;
                let tier: String = row.get(3)?;
                let updated_us: i64 = row.get(4)?;
                Ok((path, title, kind, tier, updated_us))
            })?;
            let mut out = Vec::new();
            for r in rows {
                let (path, title, kind, tier, updated_us) = r?;
                let updated_at = jiff::Timestamp::from_microsecond(updated_us)
                    .map(|ts| ts.to_string())
                    .unwrap_or_default();
                out.push(PageSummary {
                    path,
                    title,
                    kind,
                    tier,
                    updated_at,
                });
            }
            Ok(out)
        })
        .await
    }

    /// Bounded incremental latest-page summaries, ordered by timestamp and path.
    /// Expired pages are omitted; this is an update listing, not a deletion feed.
    /// `since_us` is exclusive; `after` resumes strictly after a returned pair.
    ///
    /// # Errors
    /// Propagates SQL and pool errors.
    pub async fn incremental_pages(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        since_us: i64,
        after: Option<(i64, String)>,
        limit: usize,
    ) -> StoreResult<Vec<PageSummary>> {
        self.with_conn(move |conn| {
            let kind_expr = page_kind_expr("pg.path", "pg.frontmatter_json");
            let (after_us, after_path) = after.unwrap_or((since_us, String::new()));
            let mut stmt = conn.prepare_cached(&format!(
                "SELECT pg.path, pg.title, {kind_expr}, pg.tier, pg.updated_at
                 FROM pages pg WHERE pg.workspace_id = ?1 AND pg.project_id = ?2
                   AND pg.is_latest = 1 AND pg.updated_at > ?3
                   AND (pg.updated_at > ?4 OR (pg.updated_at = ?4 AND pg.path > ?5))
                   AND (pg.expires_at IS NULL OR pg.expires_at > ?6)
                 ORDER BY pg.updated_at ASC, pg.path ASC LIMIT ?7"
            ))?;
            let rows = stmt.query_map(
                params![
                    workspace_id.as_bytes(),
                    project_id.as_bytes(),
                    since_us,
                    after_us,
                    after_path,
                    jiff::Timestamp::now().as_microsecond(),
                    limit.clamp(1, 100) as i64 + 1
                ],
                |row| {
                    let updated_us: i64 = row.get(4)?;
                    Ok(PageSummary {
                        path: row.get(0)?,
                        title: row.get(1)?,
                        kind: row.get(2)?,
                        tier: row.get(3)?,
                        updated_at: jiff::Timestamp::from_microsecond(updated_us)
                            .map(|ts| ts.to_string())
                            .unwrap_or_default(),
                    })
                },
            )?;
            rows.collect::<Result<Vec<_>, _>>().map_err(Into::into)
        })
        .await
    }

    /// Full page metadata for the page-view template (body comes from
    /// `Wiki::read_page`). Returns `None` when no `is_latest = 1` row
    /// matches the given path.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn page_meta(
        &self,
        workspace: &str,
        project: &str,
        page_path: &str,
    ) -> StoreResult<Option<PageMeta>> {
        let workspace = workspace.to_owned();
        let project = project.to_owned();
        let page_path = page_path.to_owned();
        self.with_conn(move |conn| {
            let kind_expr = page_kind_expr("pg.path", "pg.frontmatter_json");
            let created_expr = PAGE_FIRST_CREATED_EXPR;
            let sql = format!(
                "SELECT w.name, p.name, w.id, p.id, pg.path, pg.title, \
                        {kind_expr}, \
                        pg.tier, pg.pinned, {created_expr}, pg.updated_at, \
                        sp.path AS supersedes_path, \
                        au.username, au.name, au.email, pg.expires_at, pg.id \
                 FROM pages pg \
                 JOIN projects p ON p.id = pg.project_id \
                 JOIN workspaces w ON w.id = pg.workspace_id \
                 LEFT JOIN pages sp ON sp.id = pg.supersedes \
                 LEFT JOIN users au ON au.id = pg.author_id \
                 WHERE w.name = ?1 AND p.name = ?2 AND pg.path = ?3 AND pg.is_latest = 1"
            );
            let row_opt = conn
                .query_row(
                    &sql,
                    params![workspace, project, page_path],
                    page_meta_from_row,
                )
                .optional()?;
            row_opt.transpose()
        })
        .await
    }

    /// Fetch the latest version's stored body/title/frontmatter for a page by
    /// `(workspace_id, project_id, path)`. Used as a DB-backed fallback for
    /// `memory_read_page` when the on-disk markdown read fails (index/disk
    /// skew — see `gotchas/read-page-by-query-misses`). Returns `None` when no
    /// `is_latest` row exists.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn page_body_by_ids(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: &str,
    ) -> StoreResult<Option<StoredPageBody>> {
        let path = path.to_owned();
        self.with_conn(move |conn| {
            let row = conn
                .query_row(
                    "SELECT title, body, frontmatter_json, tier, pinned FROM pages \
                     WHERE workspace_id = ?1 AND project_id = ?2 AND path = ?3 \
                       AND is_latest = 1",
                    params![workspace_id.as_bytes(), project_id.as_bytes(), path],
                    |row| {
                        Ok(StoredPageBody {
                            title: row.get(0)?,
                            body: row.get(1)?,
                            frontmatter_json: row.get(2)?,
                            tier: row.get(3)?,
                            pinned: row.get::<_, i64>(4)? != 0,
                        })
                    },
                )
                .optional()?;
            Ok(row)
        })
        .await
    }

    /// List the stored versions of one fully scoped page path, newest first.
    ///
    /// Every row at the path is listed, superseded ones included, so a
    /// version a concurrent write replaced stays visible (invariant #16).
    /// The listing reads by `(workspace_id, project_id, path)` and nothing
    /// else, so another project's rows at the same path never appear.
    /// `limit` is clamped to `1..=`[`PAGE_VERSIONS_MAX_LIMIT`]; `total` counts
    /// every visible version at the path. Bodies are not read, only their
    /// length. Expired versions are hidden (see `history_visible`).
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn page_versions(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: String,
        limit: usize,
        offset: usize,
    ) -> StoreResult<PageVersions> {
        self.with_conn(move |conn| {
            let now = now_us();
            let total: i64 = conn.query_row(
                &format!(
                    "SELECT COUNT(*) FROM pages pg \
                     WHERE pg.workspace_id = ?1 AND pg.project_id = ?2 AND pg.path = ?3{visible}",
                    visible = history_visible("pg", "?4"),
                ),
                params![workspace_id.as_bytes(), project_id.as_bytes(), path, now],
                |row| row.get(0),
            )?;
            let mut stmt = conn.prepare_cached(&format!(
                "SELECT pg.id, \
                        (SELECT sp.id FROM pages sp WHERE sp.id = pg.supersedes{prev_visible}), \
                        pg.is_latest, pg.title, pg.tier, \
                        pg.created_at, length(pg.body), au.username, au.name, au.email \
                 FROM pages pg \
                 LEFT JOIN users au ON au.id = pg.author_id \
                 WHERE pg.workspace_id = ?1 AND pg.project_id = ?2 AND pg.path = ?3{visible} \
                 ORDER BY pg.created_at DESC, pg.rowid DESC \
                 LIMIT ?5 OFFSET ?6",
                visible = history_visible("pg", "?4"),
                prev_visible = history_visible("sp", "?4"),
            ))?;
            let rows = stmt.query_map(
                params![
                    workspace_id.as_bytes(),
                    project_id.as_bytes(),
                    path,
                    now,
                    limit.clamp(1, PAGE_VERSIONS_MAX_LIMIT) as i64,
                    i64::try_from(offset).unwrap_or(i64::MAX),
                ],
                |row| {
                    Ok((
                        row.get::<_, Vec<u8>>(0)?,
                        row.get::<_, Option<Vec<u8>>>(1)?,
                        row.get::<_, i64>(2)?,
                        row.get::<_, String>(3)?,
                        row.get::<_, String>(4)?,
                        row.get::<_, i64>(5)?,
                        row.get::<_, i64>(6)?,
                        row.get::<_, Option<String>>(7)?,
                        row.get::<_, Option<String>>(8)?,
                        row.get::<_, Option<String>>(9)?,
                    ))
                },
            )?;
            let mut versions = Vec::new();
            for row in rows {
                let (id, supersedes, is_latest, title, tier, created_us, chars, user, name, email) =
                    row?;
                versions.push(PageVersion {
                    id: PageId::from_slice(&id)?,
                    supersedes: supersedes.as_deref().map(PageId::from_slice).transpose()?,
                    is_latest: is_latest != 0,
                    title,
                    tier,
                    created_at: jiff::Timestamp::from_microsecond(created_us)
                        .map(|ts| ts.to_string())
                        .unwrap_or_default(),
                    body_chars: u64::try_from(chars).unwrap_or(0),
                    author: user.map(|username| PageAuthor {
                        username,
                        name,
                        email,
                    }),
                });
            }
            Ok(PageVersions {
                total: u64::try_from(total).unwrap_or(0),
                versions,
            })
        })
        .await
    }

    /// Read one stored version of a page by id, only if it belongs to the
    /// given `(workspace_id, project_id, path)`.
    ///
    /// A version id from another project, workspace or path returns `None`,
    /// exactly like an unknown id, so a raw id cannot read across scopes. An
    /// expired version (see `history_visible`) returns `None` the same way.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn page_version_body(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: String,
        version: PageId,
    ) -> StoreResult<Option<PageVersionBody>> {
        self.with_conn(move |conn| {
            let row = conn
                .query_row(
                    &format!(
                        "SELECT pg.title, pg.body, pg.frontmatter_json, pg.tier, pg.pinned, pg.created_at, \
                                (SELECT sp.id FROM pages sp \
                                 WHERE sp.id = pg.supersedes{prev_visible}) \
                         FROM pages pg \
                         WHERE pg.id = ?1 AND pg.workspace_id = ?2 AND pg.project_id = ?3 \
                           AND pg.path = ?4{visible}",
                        visible = history_visible("pg", "?5"),
                        prev_visible = history_visible("sp", "?5"),
                    ),
                    params![
                        version.as_bytes(),
                        workspace_id.as_bytes(),
                        project_id.as_bytes(),
                        path,
                        now_us()
                    ],
                    |row| {
                        Ok((
                            row.get::<_, String>(0)?,
                            row.get::<_, String>(1)?,
                            row.get::<_, String>(2)?,
                            row.get::<_, String>(3)?,
                            row.get::<_, i64>(4)?,
                            row.get::<_, i64>(5)?,
                            row.get::<_, Option<Vec<u8>>>(6)?,
                        ))
                    },
                )
                .optional()?;
            let Some((title, body, frontmatter, tier, pinned, created_us, supersedes)) = row else {
                return Ok(None);
            };
            Ok(Some(PageVersionBody {
                id: version,
                supersedes: supersedes.as_deref().map(PageId::from_slice).transpose()?,
                title,
                body,
                frontmatter: serde_json::from_str(&frontmatter).unwrap_or_default(),
                tier,
                pinned: pinned != 0,
                created_at: jiff::Timestamp::from_microsecond(created_us)
                    .map(|ts| ts.to_string())
                    .unwrap_or_default(),
            }))
        })
        .await
    }

    /// Return the latest page version id for one fully scoped path.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn latest_page_id_by_ids(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: String,
    ) -> StoreResult<Option<PageId>> {
        self.with_conn(move |conn| {
            let id: Option<Vec<u8>> = conn
                .query_row(
                    "SELECT id FROM pages \
                     WHERE workspace_id = ?1 AND project_id = ?2 AND path = ?3 \
                       AND is_latest = 1",
                    params![workspace_id.as_bytes(), project_id.as_bytes(), path],
                    |row| row.get(0),
                )
                .optional()?;
            Ok(id.map(|bytes| PageId::from_slice(&bytes)).transpose()?)
        })
        .await
    }

    /// Resolve the latest-version page ids for a batch of paths within one
    /// scope, in a single query. Missing/duplicate paths are simply absent from
    /// the result. Used by `memory_explore` for access reinforcement (C1): it
    /// surfaces a bounded set of pages by path (rules, slots, recent, pinned,
    /// settled) and bumps them all through one round-trip rather than a per-page
    /// N+1 (invariant #2).
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn latest_page_ids_by_paths(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        paths: Vec<String>,
    ) -> StoreResult<Vec<PageId>> {
        if paths.is_empty() {
            return Ok(Vec::new());
        }
        self.with_conn(move |conn| {
            // De-duplicate placeholders and bind (ws, proj) + each distinct path.
            let mut distinct: Vec<String> = paths;
            distinct.sort();
            distinct.dedup();
            let placeholders = std::iter::repeat_n("?", distinct.len())
                .collect::<Vec<_>>()
                .join(", ");
            let sql = format!(
                "SELECT id FROM pages \
                 WHERE workspace_id = ?1 AND project_id = ?2 AND is_latest = 1 \
                   AND path IN ({placeholders})"
            );
            let mut stmt = conn.prepare(&sql)?;
            let ws_bytes = workspace_id.as_bytes();
            let proj_bytes = project_id.as_bytes();
            let mut binds: Vec<&dyn rusqlite::ToSql> = Vec::with_capacity(distinct.len() + 2);
            binds.push(ws_bytes as &dyn rusqlite::ToSql);
            binds.push(proj_bytes as &dyn rusqlite::ToSql);
            for p in &distinct {
                binds.push(p as &dyn rusqlite::ToSql);
            }
            let rows = stmt.query_map(binds.as_slice(), |row| row.get::<_, Vec<u8>>(0))?;
            let mut ids = Vec::new();
            for r in rows {
                ids.push(PageId::from_slice(&r?)?);
            }
            Ok(ids)
        })
        .await
    }

    /// Return the subset of `paths` that name a latest unexpired page in this
    /// scope, in a single query. The batched counterpart of [`Self::latest_page_id_by_ids`]
    /// for callers that need to know *which* paths resolve — the consolidation
    /// link guard validates proposed cross-scope wikilinks against it (#1218).
    ///
    /// A `restricted` project reports nothing, whatever it holds (the global
    /// preferences project excepted, which every viewer may read). The link
    /// guard runs with no viewer — background consolidation has none — and a
    /// link it keeps lands on a page readers of the source project see, so
    /// answering for a restricted project would let anyone who can plant an
    /// observation learn which paths exist there.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn existing_latest_paths(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        paths: Vec<String>,
    ) -> StoreResult<Vec<String>> {
        if paths.is_empty() {
            return Ok(Vec::new());
        }
        self.with_conn(move |conn| {
            let mut distinct: Vec<String> = paths;
            distinct.sort();
            distinct.dedup();
            let placeholders = std::iter::repeat_n("?", distinct.len())
                .collect::<Vec<_>>()
                .join(", ");
            let ttl = not_expired("pg", "?3");
            let sql = format!(
                "SELECT pg.path FROM pages pg \
                 JOIN projects p ON p.id = pg.project_id \
                 JOIN workspaces w ON w.id = p.workspace_id \
                 WHERE pg.workspace_id = ?1 AND pg.project_id = ?2 AND pg.is_latest = 1{ttl} \
                   AND (p.access_mode <> 'restricted' \
                        OR (w.name = '{global_ws}' AND p.name = '{global_proj}')) \
                   AND pg.path IN ({placeholders})",
                global_ws = ai_memory_core::DEFAULT_WORKSPACE_NAME,
                global_proj = ai_memory_core::GLOBAL_SCOPE_PROJECT,
            );
            let mut stmt = conn.prepare(&sql)?;
            let ws_bytes = workspace_id.as_bytes();
            let proj_bytes = project_id.as_bytes();
            let now = now_us();
            let mut binds: Vec<&dyn rusqlite::ToSql> = Vec::with_capacity(distinct.len() + 3);
            binds.push(ws_bytes as &dyn rusqlite::ToSql);
            binds.push(proj_bytes as &dyn rusqlite::ToSql);
            binds.push(&now as &dyn rusqlite::ToSql);
            for p in &distinct {
                binds.push(p as &dyn rusqlite::ToSql);
            }
            let rows = stmt.query_map(binds.as_slice(), |row| row.get::<_, String>(0))?;
            let mut found = Vec::new();
            for r in rows {
                found.push(r?);
            }
            Ok(found)
        })
        .await
    }

    /// Return whether the latest version of one fully scoped page is expired.
    /// Returns `None` when the path has no latest indexed row.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn page_expired_by_ids(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: &str,
    ) -> StoreResult<Option<bool>> {
        let path = path.to_owned();
        self.with_conn(move |conn| {
            let expires_at: Option<Option<i64>> = conn
                .query_row(
                    "SELECT expires_at FROM pages \
                     WHERE workspace_id = ?1 AND project_id = ?2 AND path = ?3 \
                       AND is_latest = 1",
                    params![workspace_id.as_bytes(), project_id.as_bytes(), path],
                    |row| row.get(0),
                )
                .optional()?;
            Ok(expires_at.map(|expires_at| expires_at.is_some_and(|value| value <= now_us())))
        })
        .await
    }

    /// List auto-improvement proposals for one scope, optionally filtered by status.
    pub async fn list_auto_improve_proposals(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        status: Option<AutoImproveProposalStatus>,
        limit: usize,
    ) -> StoreResult<Vec<AutoImproveProposalSummary>> {
        self.with_conn(move |conn| {
            let limit = i64::try_from(limit).unwrap_or(i64::MAX);
            let sql = if status.is_some() {
                "SELECT id, run_id, workspace_id, project_id, status, operation, target_path, \
                        kind, title, confidence, staged_at, decided_at \
                 FROM auto_improve_proposals \
                 WHERE workspace_id = ?1 AND project_id = ?2 AND status = ?3 \
                 ORDER BY staged_at DESC LIMIT ?4"
            } else {
                "SELECT id, run_id, workspace_id, project_id, status, operation, target_path, \
                        kind, title, confidence, staged_at, decided_at \
                 FROM auto_improve_proposals \
                 WHERE workspace_id = ?1 AND project_id = ?2 \
                 ORDER BY staged_at DESC LIMIT ?3"
            };
            let mut stmt = conn.prepare(sql)?;
            let mut out = Vec::new();
            if let Some(status) = status {
                let rows = stmt.query_map(
                    params![
                        workspace_id.as_bytes(),
                        project_id.as_bytes(),
                        status.as_str(),
                        limit
                    ],
                    summary_from_row,
                )?;
                for row in rows {
                    out.push(row?);
                }
            } else {
                let rows = stmt.query_map(
                    params![workspace_id.as_bytes(), project_id.as_bytes(), limit],
                    summary_from_row,
                )?;
                for row in rows {
                    out.push(row?);
                }
            }
            Ok(out)
        })
        .await
    }

    /// Every project with pending auto-improvement proposals, with its
    /// pending count, ordered by workspace and project name.
    ///
    /// Unscoped by design: the only caller is the root-only `/web/pending`
    /// triage page, which gates on `Capability::Admin` before reading.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn list_pending_auto_improve_scopes(
        &self,
    ) -> StoreResult<Vec<PendingAutoImproveScope>> {
        self.with_conn(move |conn| {
            let mut stmt = conn.prepare(
                "SELECT p.workspace_id, p.project_id, workspaces.name, projects.name, \
                        COUNT(*) \
                 FROM auto_improve_proposals p \
                 JOIN workspaces ON workspaces.id = p.workspace_id \
                 JOIN projects ON projects.id = p.project_id \
                   AND projects.workspace_id = p.workspace_id \
                 WHERE p.status = ?1 \
                 GROUP BY p.workspace_id, p.project_id \
                 ORDER BY workspaces.name, projects.name",
            )?;
            let rows = stmt.query_map(
                params![AutoImproveProposalStatus::Pending.as_str()],
                |row| {
                    let pending: i64 = row.get(4)?;
                    Ok(PendingAutoImproveScope {
                        workspace_id: WorkspaceId::from_slice(&row.get::<_, Vec<u8>>(0)?)
                            .map_err(to_sql_err)?,
                        project_id: ProjectId::from_slice(&row.get::<_, Vec<u8>>(1)?)
                            .map_err(to_sql_err)?,
                        workspace_name: row.get(2)?,
                        project_name: row.get(3)?,
                        pending: u64::try_from(pending).unwrap_or_default(),
                    })
                },
            )?;
            let mut out = Vec::new();
            for row in rows {
                out.push(row?);
            }
            Ok(out)
        })
        .await
    }

    /// List pending auto-improvement proposals, oldest first, with the names
    /// and bodies a reviewer needs. `scope` limits the list to one project;
    /// `None` lists every project.
    ///
    /// Unscoped by design when `scope` is `None`: the only caller is the
    /// root-only `/web/pending` triage page, which gates on
    /// `Capability::Admin` before reading. One joined query instead of a
    /// per-project fan-out.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn list_pending_auto_improve_reviews(
        &self,
        scope: Option<(WorkspaceId, ProjectId)>,
        limit: usize,
    ) -> StoreResult<Vec<PendingAutoImproveReview>> {
        self.with_conn(move |conn| {
            let limit = i64::try_from(limit).unwrap_or(i64::MAX);
            let (workspace_id, project_id) = scope
                .map(|(ws, proj)| (Some(ws.as_bytes().to_vec()), Some(proj.as_bytes().to_vec())))
                .unwrap_or_default();
            let mut stmt = conn.prepare(
                "SELECT p.id, p.run_id, p.workspace_id, p.project_id, p.status, p.operation, \
                        p.target_path, p.kind, p.title, p.confidence, p.staged_at, \
                        p.decided_at, workspaces.name, projects.name, p.rationale, \
                        p.body_markdown, p.edit_mode \
                 FROM auto_improve_proposals p \
                 JOIN workspaces ON workspaces.id = p.workspace_id \
                 JOIN projects ON projects.id = p.project_id \
                   AND projects.workspace_id = p.workspace_id \
                 WHERE p.status = ?1 \
                   AND (?2 IS NULL OR (p.workspace_id = ?2 AND p.project_id = ?3)) \
                 ORDER BY p.staged_at ASC LIMIT ?4",
            )?;
            let rows = stmt.query_map(
                params![
                    AutoImproveProposalStatus::Pending.as_str(),
                    workspace_id,
                    project_id,
                    limit
                ],
                |row| {
                    Ok(PendingAutoImproveReview {
                        summary: summary_from_row(row)?,
                        workspace_name: row.get(12)?,
                        project_name: row.get(13)?,
                        rationale: row.get(14)?,
                        body_markdown: row.get(15)?,
                        edit_mode: row.get(16)?,
                    })
                },
            )?;
            let mut out = Vec::new();
            for row in rows {
                out.push(row?);
            }
            Ok(out)
        })
        .await
    }

    /// Read one proposal by id, failing closed when the scope does not match.
    pub async fn auto_improve_proposal_detail(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        proposal_id: AutoImproveProposalId,
    ) -> StoreResult<Option<AutoImproveProposalDetail>> {
        self.auto_improve_proposal_detail_with_owner(workspace_id, project_id, proposal_id)
            .await
            .map(|detail| detail.map(|owned| owned.detail))
    }

    /// Read one proposal plus the operator that staged it, failing closed when
    /// the scope does not match.
    pub async fn auto_improve_proposal_detail_with_owner(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        proposal_id: AutoImproveProposalId,
    ) -> StoreResult<Option<OwnedAutoImproveProposalDetail>> {
        self.with_conn(move |conn| {
            let row = conn
                .query_row(
                    "SELECT id, run_id, workspace_id, project_id, status, operation, target_path, \
                            kind, title, confidence, staged_at, decided_at, rationale, \
                            evidence_json, body_markdown, body_sha256, artifact_path, \
                            artifact_sha256, target_latest_page_id_at_stage, \
                            target_body_sha256_at_stage, target_updated_at_at_stage, \
                            decision_reason, decided_by_author_id, decided_by_actor_json, \
                            applied_page_id, checkpoint, edit_mode, patch_json, \
                            expected_base_body_sha256, materialized_base_body_sha256, \
                            staged_by_actor_user \
                     FROM auto_improve_proposals \
                     WHERE id = ?1 AND workspace_id = ?2 AND project_id = ?3",
                    params![
                        proposal_id.as_bytes(),
                        workspace_id.as_bytes(),
                        project_id.as_bytes(),
                    ],
                    |row| {
                        let summary = summary_from_row(row)?;
                        let evidence_raw: String = row.get(13)?;
                        let body_hash = bytes32(row.get(15)?).map_err(to_sql_err)?;
                        let artifact_hash = opt_bytes32(row.get(17)?).map_err(to_sql_err)?;
                        let staged_page_id = row
                            .get::<_, Option<Vec<u8>>>(18)?
                            .map(|b| PageId::from_slice(&b))
                            .transpose()
                            .map_err(to_sql_err)?;
                        let staged_body_hash = opt_bytes32(row.get(19)?).map_err(to_sql_err)?;
                        let decided_author = row
                            .get::<_, Option<Vec<u8>>>(22)?
                            .map(|b| UserId::from_slice(&b))
                            .transpose()
                            .map_err(to_sql_err)?;
                        let decided_actor_raw: Option<String> = row.get(23)?;
                        let applied_page_id = row
                            .get::<_, Option<Vec<u8>>>(24)?
                            .map(|b| PageId::from_slice(&b))
                            .transpose()
                            .map_err(to_sql_err)?;
                        let patch_raw: Option<String> = row.get(27)?;
                        Ok(OwnedAutoImproveProposalDetail {
                            detail: AutoImproveProposalDetail {
                                summary,
                                rationale: row.get(12)?,
                                evidence_json: serde_json::from_str(&evidence_raw)
                                    .map_err(to_sql_err)?,
                                body_markdown: row.get(14)?,
                                body_sha256: body_hash,
                                artifact_path: row.get(16)?,
                                artifact_sha256: artifact_hash,
                                target_latest_page_id_at_stage: staged_page_id,
                                target_body_sha256_at_stage: staged_body_hash,
                                target_updated_at_at_stage: row.get(20)?,
                                decision_reason: row.get(21)?,
                                decided_by_author_id: decided_author,
                                decided_by_actor_json: decided_actor_raw
                                    .map(|raw| serde_json::from_str(&raw))
                                    .transpose()
                                    .map_err(to_sql_err)?,
                                applied_page_id,
                                checkpoint: row.get(25)?,
                                edit_mode: row.get(26)?,
                                patch_json: patch_raw
                                    .map(|raw| serde_json::from_str(&raw))
                                    .transpose()
                                    .map_err(to_sql_err)?,
                                expected_base_body_sha256: opt_bytes32(row.get(28)?)
                                    .map_err(to_sql_err)?,
                                materialized_base_body_sha256: opt_bytes32(row.get(29)?)
                                    .map_err(to_sql_err)?,
                                events: Vec::new(),
                            },
                            staged_by_actor_user: row.get(30)?,
                        })
                    },
                )
                .optional()?;
            let Some(mut detail) = row else {
                return Ok(None);
            };
            let mut stmt = conn.prepare(
                "SELECT id, proposal_id, event, actor_json, author_id, detail_json, at \
                 FROM auto_improve_proposal_events \
                 WHERE proposal_id = ?1 ORDER BY at ASC, id ASC",
            )?;
            let rows = stmt.query_map(params![proposal_id.as_bytes()], |row| {
                let proposal_id = AutoImproveProposalId::from_slice(&row.get::<_, Vec<u8>>(1)?)
                    .map_err(to_sql_err)?;
                let actor_raw: String = row.get(3)?;
                let detail_raw: String = row.get(5)?;
                let author_id = row
                    .get::<_, Option<Vec<u8>>>(4)?
                    .map(|b| UserId::from_slice(&b))
                    .transpose()
                    .map_err(to_sql_err)?;
                Ok(AutoImproveProposalEvent {
                    id: row.get(0)?,
                    proposal_id,
                    event: row.get(2)?,
                    actor_json: serde_json::from_str(&actor_raw).map_err(to_sql_err)?,
                    author_id,
                    detail_json: serde_json::from_str(&detail_raw).map_err(to_sql_err)?,
                    at: row.get(6)?,
                })
            })?;
            for row in rows {
                detail.detail.events.push(row?);
            }
            Ok(Some(detail))
        })
        .await
    }

    /// Read recent rejection-buffer entries for one workspace/project scope.
    pub async fn recent_auto_improve_rejections(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        limit: usize,
        since_created_at: Option<i64>,
    ) -> StoreResult<Vec<AutoImproveRejectionSummary>> {
        self.with_conn(move |conn| {
            let limit = i64::try_from(limit).unwrap_or(i64::MAX);
            let since = since_created_at.unwrap_or(0);
            let mut stmt = conn.prepare(
                "SELECT id, workspace_id, project_id, target_path, kind, operation, edit_mode, \
                        reason, normalized_fingerprint, summary, evidence_json, source_run_id, \
                        source_proposal_id, created_at \
                 FROM auto_improve_rejections \
                 WHERE workspace_id = ?1 AND project_id = ?2 AND created_at >= ?3 \
                 ORDER BY created_at DESC LIMIT ?4",
            )?;
            let rows = stmt.query_map(
                params![workspace_id.as_bytes(), project_id.as_bytes(), since, limit],
                |row| {
                    let id_bytes: Vec<u8> = row.get(0)?;
                    let id = Uuid::from_slice(&id_bytes).map_err(to_sql_err)?.to_string();
                    let workspace_id =
                        WorkspaceId::from_slice(&row.get::<_, Vec<u8>>(1)?).map_err(to_sql_err)?;
                    let project_id =
                        ProjectId::from_slice(&row.get::<_, Vec<u8>>(2)?).map_err(to_sql_err)?;
                    let evidence_raw: String = row.get(10)?;
                    let source_run_id = row
                        .get::<_, Option<Vec<u8>>>(11)?
                        .map(|b| AutoImproveRunId::from_slice(&b))
                        .transpose()
                        .map_err(to_sql_err)?;
                    let source_proposal_id = row
                        .get::<_, Option<Vec<u8>>>(12)?
                        .map(|b| AutoImproveProposalId::from_slice(&b))
                        .transpose()
                        .map_err(to_sql_err)?;
                    Ok(AutoImproveRejectionSummary {
                        id,
                        workspace_id,
                        project_id,
                        target_path: row.get(3)?,
                        kind: row.get(4)?,
                        operation: row.get(5)?,
                        edit_mode: row.get(6)?,
                        reason: row.get(7)?,
                        normalized_fingerprint: row.get(8)?,
                        summary: row.get(9)?,
                        evidence_json: serde_json::from_str(&evidence_raw).map_err(to_sql_err)?,
                        source_run_id,
                        source_proposal_id,
                        created_at: row.get(13)?,
                    })
                },
            )?;
            let mut out = Vec::new();
            for row in rows {
                out.push(row?);
            }
            Ok(out)
        })
        .await
    }

    /// Aggregate auto-improvement telemetry for one workspace/project scope.
    ///
    /// `since_created_at` filters by run/proposal/rejection creation time in Unix
    /// microseconds. Maintenance/report proposals are excluded from learning
    /// metrics and counted separately.
    pub async fn auto_improve_telemetry_aggregate(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        since_created_at: i64,
        top_limit: usize,
    ) -> StoreResult<AutoImproveTelemetryAggregate> {
        self.with_conn(move |conn| {
            let top_limit = i64::try_from(top_limit).unwrap_or(i64::MAX);
            let run_count: i64 = conn.query_row(
                "SELECT COUNT(*) FROM auto_improve_runs
                 WHERE workspace_id = ?1 AND project_id = ?2 AND created_at >= ?3",
                params![
                    workspace_id.as_bytes(),
                    project_id.as_bytes(),
                    since_created_at
                ],
                |row| row.get(0),
            )?;
            let runs_with_learning_proposals: i64 = conn.query_row(
                "SELECT COUNT(DISTINCT run_id) FROM auto_improve_proposals
                 WHERE workspace_id = ?1 AND project_id = ?2 AND staged_at >= ?3
                   AND kind NOT IN ('curator_report', 'auto_improve_report')",
                params![
                    workspace_id.as_bytes(),
                    project_id.as_bytes(),
                    since_created_at
                ],
                |row| row.get(0),
            )?;
            Ok(AutoImproveTelemetryAggregate {
                run_count: usize::try_from(run_count).unwrap_or(usize::MAX),
                runs_with_learning_proposals: usize::try_from(runs_with_learning_proposals)
                    .unwrap_or(usize::MAX),
                proposals_by_status: auto_improve_group_counts(
                    conn,
                    "status",
                    workspace_id,
                    project_id,
                    since_created_at,
                    None,
                )?,
                proposals_by_operation: auto_improve_group_counts(
                    conn,
                    "operation",
                    workspace_id,
                    project_id,
                    since_created_at,
                    None,
                )?,
                proposals_by_edit_mode: auto_improve_group_counts(
                    conn,
                    "edit_mode",
                    workspace_id,
                    project_id,
                    since_created_at,
                    None,
                )?,
                proposals_by_kind: auto_improve_group_counts(
                    conn,
                    "kind",
                    workspace_id,
                    project_id,
                    since_created_at,
                    None,
                )?,
                maintenance_proposals_by_kind: auto_improve_group_counts(
                    conn,
                    "kind",
                    workspace_id,
                    project_id,
                    since_created_at,
                    Some("kind IN ('curator_report', 'auto_improve_report')"),
                )?,
                top_targets: auto_improve_group_counts(
                    conn,
                    "target_path",
                    workspace_id,
                    project_id,
                    since_created_at,
                    Some("kind NOT IN ('curator_report', 'auto_improve_report')"),
                )?
                .into_iter()
                .take(usize::try_from(top_limit).unwrap_or(usize::MAX))
                .collect(),
                rejections_by_reason: auto_improve_rejection_group_counts(
                    conn,
                    "r.reason",
                    workspace_id,
                    project_id,
                    since_created_at,
                    top_limit,
                )?,
                repeated_rejection_fingerprints: auto_improve_repeated_rejection_fingerprints(
                    conn,
                    workspace_id,
                    project_id,
                    since_created_at,
                    top_limit,
                )?,
                rejected_targets: auto_improve_rejection_group_counts(
                    conn,
                    "COALESCE(r.target_path, '(none)')",
                    workspace_id,
                    project_id,
                    since_created_at,
                    top_limit,
                )?,
            })
        })
        .await
    }

    /// Look up a workspace id by name without creating it.
    ///
    /// Returns `None` when no workspace with the given name exists.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn find_workspace(&self, name: String) -> StoreResult<Option<WorkspaceId>> {
        self.with_conn(move |conn| {
            let row_opt = conn
                .query_row(
                    "SELECT id FROM workspaces WHERE name = ?1",
                    params![name],
                    |row| {
                        let bytes: Vec<u8> = row.get(0)?;
                        Ok(bytes)
                    },
                )
                .optional()?;
            row_opt
                .map(|bytes| WorkspaceId::from_slice(&bytes).map_err(StoreError::from))
                .transpose()
        })
        .await
    }

    /// Diagnose a requested project coordinate without creating, claiming, or renaming.
    ///
    /// The lookup uses the same bounded exact/canonical/legacy indexes as normal
    /// compatibility resolution, but retains probe provenance and conflicting
    /// candidates for operator diagnostics.
    pub async fn diagnose_project_coordinate(
        &self,
        workspace: String,
        requested_name: String,
        repository: Option<ai_memory_core::repository_identity::RepositoryIdentity>,
        requested_style: ai_memory_core::repository_identity::IdentityStyle,
    ) -> StoreResult<ProjectCoordinateDiagnostic> {
        let canonical_candidate = repository
            .as_ref()
            .and_then(ai_memory_core::repository_identity::path_style_name);
        let legacy_candidate = repository
            .as_ref()
            .and_then(ai_memory_core::repository_identity::legacy_basename_name);
        let local_source = repository.as_ref().map(|identity| identity.source);
        let requested = requested_name.clone();
        let workspace_name = workspace.clone();
        self.with_conn(move |conn| {
            let workspace_id = conn
                .query_row(
                    "SELECT id FROM workspaces WHERE name = ?1",
                    params![workspace_name],
                    |row| row.get::<_, Vec<u8>>(0),
                )
                .optional()?
                .map(|bytes| WorkspaceId::from_slice(&bytes))
                .transpose()?;
            let Some(workspace_id) = workspace_id else {
                return Ok(ProjectCoordinateDiagnostic {
                    workspace,
                    requested_name,
                    status: ProjectCoordinateStatus::Missing,
                    project_id: None,
                    current_name: None,
                    canonical_candidate,
                    legacy_candidate,
                    identity_source: local_source.map(|source| source.as_str().to_owned()),
                    identity_style: local_source.map(|_| requested_style.as_str().to_owned()),
                    rename_eligible: false,
                    collision_reason: None,
                    candidate_count: 0,
                });
            };

            let matches = crate::project_coordinates::matches(
                conn,
                workspace_id,
                &requested,
                repository.as_ref(),
            )?;
            let requested_matches = matches
                .iter()
                .filter(|candidate| candidate.provenance.requested())
                .collect::<Vec<_>>();
            let identity_match = matches
                .iter()
                .find(|candidate| candidate.provenance.identity);
            let exact_match = requested_matches
                .iter()
                .copied()
                .find(|candidate| candidate.provenance.exact);
            let canonical_collision = identity_match.and_then(|identity| {
                matches.iter().find(|candidate| {
                    candidate.provenance.canonical_target && candidate.id != identity.id
                })
            });
            let identity_conflict = repository.as_ref().is_some_and(|repository| {
                exact_match.is_some_and(|candidate| {
                    candidate
                        .identity
                        .as_deref()
                        .is_some_and(|stored| stored != repository.identity)
                })
            });
            let identityless_collision = repository.is_some()
                && exact_match.is_some_and(|candidate| candidate.identity.is_none());
            let ambiguous = requested_matches.len() > 1
                || identity_conflict
                || identityless_collision
                || (identity_match.is_some()
                    && exact_match
                        .is_some_and(|exact| Some(exact.id) != identity_match.map(|row| row.id)));

            let primary = identity_match.or_else(|| requested_matches.first().copied());
            let status = if ambiguous {
                ProjectCoordinateStatus::Ambiguous
            } else if let Some(candidate) = requested_matches.first() {
                if candidate.provenance.exact {
                    ProjectCoordinateStatus::Exact
                } else if candidate.provenance.canonical_compat {
                    ProjectCoordinateStatus::CanonicalCompat
                } else {
                    ProjectCoordinateStatus::LegacyCompat
                }
            } else {
                ProjectCoordinateStatus::Missing
            };
            let collision_reason = if identityless_collision {
                Some(ProjectCoordinateCollisionReason::UnclaimedIdentitylessProject)
            } else if let Some(holder) = canonical_collision {
                Some(if holder.identity_source.as_deref() == Some("git_remote") {
                    ProjectCoordinateCollisionReason::CrossForgeCollision
                } else {
                    ProjectCoordinateCollisionReason::CanonicalTargetOccupied
                })
            } else if identity_conflict {
                Some(ProjectCoordinateCollisionReason::CrossIdentityOccupied)
            } else if requested_matches.len() > 1 && identity_match.is_some() {
                Some(ProjectCoordinateCollisionReason::CrossForgeCollision)
            } else if ambiguous {
                Some(ProjectCoordinateCollisionReason::MultipleProjects)
            } else {
                None
            };
            let rename_eligible = requested_matches.len() == 1
                && requested_matches.first().is_some_and(|candidate| {
                    crate::project_coordinates::promotion_target(candidate, &requested).is_some()
                })
                && collision_reason.is_none();

            Ok(ProjectCoordinateDiagnostic {
                workspace,
                requested_name,
                status,
                project_id: primary.map(|candidate| candidate.id),
                current_name: primary.map(|candidate| candidate.current_name.clone()),
                canonical_candidate: canonical_candidate
                    .or_else(|| primary.and_then(|candidate| candidate.canonical_name.clone())),
                legacy_candidate: legacy_candidate
                    .or_else(|| primary.and_then(|candidate| candidate.legacy_name.clone())),
                identity_source: local_source
                    .map(|source| source.as_str().to_owned())
                    .or_else(|| primary.and_then(|candidate| candidate.identity_source.clone())),
                identity_style: local_source.map(|_| requested_style.as_str().to_owned()),
                rename_eligible,
                collision_reason,
                candidate_count: matches.len(),
            })
        })
        .await
    }

    /// Look up a project id by `(workspace_id, name)` without creating it.
    ///
    /// Returns `None` when no project with the given name exists in the workspace.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn find_project(
        &self,
        workspace_id: WorkspaceId,
        name: String,
    ) -> StoreResult<Option<ProjectId>> {
        self.with_conn(move |conn| {
            let row_opt = conn
                .query_row(
                    "SELECT id FROM projects WHERE workspace_id = ?1 AND name = ?2",
                    params![workspace_id.as_bytes(), name],
                    |row| {
                        let bytes: Vec<u8> = row.get(0)?;
                        Ok(bytes)
                    },
                )
                .optional()?;
            row_opt
                .map(|bytes| ProjectId::from_slice(&bytes).map_err(StoreError::from))
                .transpose()
        })
        .await
    }

    /// Resolve an existing project by its exact, canonical path-style, or v2
    /// legacy basename key without creating or renaming anything.
    pub(crate) async fn resolve_existing_project_name(
        &self,
        workspace_id: WorkspaceId,
        name: String,
    ) -> StoreResult<Option<ProjectId>> {
        self.with_conn(move |conn| {
            crate::project_coordinates::resolve(conn, workspace_id, &name)
                .map(|matched| matched.map(|matched| matched.id))
        })
        .await
    }

    /// Bounded coordinate candidates for an explicitly authorized picker.
    /// These are internal rows: callers must authorize each before disclosure.
    pub async fn project_coordinate_candidates(
        &self,
        workspace_id: WorkspaceId,
        name: String,
    ) -> StoreResult<Vec<(ProjectId, String)>> {
        self.with_conn(move |conn| {
            crate::project_coordinates::matches_bounded(conn, workspace_id, &name, None, 101).map(
                |rows| {
                    rows.into_iter()
                        .map(|row| (row.id, row.current_name))
                        .collect()
                },
            )
        })
        .await
    }

    /// Resolve a local marker's former names inside one workspace, requiring
    /// the selected row to carry the checkout's full git-remote identity.
    pub async fn resolve_existing_project_aliases(
        &self,
        workspace_id: WorkspaceId,
        canonical: String,
        aliases: ai_memory_core::repository_identity::MarkerAliases,
        repository: ai_memory_core::repository_identity::RepositoryIdentity,
    ) -> StoreResult<Option<ProjectId>> {
        self.with_conn(move |conn| {
            crate::project_coordinates::resolve_aliases(
                conn,
                workspace_id,
                &canonical,
                &aliases,
                &repository,
            )
            .map(|matched| matched.map(|matched| matched.id))
        })
        .await
    }

    /// Find the existing project whose `repo_path` is the longest
    /// prefix of `cwd`, if any. Used by the hook router before
    /// auto-creating a new project from `basename(cwd)` so an event
    /// whose cwd is inside an existing project's tree resolves to
    /// that parent instead of materialising a fragment project for
    /// the subdirectory name.
    ///
    /// `ORDER BY length(repo_path) DESC` picks the most-specific
    /// match: if the operator declared a sub-project via
    /// `.ai-memory.toml` (which writes its own row with a longer
    /// `repo_path`), the sub-project wins over its outer parent.
    ///
    /// **Boundary safety.** Every layer of this query has explicit
    /// guards so a path-shaped value can't accidentally widen the
    /// match set:
    ///
    /// - `workspace_id = ?1` — never matches a project in another
    ///   workspace.
    /// - `repo_path IS NOT NULL` plus Rust-side normalization rejects stored
    ///   values that would match too broadly (`NULL`, `''`, `/`) or fail the
    ///   `<repo_path>/%` boundary (trailing slash/backslash).
    /// - Stored `repo_path` wildcards (`%`, `_`) are compared as literal path
    ///   bytes in Rust, not as SQL `LIKE` wildcards.
    /// - A normalized stored `repo_path` equal to the operator's home
    ///   directory (`home`) is never matched.
    ///   Such a row would be a prefix catch-all for every project
    ///   beneath `$HOME`; the caller passes the server's own `$HOME`
    ///   (filesystem root `/` is already excluded by the
    ///   `length(repo_path) > 1` guard). A `None` `home` is a no-op.
    /// - Input canonicalisation — trailing slashes stripped; cwds
    ///   containing dot-segments (`/foo/../bar`, `/./x`) are rejected
    ///   outright so a traversal-style path can't match a parent it
    ///   doesn't logically belong to.
    ///
    /// Returns `None` (caller falls through to create-by-basename)
    /// for every defensive case so a bad input degrades the same way
    /// as "no match" rather than picking the wrong project.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn find_project_by_cwd_prefix(
        &self,
        workspace_id: WorkspaceId,
        cwd: String,
        home: Option<&str>,
    ) -> StoreResult<Option<(ProjectId, String)>> {
        let home = home.map(|h| normalize_cwd(h).into_owned());
        let cwd_norm = normalize_cwd(&cwd).into_owned();
        if !is_safe_cwd_for_prefix_match(&cwd_norm) {
            return Ok(None);
        }
        self.with_conn(move |conn| {
            // Compare in Rust instead of SQL LIKE so stored `%`/`_` bytes stay
            // literal and legacy Windows rows with backslashes keep matching a
            // slash-normalized hook cwd. New writes normalize `repo_path`, but
            // this compatibility read path protects existing databases.
            let mut stmt = conn.prepare(
                "SELECT id, name, repo_path FROM projects \
                 WHERE workspace_id = ?1 AND repo_path IS NOT NULL",
            )?;
            let rows = stmt.query_map(params![workspace_id.as_bytes()], |row| {
                Ok((
                    row.get::<_, Vec<u8>>(0)?,
                    row.get::<_, String>(1)?,
                    row.get::<_, String>(2)?,
                ))
            })?;
            let mut matches = Vec::new();
            for row in rows {
                let (bytes, name, repo_path) = row?;
                if has_trailing_path_separator(&repo_path) {
                    continue;
                }
                let repo_norm = normalize_cwd(&repo_path).into_owned();
                if repo_norm.len() <= 1
                    || !is_safe_cwd_for_prefix_match(&repo_norm)
                    || home.as_deref() == Some(repo_norm.as_str())
                {
                    continue;
                }
                if cwd_within(&repo_norm, &cwd_norm) {
                    matches.push((bytes, name, repo_norm.len()));
                }
            }
            matches.sort_by_key(|entry| std::cmp::Reverse(entry.2));
            matches
                .into_iter()
                .next()
                .map(|(bytes, name, _)| {
                    ProjectId::from_slice(&bytes)
                        .map(|id| (id, name))
                        .map_err(StoreError::from)
                })
                .transpose()
        })
        .await
    }

    /// Structural cross-project contamination audit (cheap, SQL-only, no LLM).
    ///
    /// One HIGH-precision heuristic:
    /// - **CHECK A** (`session_wrong_bucket`): a session whose `cwd`
    ///   longest-prefix-resolves to a *different* project than the one it landed
    ///   in — the direct signature of the auto-scope bleed bug. Resolved with the
    ///   same prefix and cwd-safety rules as [`Self::find_project_by_cwd_prefix`],
    ///   so the audit never claims a session a live resolve would not.
    ///
    /// Note: an earlier "observation drifted from its session's project" check
    /// was removed. With per-event cwd resolution, an observation's `project_id`
    /// is set from the cwd *of that event* — so an agent that legitimately
    /// `cd`s across repos in one session produces observations whose project
    /// differs from the session's home project. That is correct attribution,
    /// not contamination, so the check flagged normal cross-repo work as a false
    /// positive (and observations carry no cwd of their own to disambiguate).
    /// CHECK A — anchored on the session's own cwd — remains the precise signal.
    ///
    /// Detects only contamination with a STRUCTURAL trace; purely semantic
    /// mislandings (topic-level, no cwd/session anomaly) are not detectable.
    /// `scope` restricts findings to the given landed `(workspace, project)`.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn audit_contamination(
        &self,
        scope: Option<(WorkspaceId, ProjectId)>,
        home: Option<&str>,
    ) -> StoreResult<ContaminationReport> {
        let scoped = scope.is_some();
        let scoped_project = scope.as_ref().map(|(_, project)| *project);
        let home = home.map(|h| normalize_cwd(h).into_owned());
        let scope_params: Vec<Value> = match &scope {
            Some((ws, proj)) => vec![
                Value::Blob(ws.as_bytes().to_vec()),
                Value::Blob(proj.as_bytes().to_vec()),
            ],
            None => Vec::new(),
        };

        // One connection: the candidate session list + the valid repo_path
        // prefixes used to resolve CHECK A. Loading prefixes once avoids a
        // reader query per historical session while preserving the same path
        // boundary and safety rules as the runtime resolver.
        type Candidate = (String, WorkspaceId, ProjectId, String, String, String);
        type Prefix = (WorkspaceId, ProjectId, String, String);
        // CHECK B's input: every project in scope's workspace with its counts.
        // A project-scoped audit still needs its peers to detect a collision;
        // only the emitted findings are restricted to the requested project.
        type ProjectRow = (String, String, Vec<u8>, String, u64, u64, i64);
        let (mut findings, candidates, prefixes, projects): (
            Vec<ContaminationFinding>,
            Vec<Candidate>,
            Vec<Prefix>,
            Vec<ProjectRow>,
        ) = self
            .with_conn(move |conn| {
                // CHECK A findings are built after this closure (they need the
                // repo_path prefixes resolved outside the DB connection); this
                // closure only gathers the raw inputs.
                let findings: Vec<ContaminationFinding> = Vec::new();

                // Candidate sessions (cwd present) — resolved outside the conn.
                let mut s_sql = String::from(
                    "SELECT lower(hex(s.id)), s.workspace_id, s.project_id, wl.name, pl.name, s.cwd \
                     FROM sessions s \
                     JOIN workspaces wl ON wl.id = s.workspace_id \
                     JOIN projects pl ON pl.id = s.project_id \
                     WHERE s.cwd IS NOT NULL",
                );
                if scoped {
                    s_sql.push_str(" AND s.workspace_id = ? AND s.project_id = ?");
                }
                let mut candidates: Vec<Candidate> = Vec::new();
                {
                    let mut stmt = conn.prepare(&s_sql)?;
                    let rows = stmt.query_map(params_from_iter(scope_params.iter()), |row| {
                        Ok((
                            row.get::<_, String>(0)?,
                            row.get::<_, Vec<u8>>(1)?,
                            row.get::<_, Vec<u8>>(2)?,
                            row.get::<_, String>(3)?,
                            row.get::<_, String>(4)?,
                            row.get::<_, String>(5)?,
                        ))
                    })?;
                    for r in rows {
                        let (id, ws_b, proj_b, lws, lproj, cwd) = r?;
                        candidates.push((
                            id,
                            WorkspaceId::from_slice(&ws_b)?,
                            ProjectId::from_slice(&proj_b)?,
                            lws,
                            lproj,
                            cwd,
                        ));
                    }
                }

                let mut p_sql = String::from(
                    "SELECT workspace_id, id, name, repo_path \
                     FROM projects \
                     WHERE repo_path IS NOT NULL \
                       AND length(repo_path) > 1 \
                       AND repo_path NOT LIKE '%/'",
                );
                if scoped {
                    p_sql.push_str(" AND workspace_id = ?");
                }
                p_sql.push_str(" ORDER BY length(repo_path) DESC");
                let mut prefixes: Vec<Prefix> = Vec::new();
                {
                    let mut stmt = conn.prepare(&p_sql)?;
                    if scoped {
                        let rows = stmt.query_map(params_from_iter(scope_params.iter().take(1)), |row| {
                            Ok((
                                row.get::<_, Vec<u8>>(0)?,
                                row.get::<_, Vec<u8>>(1)?,
                                row.get::<_, String>(2)?,
                                row.get::<_, String>(3)?,
                            ))
                        })?;
                        for r in rows {
                            let (ws_b, proj_b, name, repo_path) = r?;
                            if has_trailing_path_separator(&repo_path) {
                                continue;
                            }
                            let repo_path = normalize_cwd(&repo_path).into_owned();
                            if repo_path.len() <= 1
                                || !is_safe_cwd_for_prefix_match(&repo_path)
                                || home.as_deref() == Some(repo_path.as_str())
                            {
                                continue;
                            }
                            prefixes.push((
                                WorkspaceId::from_slice(&ws_b)?,
                                ProjectId::from_slice(&proj_b)?,
                                name,
                                repo_path,
                            ));
                        }
                    } else {
                        let rows = stmt.query_map([], |row| {
                            Ok((
                                row.get::<_, Vec<u8>>(0)?,
                                row.get::<_, Vec<u8>>(1)?,
                                row.get::<_, String>(2)?,
                                row.get::<_, String>(3)?,
                            ))
                        })?;
                        for r in rows {
                            let (ws_b, proj_b, name, repo_path) = r?;
                            if has_trailing_path_separator(&repo_path) {
                                continue;
                            }
                            let repo_path = normalize_cwd(&repo_path).into_owned();
                            if repo_path.len() <= 1
                                || !is_safe_cwd_for_prefix_match(&repo_path)
                                || home.as_deref() == Some(repo_path.as_str())
                            {
                                continue;
                            }
                            prefixes.push((
                                WorkspaceId::from_slice(&ws_b)?,
                                ProjectId::from_slice(&proj_b)?,
                                name,
                                repo_path,
                            ));
                        }
                    }
                }

                // CHECK B: project rows with their page and session counts.
                // The fold happens outside the connection; the counts ride the
                // same query so a large store costs two index scans, not 2N.
                let mut p_sql = String::from(
                    "SELECT lower(hex(p.id)), wl.name, p.id, p.name, \
                            (SELECT COUNT(*) FROM pages pg WHERE pg.project_id = p.id \
                              AND pg.is_latest = 1), \
                            (SELECT COUNT(*) FROM sessions s WHERE s.project_id = p.id), \
                            max(p.created_at, \
                              COALESCE((SELECT MAX(pg.updated_at) FROM pages pg WHERE pg.project_id = p.id), 0), \
                              COALESCE((SELECT MAX(COALESCE(s.ended_at, s.started_at)) FROM sessions s WHERE s.project_id = p.id), 0), \
                              COALESCE((SELECT MAX(o.created_at) FROM observations o WHERE o.project_id = p.id), 0)) \
                     FROM projects p JOIN workspaces wl ON wl.id = p.workspace_id",
                );
                if scoped {
                    p_sql.push_str(" WHERE p.workspace_id = ?");
                }
                let mut projects: Vec<ProjectRow> = Vec::new();
                {
                    let mut stmt = conn.prepare(&p_sql)?;
                    let params = if scoped {
                        &scope_params[..1]
                    } else {
                        &scope_params[..0]
                    };
                    let rows = stmt.query_map(params_from_iter(params.iter()), |row| {
                        Ok((
                            row.get::<_, String>(0)?,
                            row.get::<_, String>(1)?,
                            row.get::<_, Vec<u8>>(2)?,
                            row.get::<_, String>(3)?,
                            u64::try_from(row.get::<_, i64>(4)?).unwrap_or(0),
                            u64::try_from(row.get::<_, i64>(5)?).unwrap_or(0),
                            row.get::<_, i64>(6)?,
                        ))
                    })?;
                    for r in rows {
                        projects.push(r?);
                    }
                }

                Ok((findings, candidates, prefixes, projects))
            })
            .await?;

        // CHECK A: resolve each session's cwd against preloaded valid prefixes
        // and flag a bucket mismatch.
        for (id, ws, landed_proj, landed_ws_name, landed_proj_name, cwd) in candidates {
            let cwd_norm = normalize_cwd(&cwd).into_owned();
            if !is_safe_cwd_for_prefix_match(&cwd_norm) {
                continue;
            }
            let resolved = prefixes.iter().find(|(prefix_ws, _, _, repo_path)| {
                *prefix_ws == ws && cwd_within(repo_path, &cwd_norm)
            });
            if let Some((_, resolved_proj, resolved_name, _)) = resolved
                && *resolved_proj != landed_proj
            {
                findings.push(ContaminationFinding {
                    check: "session_wrong_bucket",
                    confidence: "high",
                    entity_kind: "session",
                    entity_id: id,
                    landed_workspace: landed_ws_name,
                    landed_project: landed_proj_name,
                    expected_project: Some(resolved_name.clone()),
                    cwd: Some(cwd),
                    peer_projects: None,
                    pages: None,
                    sessions: None,
                    collision_kind: None,
                    last_activity_us: None,
                });
            }
        }

        // CHECK B: projects whose names collide once spelling differences
        // cannot be told apart (case, Unicode composition, separators). Two
        // rows mean one working copy reached two projects, and no read can say
        // which one a marker-less directory means (#1645).
        let mut groups: BTreeMap<String, Vec<&ProjectRow>> = BTreeMap::new();
        for project in &projects {
            groups
                .entry(project_name_fold_key(&project.3))
                .or_default()
                .push(project);
        }
        for (_, peers) in groups.iter().filter(|(_, peers)| peers.len() > 1) {
            for project in peers {
                if scoped_project
                    .is_some_and(|selected| project.2.as_slice() != selected.as_bytes())
                {
                    continue;
                }
                let others: Vec<&str> = peers
                    .iter()
                    .filter(|peer| peer.0 != project.0)
                    .map(|peer| peer.3.as_str())
                    .collect();
                let case_key = project_name_case_key(&project.3);
                let case_differs = peers
                    .iter()
                    .any(|peer| peer.0 != project.0 && project_name_case_key(&peer.3) == case_key);
                let accent_differs = peers
                    .iter()
                    .any(|peer| peer.0 != project.0 && project_name_case_key(&peer.3) != case_key);
                let collision_kind = match (case_differs, accent_differs) {
                    (true, true) => "case_and_accent",
                    (true, false) => "case",
                    (false, true) => "accent",
                    (false, false) => "spelling",
                };
                findings.push(ContaminationFinding {
                    check: "project_name_collision",
                    confidence: "medium",
                    entity_kind: "project",
                    entity_id: project.0.clone(),
                    landed_workspace: project.1.clone(),
                    landed_project: project.3.clone(),
                    expected_project: None,
                    cwd: None,
                    peer_projects: Some(others.join(", ")),
                    pages: Some(project.4),
                    sessions: Some(project.5),
                    collision_kind: Some(collision_kind),
                    last_activity_us: Some(project.6),
                });
            }
        }

        let summary = ContaminationSummary {
            sessions_misbucketed: findings
                .iter()
                .filter(|f| f.check == "session_wrong_bucket")
                .count(),
            project_name_collisions: findings
                .iter()
                .filter(|f| f.check == "project_name_collision")
                .count(),
        };
        Ok(ContaminationReport { summary, findings })
    }

    /// List `audit_log` rows newest-first, resolving names through LEFT JOINs.
    ///
    /// Workspace/project filters match on **name** (the same convention as
    /// [`Self::list_pages`]). `before_id` is a keyset cursor (`id < ?` under
    /// `ORDER BY id DESC`): new events get higher ids, so they land on later
    /// first pages instead of shifting this window and duplicating or skipping
    /// rows already seen. `limit` is clamped to `1..=200`.
    ///
    /// `detail` is the schema column; the only writer currently stores the
    /// literal `{}`.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn list_audit_events(&self, filter: AuditLogFilter) -> StoreResult<Vec<AuditEvent>> {
        let limit = filter.limit.clamp(1, 200);
        let workspace = filter.workspace.filter(|s| !s.is_empty());
        let project = filter.project.filter(|s| !s.is_empty());
        let op = filter.op.filter(|s| !s.is_empty());
        let before_id = filter.before_id;
        self.with_conn(move |conn| {
            let mut sql = String::from(
                "SELECT a.id, a.at, a.op, w.name, p.name, pg.path, u.username, a.detail \
                 FROM audit_log a \
                 LEFT JOIN workspaces w ON w.id = a.workspace_id \
                 LEFT JOIN projects p ON p.id = a.project_id \
                 LEFT JOIN pages pg ON pg.id = a.page_id \
                 LEFT JOIN users u ON u.id = a.author_id",
            );
            let mut binds: Vec<Value> = Vec::new();
            let mut clauses: Vec<&str> = Vec::new();
            if workspace.is_some() {
                clauses.push("w.name = ?");
            }
            if project.is_some() {
                clauses.push("p.name = ?");
            }
            if op.is_some() {
                clauses.push("a.op = ?");
            }
            if before_id.is_some() {
                clauses.push("a.id < ?");
            }
            if !clauses.is_empty() {
                sql.push_str(" WHERE ");
                sql.push_str(&clauses.join(" AND "));
            }
            sql.push_str(" ORDER BY a.id DESC LIMIT ?");
            if let Some(ws) = &workspace {
                binds.push(Value::Text(ws.clone()));
            }
            if let Some(proj) = &project {
                binds.push(Value::Text(proj.clone()));
            }
            if let Some(op) = &op {
                binds.push(Value::Text(op.clone()));
            }
            if let Some(before) = before_id {
                binds.push(Value::Integer(before));
            }
            binds.push(Value::Integer(i64::try_from(limit).unwrap_or(200)));
            let mut stmt = conn.prepare(&sql)?;
            let rows = stmt.query_map(params_from_iter(binds.iter()), |row| {
                Ok(AuditEvent {
                    id: row.get(0)?,
                    at: row.get(1)?,
                    op: row.get(2)?,
                    workspace: row.get(3)?,
                    project: row.get(4)?,
                    page_path: row.get(5)?,
                    author_username: row.get(6)?,
                    detail: row.get(7)?,
                })
            })?;
            let mut out = Vec::new();
            for row in rows {
                out.push(row?);
            }
            Ok(out)
        })
        .await
    }

    /// Return aggregate counts for the `status` view.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn status_counts(&self) -> StoreResult<StatusCounts> {
        self.with_conn(|conn| {
            let pages_latest: u64 = count(conn, "SELECT COUNT(*) FROM pages WHERE is_latest = 1")?;
            let pages_all: u64 = count(conn, "SELECT COUNT(*) FROM pages")?;
            let sessions: u64 = count(conn, "SELECT COUNT(*) FROM sessions")?;
            let observations: u64 = count(conn, "SELECT COUNT(*) FROM observations")?;
            let evidence_rows: u64 = count(conn, "SELECT COUNT(*) FROM page_evidence")?;
            Ok(StatusCounts {
                pages_latest,
                pages_all,
                sessions,
                observations,
                evidence_rows,
            })
        })
        .await
    }

    /// Server-wide [`SessionConsolidationQueue`] state.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn session_consolidation_queue(&self) -> StoreResult<SessionConsolidationQueue> {
        self.with_conn(|conn| {
            let mut queue = SessionConsolidationQueue::default();
            let mut stmt = conn
                .prepare("SELECT state, COUNT(*) FROM session_consolidation_jobs GROUP BY state")?;
            let rows = stmt.query_map([], |row| {
                Ok((row.get::<_, String>(0)?, row.get::<_, i64>(1)?))
            })?;
            for row in rows {
                let (state, n) = row?;
                let n = u64::try_from(n).unwrap_or(0);
                match state.as_str() {
                    "pending" => queue.pending = n,
                    "running" => queue.running = n,
                    "completed" => queue.completed = n,
                    "failed" => queue.failed = n,
                    _ => {}
                }
            }
            queue.last_completed_at_us = conn.query_row(
                "SELECT MAX(completed_at) FROM session_consolidation_jobs \
                 WHERE state = 'completed'",
                [],
                |row| row.get(0),
            )?;
            queue.oldest_pending_requested_at_us = conn.query_row(
                "SELECT MIN(requested_at) FROM session_consolidation_jobs \
                 WHERE state = 'pending'",
                [],
                |row| row.get(0),
            )?;
            Ok(queue)
        })
        .await
    }

    /// The most recent consolidation jobs that gave up, newest first,
    /// bounded to `limit`.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn failed_consolidation_jobs(
        &self,
        limit: u32,
    ) -> StoreResult<Vec<FailedConsolidationJob>> {
        let limit = i64::from(limit.clamp(1, 100));
        self.with_conn(move |conn| {
            let mut stmt = conn.prepare_cached(
                "SELECT session_id, attempts, COALESCE(completed_at, 0), \
                        COALESCE(last_error, '') \
                 FROM session_consolidation_jobs WHERE state = 'failed' \
                 ORDER BY COALESCE(completed_at, 0) DESC LIMIT ?1",
            )?;
            let rows = stmt.query_map([limit], |row| {
                Ok((
                    row.get::<_, Vec<u8>>(0)?,
                    row.get::<_, i64>(1)?,
                    row.get::<_, i64>(2)?,
                    row.get::<_, String>(3)?,
                ))
            })?;
            let mut out = Vec::new();
            for row in rows {
                let (session, attempts, failed_at_us, last_error) = row?;
                let Ok(session_id) = ai_memory_core::SessionId::from_slice(&session) else {
                    continue;
                };
                out.push(FailedConsolidationJob {
                    session_id: session_id.to_string(),
                    attempts: u32::try_from(attempts).unwrap_or(0),
                    failed_at_us,
                    last_error,
                });
            }
            Ok(out)
        })
        .await
    }

    /// Count the records of one project, for a destructive operation's
    /// preflight (#1713).
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn project_record_counts(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> StoreResult<ProjectRecordCounts> {
        self.with_conn(move |conn| {
            let count = |sql: &str| -> StoreResult<u64> {
                let n: i64 = conn.query_row(
                    sql,
                    params![workspace_id.as_bytes(), project_id.as_bytes()],
                    |row| row.get(0),
                )?;
                Ok(u64::try_from(n).unwrap_or(0))
            };
            Ok(ProjectRecordCounts {
                pages: count(
                    "SELECT COUNT(*) FROM pages WHERE workspace_id = ?1 AND project_id = ?2 \
                     AND is_latest = 1",
                )?,
                sessions: count(
                    "SELECT COUNT(*) FROM sessions WHERE workspace_id = ?1 AND project_id = ?2",
                )?,
                observations: count(
                    "SELECT COUNT(*) FROM observations WHERE workspace_id = ?1 AND project_id = ?2",
                )?,
                handoffs: count(
                    "SELECT COUNT(*) FROM handoffs WHERE workspace_id = ?1 AND project_id = ?2",
                )?,
            })
        })
        .await
    }

    /// Physical storage figures for the database file.
    ///
    /// Three `PRAGMA` reads, no table scan, so it is cheap enough to sit in
    /// `status` next to the row counts.
    ///
    /// # Errors
    /// Propagates the SQL error from the pragma reads.
    pub async fn storage_status(&self) -> StoreResult<StorageStatus> {
        // The database's own dir may not exist as a distinct mount point
        // (it usually doesn't), but `available_space` walks up to whatever
        // filesystem holds it either way. A read failure (unsupported
        // filesystem, transient error) is a signal we don't have, not a
        // reason to fail the whole status report.
        let data_dir_free_bytes = self
            .inner
            .db_path
            .parent()
            .and_then(|dir| fs2::available_space(dir).ok());
        self.with_conn(move |conn| {
            let page_size: i64 = conn.query_row("PRAGMA page_size", [], |r| r.get(0))?;
            let page_count: i64 = conn.query_row("PRAGMA page_count", [], |r| r.get(0))?;
            let freelist_count: i64 = conn.query_row("PRAGMA freelist_count", [], |r| r.get(0))?;
            let page_size = u64::try_from(page_size.max(0)).unwrap_or(0);
            let page_count = u64::try_from(page_count.max(0)).unwrap_or(0);
            let freelist_count = u64::try_from(freelist_count.max(0)).unwrap_or(0);
            Ok(StorageStatus {
                page_size,
                page_count,
                freelist_count,
                database_bytes: page_count.saturating_mul(page_size),
                reclaimable_bytes: freelist_count.saturating_mul(page_size),
                data_dir_free_bytes,
            })
        })
        .await
    }

    /// Return health counters for derived indexes and link/embedding state.
    ///
    /// "Missing" keeps its historical meaning here: a latest page has no
    /// vector at all. Server health surfaces with a configured embedder use
    /// [`Self::derived_index_status_for_embedding`] so vectors from an old
    /// model do not hide the current backfill gap.
    ///
    /// These checks are intentionally read-only and derived-index-safe: they
    /// report drift but do not repair it. Rebuild/backfill paths stay behind
    /// explicit admin operations.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn derived_index_status(&self) -> StoreResult<DerivedIndexStatus> {
        self.derived_index_status_inner(None).await
    }

    /// Return derived-index health while judging embedding coverage against
    /// the configured `(provider, model, dim)` identity.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn derived_index_status_for_embedding(
        &self,
        configured_embedding: (String, String, u32),
    ) -> StoreResult<DerivedIndexStatus> {
        self.derived_index_status_inner(Some(configured_embedding))
            .await
    }

    async fn derived_index_status_inner(
        &self,
        configured_embedding: Option<(String, String, u32)>,
    ) -> StoreResult<DerivedIndexStatus> {
        self.with_conn(move |conn| {
            let mut triples_stmt = conn.prepare(
                "SELECT provider, model, dim, COUNT(*) \
                 FROM page_embeddings \
                 GROUP BY provider, model, dim \
                 ORDER BY COUNT(*) DESC, provider, model, dim",
            )?;
            let embedding_triples = triples_stmt
                .query_map([], |row| {
                    let provider: String = row.get(0)?;
                    let model: String = row.get(1)?;
                    let dim: i64 = row.get(2)?;
                    let count: i64 = row.get(3)?;
                    Ok(EmbeddingTripleCount {
                        provider,
                        model,
                        dim: u32::try_from(dim.max(0)).unwrap_or(0),
                        count: u64::try_from(count.max(0)).unwrap_or(0),
                    })
                })?
                .collect::<Result<Vec<_>, _>>()?;

            Ok(DerivedIndexStatus {
                pages_rows: count(conn, "SELECT COUNT(*) FROM pages")?,
                // `pages_fts` is an external-content FTS5 table, so
                // `COUNT(*)` on it is answered from `pages` and can never
                // diverge. The `_docsize` shadow table holds one row per
                // indexed document, which is what makes this pair a drift
                // check rather than a tautology. Same for `observations_fts`.
                pages_fts_rows: count(conn, "SELECT COUNT(*) FROM pages_fts_docsize")?,
                observations_rows: count(conn, "SELECT COUNT(*) FROM observations")?,
                observations_fts_rows: count(
                    conn,
                    "SELECT COUNT(*) FROM observations_fts_docsize",
                )?,
                // Split by whether an embedding exists *now*: a failure row is
                // the last unsuccessful attempt, not proof the page is still
                // broken. Without this join a page that failed once and
                // recovered would read as an outstanding problem forever.
                embed_failures_unresolved: count(
                    conn,
                    "SELECT COUNT(*) \
                     FROM page_embed_failures f \
                     JOIN pages pg ON pg.id = f.page_id AND pg.is_latest = 1 \
                     LEFT JOIN page_embeddings pe ON pe.page_id = f.page_id \
                     WHERE pe.page_id IS NULL",
                )?,
                embed_failures_recovered: count(
                    conn,
                    "SELECT COUNT(*) \
                     FROM page_embed_failures f \
                     JOIN pages pg ON pg.id = f.page_id AND pg.is_latest = 1 \
                     JOIN page_embeddings pe ON pe.page_id = f.page_id",
                )?,
                // Aligned with the backfill's own skip rule: an
                // empty-body page can never be embedded, so counting it
                // as \"missing\" overstated the actionable number forever
                // (observed live: a stable 427 that no backfill could
                // ever clear). Unembeddable pages are reported apart.
                // With a configured triple, "has a vector" means "has a
                // vector the current model would produce": a row stored
                // under an old triple is stale, and without the triple the
                // count would read zero after every model switch.
                latest_pages_missing_embeddings: match configured_embedding {
                    Some((provider, model, dim)) => {
                        let provider = provider.as_str();
                        let model = model.as_str();
                        let dim = i64::from(dim);
                        count_bound(
                            conn,
                            "SELECT COUNT(*) \
                             FROM pages pg \
                             WHERE pg.is_latest = 1 AND TRIM(pg.body) != '' \
                               AND NOT EXISTS ( \
                                   SELECT 1 FROM page_embeddings pe \
                                   WHERE pe.page_id = pg.id \
                                     AND pe.provider = ?1 \
                                     AND pe.model = ?2 \
                                     AND pe.dim = ?3)",
                            &[&provider, &model, &dim],
                        )
                    }
                    None => count(
                        conn,
                        "SELECT COUNT(*) \
                         FROM pages pg \
                         LEFT JOIN page_embeddings pe ON pe.page_id = pg.id \
                         WHERE pg.is_latest = 1 AND pe.page_id IS NULL \
                           AND TRIM(pg.body) != ''",
                    ),
                }?,
                latest_pages_unembeddable: count(
                    conn,
                    "SELECT COUNT(*) \
                     FROM pages pg \
                     LEFT JOIN page_embeddings pe ON pe.page_id = pg.id \
                     WHERE pg.is_latest = 1 AND pe.page_id IS NULL \
                       AND TRIM(pg.body) = ''",
                )?,
                embedding_rows: count(conn, "SELECT COUNT(*) FROM page_embeddings")?,
                embedding_triples,
                typed_links_from_latest_pages: {
                    let mut stmt = conn.prepare(
                        "SELECT l.link_type, COUNT(*) FROM links l \
                         JOIN pages fp ON fp.id = l.from_page_id AND fp.is_latest = 1 \
                         WHERE l.link_type != 'references' \
                         GROUP BY l.link_type ORDER BY l.link_type",
                    )?;
                    let rows: Vec<(String, i64)> = stmt
                        .query_map([], |row| Ok((row.get(0)?, row.get(1)?)))?
                        .collect::<Result<_, _>>()?;
                    rows.into_iter()
                        .map(|(k, v)| (k, u64::try_from(v).unwrap_or(0)))
                        .collect()
                },
                links_from_latest_pages: count(
                    conn,
                    "SELECT COUNT(*) \
                     FROM links l \
                     JOIN pages fp ON fp.id = l.from_page_id \
                     WHERE fp.is_latest = 1",
                )?,
                unresolved_links_from_latest_pages: count(
                    conn,
                    "SELECT COUNT(*) \
                     FROM links l \
                     JOIN pages fp ON fp.id = l.from_page_id \
                     WHERE fp.is_latest = 1 AND l.to_page_id IS NULL",
                )?,
                stale_links_from_latest_pages: count(
                    conn,
                    "SELECT COUNT(*) \
                     FROM links l \
                     JOIN pages fp ON fp.id = l.from_page_id \
                     LEFT JOIN pages tp ON tp.id = l.to_page_id \
                     WHERE fp.is_latest = 1 \
                       AND l.to_page_id IS NOT NULL \
                       AND COALESCE(tp.is_latest, 0) != 1",
                )?,
            })
        })
        .await
    }

    /// Return aggregate counts scoped to one project.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn status_counts_for_project(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> StoreResult<StatusCounts> {
        self.with_conn(move |conn| {
            let pages_latest = count_project(
                conn,
                "SELECT COUNT(*) FROM pages WHERE workspace_id = ?1 AND project_id = ?2 AND is_latest = 1",
                workspace_id,
                project_id,
            )?;
            let pages_all = count_project(
                conn,
                "SELECT COUNT(*) FROM pages WHERE workspace_id = ?1 AND project_id = ?2",
                workspace_id,
                project_id,
            )?;
            let sessions = count_project(
                conn,
                "SELECT COUNT(*) FROM sessions WHERE workspace_id = ?1 AND project_id = ?2",
                workspace_id,
                project_id,
            )?;
            let observations = count_project(
                conn,
                "SELECT COUNT(*) FROM observations WHERE workspace_id = ?1 AND project_id = ?2",
                workspace_id,
                project_id,
            )?;
            // page_evidence carries no scope columns of its own; join through
            // pages to keep the count per-project (3-tuple identity, #4).
            let evidence_rows = count_project(
                conn,
                "SELECT COUNT(*) FROM page_evidence pe \
                 JOIN pages p ON p.id = pe.page_id \
                 WHERE p.workspace_id = ?1 AND p.project_id = ?2",
                workspace_id,
                project_id,
            )?;
            Ok(StatusCounts {
                pages_latest,
                pages_all,
                sessions,
                observations,
                evidence_rows,
            })
        })
        .await
    }

    /// Return all migration names recorded in the `wiki_migrations` table.
    ///
    /// Used by the wiki migration runner to determine which migrations have
    /// already been applied to this data directory.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn wiki_migration_names(&self) -> StoreResult<Vec<String>> {
        self.with_conn(|conn| {
            let mut stmt = conn.prepare("SELECT name FROM wiki_migrations ORDER BY name")?;
            let names = stmt
                .query_map([], |row| row.get::<_, String>(0))?
                .collect::<Result<Vec<_>, _>>()?;
            Ok(names)
        })
        .await
    }

    // ── user lookups ────────────────────────────────────────────────

    /// Hot path for Bearer auth: native `api_credentials` where
    /// `revoked_at IS NULL`. Does not filter `users.disabled_at`.
    /// Always authenticates as [`ai_memory_core::AuthLevel::User`].
    ///
    /// # Errors
    /// Propagates any SQL or pool error. Returns `Ok(None)` when no
    /// active credential matches.
    pub async fn find_active_user_by_token_hash(
        &self,
        token_hash: [u8; TOKEN_HASH_LEN],
    ) -> StoreResult<Option<crate::AuthenticatedApiUser>> {
        let now = now_us();
        self.with_conn(move |conn| {
            crate::api_credentials::find_active_user_by_token_hash(conn, &token_hash, now)
        })
        .await
    }

    /// Look up a user by exact-match username. Used by admin endpoints
    /// that accept username on the wire.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn find_user_by_username(&self, username: String) -> StoreResult<Option<User>> {
        self.with_conn(move |conn| crate::users::find_user_by_username(conn, &username))
            .await
    }

    /// Login lookup including the stored Argon2id PHC.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn find_login_user_by_username(
        &self,
        username: String,
    ) -> StoreResult<Option<crate::LoginUser>> {
        self.with_conn(move |conn| crate::users::find_login_user_by_username(conn, &username))
            .await
    }

    /// Live (unrevoked, unexpired) web session by secret hash.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn find_live_session_by_hash(
        &self,
        session_hash: [u8; TOKEN_HASH_LEN],
    ) -> StoreResult<Option<crate::LiveWebSession>> {
        let now = now_us();
        self.with_conn(move |conn| {
            crate::web_sessions::find_live_session_by_hash(conn, &session_hash, now)
        })
        .await
    }

    /// Look up a user by id, including disabled and password-less rows.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn find_user_by_id(&self, id: UserId) -> StoreResult<Option<User>> {
        self.with_conn(move |conn| crate::users::find_user_by_id(conn, id))
            .await
    }

    /// All registered users, ordered by `created_at` ascending.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn list_users(&self) -> StoreResult<Vec<User>> {
        self.with_conn(crate::users::list_users).await
    }

    /// Whether bootstrap has been marked complete.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn bootstrap_completed(&self) -> StoreResult<bool> {
        self.with_conn(crate::users::bootstrap_completed).await
    }

    /// Whether any user has a password hash.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn any_password_hash(&self) -> StoreResult<bool> {
        self.with_conn(crate::users::any_password_hash).await
    }

    /// Recoverable-root count for startup validation.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn count_recoverable_roots(&self) -> StoreResult<i64> {
        self.with_conn(crate::users::count_recoverable_roots).await
    }

    /// Whether any native API credential exists (pepper required).
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn api_credentials_exist(&self) -> StoreResult<bool> {
        self.with_conn(crate::api_credentials::api_credentials_exist)
            .await
    }

    /// Argon2id verifier for the pepper that hashes native API credentials.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn api_credential_pepper_verifier(&self) -> StoreResult<Option<String>> {
        self.with_conn(crate::api_credentials::api_credential_pepper_verifier)
            .await
    }

    /// True when any credential (active or revoked) stores this hash.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn token_hash_exists(&self, token_hash: [u8; TOKEN_HASH_LEN]) -> StoreResult<bool> {
        self.with_conn(move |conn| crate::api_credentials::token_hash_exists(conn, &token_hash))
            .await
    }

    /// List native API credentials, newest first.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn list_api_credentials(&self) -> StoreResult<Vec<ai_memory_core::ApiCredential>> {
        self.with_conn(crate::api_credentials::list_api_credentials)
            .await
    }

    /// List credentials for one user.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn list_api_credentials_for_user(
        &self,
        user_id: UserId,
    ) -> StoreResult<Vec<ai_memory_core::ApiCredential>> {
        self.with_conn(move |conn| {
            crate::api_credentials::list_api_credentials_for_user(conn, user_id)
        })
        .await
    }

    /// Look up one credential by id.
    ///
    /// # Errors
    /// Propagates any SQL or pool error.
    pub async fn find_api_credential(
        &self,
        id: ai_memory_core::ApiCredentialId,
    ) -> StoreResult<Option<ai_memory_core::ApiCredential>> {
        self.with_conn(move |conn| crate::api_credentials::find_api_credential(conn, id))
            .await
    }

    /// Return whether any user row exists, including expired users. This cheap
    /// predicate is used at the admin authorization boundary to switch from
    /// bootstrap compatibility mode to root-only multi-user administration.
    ///
    /// # Errors
    /// Propagates any SQL or pool error so callers can fail closed.
    pub async fn users_exist(&self) -> StoreResult<bool> {
        self.with_conn(crate::users::users_exist).await
    }

    /// Does this deployment tell its operators apart?
    ///
    /// Two independent routes produce distinct operators: rows in `users`, and
    /// usernames asserted by a trusted authenticating proxy. Only the first is
    /// visible from the store, so the caller passes the second in — a
    /// proxy-only deployment reports `users_exist() == false` forever.
    ///
    /// One notion, several gates: the admin authorization boundaries and the
    /// per-author bucketing of pending auto-improve proposals all key on this,
    /// so a single-operator server keeps the exact behaviour it had before
    /// either route existed.
    ///
    /// # Errors
    /// Propagates any SQL or pool error so callers can fail closed.
    pub async fn distinguishes_operators(&self, trusted_proxy_identity: bool) -> StoreResult<bool> {
        // Short-circuits the DB round-trip when the static config bit already
        // settles it. The users table is otherwise consulted per call rather
        // than cached, so committing a first user tightens access without a
        // restart.
        if trusted_proxy_identity {
            return Ok(true);
        }
        self.users_exist().await
    }

    /// The `[profile]` flags stored on a project (both on when it has none).
    ///
    /// # Errors
    /// Propagates SQL or pool errors.
    pub async fn project_profile_flags(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> StoreResult<crate::ProjectProfileFlags> {
        self.with_conn(move |conn| {
            crate::profile::project_profile_flags(conn, workspace_id, project_id)
        })
        .await
    }

    /// Projects whose marker keeps them out of the profile.
    ///
    /// # Errors
    /// Propagates SQL or pool errors.
    pub async fn profile_contribute_opt_outs(&self) -> StoreResult<Vec<crate::ProfileOptOut>> {
        self.with_conn(crate::profile::contribute_opt_outs).await
    }

    /// The current entries of a profile scope, at most `limit`
    /// ([`crate::PROFILE_ENTRIES_LIMIT`] caps it).
    ///
    /// # Errors
    /// Propagates SQL or pool errors.
    pub async fn profile_entries(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        limit: usize,
    ) -> StoreResult<Vec<ai_memory_core::profile::ProfileEntry>> {
        self.with_conn(move |conn| {
            crate::profile::profile_entries(conn, workspace_id, project_id, limit)
        })
        .await
    }

    /// Every project the profile harvester may read, with its marks.
    ///
    /// # Errors
    /// Propagates SQL or pool errors.
    pub async fn profile_harvest_projects(&self) -> StoreResult<Vec<crate::ProfileHarvestProject>> {
        self.with_conn(crate::profile::profile_harvest_projects)
            .await
    }

    /// What the harvester reads next from one project: user prompts and
    /// curated pages past its marks, at most `limit` of each.
    ///
    /// # Errors
    /// Propagates SQL or pool errors.
    pub async fn profile_harvest_inputs(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        mark: crate::ProfileHarvestMark,
        limit: usize,
    ) -> StoreResult<(
        Vec<crate::ProfilePromptRow>,
        Vec<crate::ProfilePageRow>,
        std::collections::BTreeSet<String>,
    )> {
        self.with_conn(move |conn| {
            Ok((
                crate::profile::profile_prompts_since(
                    conn,
                    workspace_id,
                    project_id,
                    mark.observations_until,
                    limit,
                )?,
                crate::profile::profile_pages_since(
                    conn,
                    workspace_id,
                    project_id,
                    mark.pages_until,
                    limit,
                )?,
                crate::profile::project_stack_tags(conn, workspace_id, project_id)?,
            ))
        })
        .await
    }

    /// The decider agent of each given auto-improve proposal in a scope,
    /// keyed by proposal id; a proposal with no row is absent (#1211).
    ///
    /// # Errors
    /// Propagates SQL or pool errors.
    pub async fn auto_improve_decided_by(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        proposal_ids: Vec<AutoImproveProposalId>,
    ) -> StoreResult<std::collections::HashMap<AutoImproveProposalId, Option<String>>> {
        self.with_conn(move |conn| {
            crate::profile::auto_improve_decided_by(conn, workspace_id, project_id, &proposal_ids)
        })
        .await
    }

    /// The newest recorded profile candidates of contributing projects.
    ///
    /// # Errors
    /// Propagates SQL or pool errors.
    pub async fn profile_candidates(
        &self,
        limit: usize,
    ) -> StoreResult<Vec<crate::ProfileCandidateRow>> {
        self.with_conn(move |conn| crate::profile::profile_candidates(conn, limit))
            .await
    }

    /// Every current `profile/` page of a scope, raw, and the harvester's
    /// ledger of the entries it wrote there, from one connection checkout.
    ///
    /// # Errors
    /// Propagates SQL or pool errors.
    pub async fn profile_scope_pages(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> StoreResult<(Vec<crate::ProfileScopePage>, Vec<crate::ProfileLedgerEntry>)> {
        self.with_conn(move |conn| {
            Ok((
                crate::profile::profile_scope_pages(conn, workspace_id, project_id)?,
                crate::profile::profile_entry_ledger(conn, workspace_id, project_id)?,
            ))
        })
        .await
    }

    /// The digest inputs for a session in `project` reading the profile held
    /// in `profile_scope`, from one connection checkout.
    ///
    /// # Errors
    /// Propagates SQL or pool errors.
    pub async fn profile_digest_inputs(
        &self,
        profile_scope: (WorkspaceId, ProjectId),
        project: (WorkspaceId, ProjectId),
    ) -> StoreResult<crate::ProfileDigestInputs> {
        self.with_conn(move |conn| {
            Ok(crate::ProfileDigestInputs {
                entries: crate::profile::profile_entries(
                    conn,
                    profile_scope.0,
                    profile_scope.1,
                    crate::PROFILE_ENTRIES_LIMIT,
                )?,
                project_tags: crate::profile::project_stack_tags(conn, project.0, project.1)?,
                project_has_pages: crate::profile::project_has_pages(conn, project.0, project.1)?,
            })
        })
        .await
    }

    /// Return the last successful global maintenance completion for `job`.
    pub async fn maintenance_job_last_success(
        &self,
        job: MaintenanceJob,
    ) -> StoreResult<Option<i64>> {
        self.with_conn(move |conn| crate::maintenance::last_success(conn, job))
            .await
    }

    /// Resolve the per-project authorization state (#708) from the read pool.
    ///
    /// An `open` project short-circuits without a grant lookup. Store failures
    /// while resolving an existing restricted project propagate so callers
    /// fail closed. See [`crate::project_authz`].
    pub async fn resolve_project_authz(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        principal: crate::ProjectPrincipal,
        distinguishes_operators: bool,
    ) -> StoreResult<crate::ProjectAuthz> {
        self.with_conn(move |conn| {
            crate::project_authz::resolve_project_authz(
                conn,
                workspace_id,
                project_id,
                &principal,
                distinguishes_operators,
            )
        })
        .await
    }

    /// The per-project authorization choke point (#708), evaluated on the read
    /// pool: resolve the project's access state and decide `need`.
    ///
    /// Returns `Ok(Ok(()))` when the caller is admitted, `Ok(Err(Forbidden))`
    /// when a restricted project refuses them, and `Err(_)` only on an
    /// infrastructure failure.
    pub async fn authorize_project(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        principal: crate::ProjectPrincipal,
        distinguishes_operators: bool,
        need: crate::ProjectAccess,
    ) -> StoreResult<Result<(), ai_memory_core::AuthzError>> {
        let ctx = self
            .resolve_project_authz(workspace_id, project_id, principal, distinguishes_operators)
            .await?;
        Ok(ctx.authorize(need))
    }
}

/// Build the per-agent session count query for one scope.
///
/// The capture probe keeps its workspace/project predicates because one
/// session id can carry observations in several projects, and only the
/// counted project's rows may decide whether a session mixed capture paths.
/// Those same predicates match the leading columns of
/// `idx_observations_project_created`, and without `sqlite_stat1` the planner
/// prefers that two-column equality over the one-column session index. It
/// then rescans the whole project's observations once per session: 144 s for
/// 780 sessions over 185k observations, against 0.3 s through the session
/// index. `INDEXED BY` pins the probe to the index that bounds it by session
/// whatever the statistics say.
fn session_counts_by_agent_sql(has_since: bool, owner_filter: &OwnerFilter) -> String {
    // Same reasoning as `open_sessions_for_scope_agent`: without the owner
    // predicate a shared server reports a teammate's activity as the
    // caller's own.
    let owner_clause = match owner_filter {
        OwnerFilter::Any => "",
        OwnerFilter::User(_) => " AND (actor_user IS NULL OR actor_user = :actor)",
        OwnerFilter::Unattributed => " AND actor_user IS NULL",
    };
    let since_clause = if has_since {
        " AND started_at >= :since"
    } else {
        ""
    };
    format!(
        "SELECT agent_kind, COUNT(*) AS n, \
         SUM((SELECT COUNT(DISTINCT CASE WHEN o.extension IS NULL \
             THEN 'native' ELSE 'extension:' || o.extension END) \
             FROM observations o INDEXED BY idx_observations_session \
             WHERE o.session_id = sessions.id \
               AND o.workspace_id = :ws AND o.project_id = :proj) > 1) \
         FROM sessions \
         WHERE workspace_id = :ws AND project_id = :proj\
         {since_clause}{owner_clause} \
         GROUP BY agent_kind \
         ORDER BY n DESC, agent_kind ASC"
    )
}

/// SQL for [`ReaderPool::latest_interrupted_session_candidate`].
///
/// Every eligibility test is a fact about one session: its newest
/// substantive work, whether that work outlived the recorded end, and
/// whether a handoff from the session covers it. The materialized
/// `candidates` set answers them once per session in the scope. Joining
/// sessions to their observations, as this query once did, re-ran the
/// per-session subqueries for every observation row, and without
/// `sqlite_stat1` the planner answered each of them from
/// `idx_observations_project_created`, so every row rescanned the project and
/// `GET /handoff` on a large project never returned (#1879, the shape of
/// #1257). `INDEXED BY` bounds each probe to one session. `handoffs` has no
/// index on its source session, so the scope's handoffs are reduced to the
/// newest per source session in one pass instead of being searched once per
/// session. Only a handoff at or after a session's newest work can cover it,
/// so that pass starts at the oldest such work among the sessions still
/// eligible; unbounded, it sorted the project's whole handoff history on
/// every call.
fn latest_interrupted_session_candidate_sql(
    owner_filter: &OwnerFilter,
    has_receiver: bool,
) -> String {
    let owner_clause = match owner_filter {
        OwnerFilter::Any => "",
        OwnerFilter::User(_) => " AND (s.actor_user IS NULL OR s.actor_user = :actor)",
        OwnerFilter::Unattributed => " AND s.actor_user IS NULL",
    };
    let receiver_clause = if has_receiver {
        " AND s.id != :receiver"
    } else {
        ""
    };
    format!(
        "WITH candidates AS MATERIALIZED ( \
           SELECT s.id, s.agent_kind, s.started_at, s.ended_at, s.cwd, \
                  (SELECT MAX(o.created_at) \
                   FROM observations o INDEXED BY idx_observations_session \
                   WHERE o.session_id = s.id \
                     AND o.workspace_id = :ws AND o.project_id = :proj) AS last_activity, \
                  (SELECT MAX(work.created_at) \
                   FROM observations work INDEXED BY idx_observations_session \
                   WHERE work.session_id = s.id \
                     AND work.workspace_id = :ws AND work.project_id = :proj \
                     AND work.kind IN ('user-prompt','pre-tool-use','post-tool-use')) AS last_work \
           FROM sessions s \
           WHERE s.workspace_id = :ws AND s.project_id = :proj{owner_clause}{receiver_clause} \
         ), covered AS ( \
           SELECT from_session_id, MAX(created_at) AS last_handoff \
           FROM handoffs \
           WHERE workspace_id = :ws AND project_id = :proj AND from_session_id IS NOT NULL \
             AND created_at >= (SELECT MIN(last_work) FROM candidates \
                                WHERE ended_at IS NULL OR last_work > ended_at) \
           GROUP BY from_session_id \
         ) \
         SELECT c.id, c.agent_kind, c.last_activity, c.cwd \
         FROM candidates c \
         LEFT JOIN covered h ON h.from_session_id = c.id \
         WHERE c.last_work IS NOT NULL \
           AND (c.ended_at IS NULL OR c.last_work > c.ended_at) \
           AND (h.last_handoff IS NULL OR h.last_handoff < c.last_work) \
         ORDER BY c.last_activity DESC, c.started_at DESC, c.id DESC \
         LIMIT 1"
    )
}

/// Build the scoped session listing query (or its point lookup).
///
/// The per-session observation count and the point lookup's membership
/// probe filter observations by session, workspace and project, the same
/// shape as the by-agent capture probe in
/// [`session_counts_by_agent_sql`]: without `sqlite_stat1` the planner
/// answers them from `idx_observations_project_created` and rescans the
/// project once per listed session. `INDEXED BY` pins both to the session
/// index.
fn sessions_for_scope_sql(
    exact_session: bool,
    owner_filter: &OwnerFilter,
    include_open: bool,
) -> String {
    // The point lookup lets the primary key narrow first so the scope
    // test is one indexed probe; the listing materializes the scope's
    // session ids once instead of probing every session in the table.
    let membership = if exact_session {
        " AND s.id = :sid \
          AND ((s.workspace_id = :ws AND s.project_id = :proj) \
               OR EXISTS (SELECT 1 FROM observations o INDEXED BY idx_observations_session \
                          WHERE o.session_id = s.id \
                            AND o.workspace_id = :ws AND o.project_id = :proj))"
    } else {
        " AND s.id IN (SELECT id FROM sessions \
                       WHERE workspace_id = :ws AND project_id = :proj \
                       UNION \
                       SELECT session_id FROM observations \
                       WHERE workspace_id = :ws AND project_id = :proj)"
    };
    let owner_clause = match owner_filter {
        OwnerFilter::Any => "",
        OwnerFilter::User(_) => " AND (s.actor_user IS NULL OR s.actor_user = :actor)",
        OwnerFilter::Unattributed => " AND s.actor_user IS NULL",
    };
    // Keep the persisted end as the writer's finalization watermark. New
    // substantive work in this scope reopens only the read view, matching
    // recent_session_activity without changing lifecycle or handoff admission.
    let effective_end = "CASE WHEN EXISTS (\
        SELECT 1 FROM observations resumed INDEXED BY idx_observations_session \
        WHERE resumed.session_id = s.id \
          AND resumed.workspace_id = :ws AND resumed.project_id = :proj \
          AND resumed.created_at > s.ended_at \
          AND resumed.kind NOT IN ('session-start', 'session-end')\
        ) THEN NULL ELSE s.ended_at END";
    let ended_clause = if include_open {
        String::new()
    } else {
        format!(" AND ({effective_end}) IS NOT NULL")
    };
    format!(
        "SELECT s.id, s.cwd, s.agent_kind, s.started_at, {effective_end} AS ended_at, s.actor_user, \
                (SELECT COUNT(*) FROM observations o INDEXED BY idx_observations_session \
                 WHERE o.session_id = s.id \
                   AND o.workspace_id = :ws AND o.project_id = :proj) AS n, \
                u.input_tokens, u.output_tokens, u.cache_write_tokens, u.cache_read_tokens, u.model, \
                j.state, j.attempts \
         FROM sessions s \
         LEFT JOIN session_usage u ON u.session_id = s.id \
         LEFT JOIN session_consolidation_jobs j ON j.session_id = s.id \
           AND j.workspace_id = :ws AND j.project_id = :proj \
           AND j.generation = (SELECT MAX(latest.generation) \
             FROM session_consolidation_jobs latest WHERE latest.session_id = s.id \
               AND latest.workspace_id = :ws AND latest.project_id = :proj) \
         WHERE 1 = 1{membership}{owner_clause}{ended_clause} \
         ORDER BY s.started_at DESC, s.id DESC \
         LIMIT :limit OFFSET :offset"
    )
}

/// Build the bounded history query and its optional owner binding.
///
/// A named operator reads two disjoint ranges: shared (`NULL`) and their own
/// owner key. Expressing those ranges as `OR` makes SQLite prefer the
/// project-wide timestamp index to satisfy `ORDER BY`, scanning other users'
/// history until it finds enough visible rows. `UNION ALL` lets SQLite merge
/// two already ordered owner-index ranges and stop at the requested limit.
fn handoff_listing_sql(
    has_state: bool,
    owner_filter: &OwnerFilter,
    limit: usize,
) -> (String, Option<String>) {
    const SELECT: &str = "SELECT id, workspace_id, project_id, from_session_id, from_agent, to_agent, \
                cwd, summary, open_questions, next_steps, files_touched, state, \
                created_at, accepted_by, accepted_at, accepted_by_session, \
                owner_user, accepted_by_user \
         FROM handoffs";
    let state_clause = if has_state { " AND state = ?3" } else { "" };
    let owner_index = if has_state { 4 } else { 3 };
    let sql_limit = limit.clamp(1, 500);
    match owner_filter {
        OwnerFilter::User(owner) => (
            format!(
                "{SELECT} \
                 WHERE workspace_id = ?1 AND project_id = ?2{state_clause} \
                   AND owner_user IS NULL \
                 UNION ALL \
                 {SELECT} \
                 WHERE workspace_id = ?1 AND project_id = ?2{state_clause} \
                   AND owner_user = ?{owner_index} \
                 ORDER BY created_at DESC \
                 LIMIT {sql_limit}"
            ),
            Some(owner.clone()),
        ),
        _ => {
            let (owner_clause, owner_param) = handoff_owner_sql(owner_filter, owner_index);
            (
                format!(
                    "{SELECT} \
                     WHERE workspace_id = ?1 AND project_id = ?2{state_clause}{owner_clause} \
                     ORDER BY created_at DESC \
                     LIMIT {sql_limit}"
                ),
                owner_param,
            )
        }
    }
}

/// Map a `(workspace, project, path, title, kind)` row to a [`HealthPage`].
fn health_page_from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<HealthPage> {
    Ok(HealthPage {
        workspace: row.get(0)?,
        project: row.get(1)?,
        path: row.get(2)?,
        title: row.get(3)?,
        kind: row.get(4)?,
    })
}

/// SQL for [`PageMeta::created_at`]: when the page itself first appeared.
///
/// `pages.created_at` is per version, so the latest row alone would report the
/// last rewrite. The page's versions form its `supersedes` chain (a
/// tombstone-resurrected page is re-linked onto its old chain, #929), so the
/// oldest retained version is the minimum along that chain. Each step is a
/// primary-key lookup, so no index on `(path, created_at)` is needed and the
/// walk cannot reach a same-path page in another project. Versions removed by
/// retention or ledger reclaim end the chain early and no longer count.
const PAGE_FIRST_CREATED_EXPR: &str = "COALESCE(\
    (WITH RECURSIVE chain(supersedes, created_at, depth) AS (\
        SELECT pg.supersedes, pg.created_at, 0 \
        UNION ALL \
        SELECT v.supersedes, v.created_at, chain.depth + 1 \
          FROM pages v JOIN chain ON v.id = chain.supersedes \
         WHERE chain.depth < 100000) \
     SELECT MIN(created_at) FROM chain), \
    pg.created_at)";

fn page_meta_from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<StoreResult<PageMeta>> {
    let workspace_name: String = row.get(0)?;
    let project_name: String = row.get(1)?;
    let ws_id_bytes: Vec<u8> = row.get(2)?;
    let proj_id_bytes: Vec<u8> = row.get(3)?;
    let path: String = row.get(4)?;
    let title: String = row.get(5)?;
    let kind: String = row.get(6)?;
    let tier: String = row.get(7)?;
    let pinned: i64 = row.get(8)?;
    let created_us: i64 = row.get(9)?;
    let updated_us: i64 = row.get(10)?;
    let supersedes: Option<String> = row.get(11)?;
    // P1.7: author columns LEFT JOIN'd from `users`. NULL when the
    // page was written anonymously / by root, or when the user row
    // has been hard-deleted (FK `ON DELETE SET NULL`).
    let author_username: Option<String> = row.get(12)?;
    let author_name: Option<String> = row.get(13)?;
    let author_email: Option<String> = row.get(14)?;
    let expires_us: Option<i64> = row.get(15)?;
    let id_bytes: Vec<u8> = row.get(16)?;
    let author = author_username.map(|username| PageAuthor {
        username,
        name: author_name,
        email: author_email,
    });

    let workspace_id = WorkspaceId::from_slice(&ws_id_bytes)
        .map_err(|_| rusqlite::Error::IntegralValueOutOfRange(2, 0))?;
    let project_id = ProjectId::from_slice(&proj_id_bytes)
        .map_err(|_| rusqlite::Error::IntegralValueOutOfRange(3, 0))?;
    let id = PageId::from_slice(&id_bytes)
        .map_err(|_| rusqlite::Error::IntegralValueOutOfRange(16, 0))?;

    let created_at = jiff::Timestamp::from_microsecond(created_us)
        .map(|ts| ts.to_string())
        .unwrap_or_default();
    let updated_at = jiff::Timestamp::from_microsecond(updated_us)
        .map(|ts| ts.to_string())
        .unwrap_or_default();
    let expired = expires_us.is_some_and(|us| us <= now_us());
    let expires_at = expires_us
        .and_then(|us| jiff::Timestamp::from_microsecond(us).ok())
        .map(|ts| ts.to_string());

    Ok(Ok(PageMeta {
        id,
        workspace_name,
        project_name,
        workspace_id,
        project_id,
        path,
        title,
        kind,
        tier,
        pinned: pinned != 0,
        created_at,
        updated_at,
        supersedes,
        author,
        expires_at,
        expired,
    }))
}

/// The observations of one session, read through bounded queries inside one
/// read transaction (see [`ReaderPool::read_session_observations`]).
///
/// A session can hold hundreds of thousands of rows, and the SessionEnd path
/// only needs a handful of facts about them: counts, a few "last of a kind"
/// markers, the rows a page prints, and the first or last row that passes a
/// predicate. Every method here answers one of those needs with an aggregate,
/// a `LIMIT`ed query or a streamed scan that keeps one row resident, so the
/// memory a caller spends does not grow with the session. Every query orders
/// rows by `created_at` and then `rowid`, which is the order
/// [`ReaderPool::observations_for_session`] returns them in (the
/// `(session_id, created_at)` index carries the rowid as its last key).
pub struct SessionObservationSnapshot<'c> {
    conn: &'c Connection,
    session_id: Vec<u8>,
    rows_read: std::cell::Cell<usize>,
}

/// Counts and "last of a kind" markers for one session, from one aggregate
/// pass. A `*_at` field is the newest `created_at` of that kind (microseconds
/// since the epoch), which is enough to seek straight to the row with an
/// indexed `created_at <= ?` range instead of walking the session.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SessionKindSummary {
    /// Every row of the session.
    pub total: usize,
    /// User prompts.
    pub prompts: usize,
    /// At least one prompt or tool use: the positive "real work" predicate
    /// [`SUBSTANTIVE_OBSERVATION_KIND_SQL`] also gives the writer.
    pub substantive: bool,
    /// Newest `session-start`.
    pub last_session_start_at: Option<i64>,
    /// Newest `session-end`.
    pub last_session_end_at: Option<i64>,
    /// Newest `stop`.
    pub last_stop_at: Option<i64>,
    /// Newest `stop` whose body is not the empty string.
    pub last_stop_with_body_at: Option<i64>,
    /// Newest `post-tool-use`.
    pub last_post_tool_at: Option<i64>,
    /// Newest `user-prompt`.
    pub last_prompt_at: Option<i64>,
    /// `post-tool-use` rows whose header ends in [`FAILED_TOOL_OUTCOME_LINE`].
    pub failed_tool_calls: usize,
    /// Newest such row.
    pub last_failed_tool_at: Option<i64>,
}

/// The hooks crate's `is_failed_tool` in SQL: within the first
/// [`TOOL_BODY_HEADER_MAX_CHARS`] characters, the header is the text before
/// the first separator (`?7`) or all of it, and `substr(header, -len) = ?8`
/// is `ends_with(marker)`. An `outcome: error` line inside a tool's output
/// never counts, and no output excerpt is scanned.
fn failed_tool_sql() -> String {
    format!(
        "substr(CASE WHEN instr(substr(body, 1, {head}), ?7) > 0 \
                THEN substr(body, 1, instr(substr(body, 1, {head}), ?7) - 1) \
                ELSE substr(body, 1, {head}) END, -{len}) = ?8",
        head = TOOL_BODY_HEADER_MAX_CHARS,
        len = FAILED_TOOL_OUTCOME_LINE.len(),
    )
}

/// Row count and `created_at` span of one session's observations, in one
/// aggregate pass: what a bounded projection and a session duration need
/// before a single row is read.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ObservationProjectionTotals {
    /// Rows the session holds — every observation of it, regardless of the
    /// scope the consolidation target was resolved from.
    pub total: usize,
    /// Oldest `created_at` (microseconds since the epoch); `None` while the
    /// session holds no rows.
    pub first_created_at: Option<i64>,
    /// Newest `created_at`; `None` while the session holds no rows.
    pub last_created_at: Option<i64>,
}

/// Tool names a session used, grouped in SQL.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct SessionToolTitles {
    /// Completed calls (`post-tool-use`) per non-empty title.
    pub completed: Vec<(String, usize)>,
    /// Every distinct non-empty title carried by a `pre-tool-use` or
    /// `post-tool-use` row.
    pub titles: Vec<String>,
}

/// The prompt titles a session page lists, with the session's true prompt
/// count.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SessionPromptTitles {
    /// User prompts the session holds (the uncapped total).
    pub total: usize,
    /// The first titles in capture order: every one of them when the session
    /// holds at most `head + tail` prompts, else the first `head`.
    pub first: Vec<String>,
    /// The last `tail` titles in capture order, only when the session holds
    /// more than `head + tail` prompts.
    pub last: Vec<String>,
}

/// What a page prints about one observation, without the body.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SessionLine {
    /// Event classification.
    pub kind: ObservationKind,
    /// Extension namespace, if any.
    pub extension: Option<String>,
    /// Source event name, if any.
    pub source_event: Option<String>,
    /// The first [`SESSION_LINE_TITLE_CHARS`] characters of the title.
    pub title: String,
    /// When the observation happened.
    pub created_at: Timestamp,
}

/// Title characters a [`SessionLine`] keeps.
pub const SESSION_LINE_TITLE_CHARS: usize = 80;

/// The kinds that make a session worth a summary page: a user prompt or a tool
/// use. The writer's lifecycle-only end
/// (`end_lifecycle_only_session_in_tx`) and the reader's
/// [`SessionKindSummary::substantive`] both build their query from this one
/// predicate, and the router's `is_ephemeral_session` is its Rust twin (a test
/// pins the three together).
pub const SUBSTANTIVE_OBSERVATION_KIND_SQL: &str =
    "kind IN ('user-prompt', 'pre-tool-use', 'post-tool-use')";

impl SessionObservationSnapshot<'_> {
    /// Rows this snapshot has deserialized into an [`Observation`] or a
    /// [`SessionLine`] so far. Aggregates and the prompt-title queries (the
    /// bounded list and the one-row-at-a-time title walk) are not counted:
    /// they return counters and short strings, not rows.
    #[must_use]
    pub fn rows_read(&self) -> usize {
        self.rows_read.get()
    }

    /// Counts and newest-of-kind markers in one pass over the session.
    ///
    /// # Errors
    /// Propagates any SQL error.
    pub fn kind_summary(&self) -> StoreResult<SessionKindSummary> {
        let failed = failed_tool_sql();
        let sql = format!(
            "SELECT COUNT(*), \
                    COALESCE(SUM(kind = ?2), 0), \
                    COALESCE(MAX({SUBSTANTIVE_OBSERVATION_KIND_SQL}), 0), \
                    MAX(CASE WHEN kind = ?3 THEN created_at END), \
                    MAX(CASE WHEN kind = ?4 THEN created_at END), \
                    MAX(CASE WHEN kind = ?5 THEN created_at END), \
                    MAX(CASE WHEN kind = ?5 AND body <> '' THEN created_at END), \
                    MAX(CASE WHEN kind = ?6 THEN created_at END), \
                    MAX(CASE WHEN kind = ?2 THEN created_at END), \
                    COALESCE(SUM(kind = ?6 AND {failed}), 0), \
                    MAX(CASE WHEN kind = ?6 AND {failed} THEN created_at END) \
             FROM observations WHERE session_id = ?1"
        );
        let summary = self.conn.query_row(
            &sql,
            params![
                self.session_id,
                ObservationKind::UserPrompt.as_str(),
                ObservationKind::SessionStart.as_str(),
                ObservationKind::SessionEnd.as_str(),
                ObservationKind::Stop.as_str(),
                ObservationKind::PostToolUse.as_str(),
                TOOL_BODY_SEPARATOR,
                FAILED_TOOL_OUTCOME_LINE,
            ],
            |row| {
                Ok(SessionKindSummary {
                    total: usize::try_from(row.get::<_, i64>(0)?).unwrap_or(usize::MAX),
                    prompts: usize::try_from(row.get::<_, i64>(1)?).unwrap_or(usize::MAX),
                    substantive: row.get::<_, i64>(2)? != 0,
                    last_session_start_at: row.get(3)?,
                    last_session_end_at: row.get(4)?,
                    last_stop_at: row.get(5)?,
                    last_stop_with_body_at: row.get(6)?,
                    last_post_tool_at: row.get(7)?,
                    last_prompt_at: row.get(8)?,
                    failed_tool_calls: usize::try_from(row.get::<_, i64>(9)?).unwrap_or(usize::MAX),
                    last_failed_tool_at: row.get(10)?,
                })
            },
        )?;
        Ok(summary)
    }

    /// Row count and the session's first and last `created_at` in one
    /// aggregate pass, without reading a row.
    ///
    /// # Errors
    /// Propagates any SQL error.
    pub fn projection_totals(&self) -> StoreResult<ObservationProjectionTotals> {
        let (total, first, last): (i64, Option<i64>, Option<i64>) = self.conn.query_row(
            "SELECT COUNT(*), MIN(created_at), MAX(created_at) \
             FROM observations WHERE session_id = ?1",
            params![self.session_id],
            |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)),
        )?;
        Ok(ObservationProjectionTotals {
            total: usize::try_from(total).unwrap_or(usize::MAX),
            first_created_at: first,
            last_created_at: last,
        })
    }

    /// The tool names the session used, grouped in SQL.
    ///
    /// # Errors
    /// Propagates any SQL error.
    pub fn tool_titles(&self) -> StoreResult<SessionToolTitles> {
        let mut stmt = self.conn.prepare_cached(
            "SELECT kind, title, COUNT(*) FROM observations \
             WHERE session_id = ?1 AND kind IN (?2, ?3) AND title <> '' \
             GROUP BY kind, title",
        )?;
        let rows = stmt.query_map(
            params![
                self.session_id,
                ObservationKind::PreToolUse.as_str(),
                ObservationKind::PostToolUse.as_str(),
            ],
            |row| {
                Ok((
                    row.get::<_, String>(0)?,
                    row.get::<_, String>(1)?,
                    row.get::<_, i64>(2)?,
                ))
            },
        )?;
        let mut out = SessionToolTitles::default();
        let mut titles = std::collections::BTreeSet::new();
        for row in rows {
            let (kind, title, count) = row?;
            if kind == ObservationKind::PostToolUse.as_str() {
                out.completed
                    .push((title.clone(), usize::try_from(count).unwrap_or(usize::MAX)));
            }
            titles.insert(title);
        }
        out.titles = titles.into_iter().collect();
        Ok(out)
    }

    /// The prompt titles a page lists, with the session's true prompt count.
    ///
    /// A page prints at most the first `head` and the last `tail` titles, so
    /// this reads at most `head + tail` titles plus one `COUNT(*)`, whatever
    /// the session holds. Titles are short by construction (the router
    /// truncates them for display).
    ///
    /// # Errors
    /// Propagates any SQL error.
    pub fn prompt_titles(&self, head: usize, tail: usize) -> StoreResult<SessionPromptTitles> {
        let total = self.conn.query_row(
            "SELECT COUNT(*) FROM observations \
             WHERE session_id = ?1 AND kind = ?2",
            params![self.session_id, ObservationKind::UserPrompt.as_str()],
            |row| row.get::<_, i64>(0),
        )?;
        let total = usize::try_from(total).unwrap_or(usize::MAX);
        if total <= head + tail {
            return Ok(SessionPromptTitles {
                total,
                first: self.prompt_title_window(total, ObservationOrder::Asc)?,
                last: Vec::new(),
            });
        }
        let mut last = self.prompt_title_window(tail, ObservationOrder::Desc)?;
        last.reverse();
        Ok(SessionPromptTitles {
            total,
            first: self.prompt_title_window(head, ObservationOrder::Asc)?,
            last,
        })
    }

    /// The first `limit` user-prompt titles of the session in `order`.
    ///
    /// # Errors
    /// Propagates any SQL error.
    fn prompt_title_window(
        &self,
        limit: usize,
        order: ObservationOrder,
    ) -> StoreResult<Vec<String>> {
        let direction = match order {
            ObservationOrder::Asc => "ASC",
            ObservationOrder::Desc => "DESC",
        };
        let sql = format!(
            "SELECT title FROM observations \
             WHERE session_id = ?1 AND kind = ?2 \
             ORDER BY created_at {direction}, rowid {direction} LIMIT ?3"
        );
        let mut stmt = self.conn.prepare_cached(&sql)?;
        let rows = stmt.query_map(
            params![
                self.session_id,
                ObservationKind::UserPrompt.as_str(),
                i64::try_from(limit).unwrap_or(i64::MAX),
            ],
            |row| row.get(0),
        )?;
        let mut out = Vec::with_capacity(limit);
        for title in rows {
            out.push(title?);
        }
        Ok(out)
    }

    /// Walk the session's user prompts in capture order, one resident at a
    /// time, feeding `visit` each title and, only when the title contains
    /// `body_for_titles_like`, the prompt's body. The walk stops at the first
    /// `false`, so a caller that settles the page title reads bodies no
    /// further than the prompt that named it: a session full of subagent
    /// preambles costs the bodies up to the first usable one, not all of
    /// them, and one row is resident at a time no matter how long it is.
    ///
    /// # Errors
    /// Propagates any SQL error.
    pub fn scan_prompts(
        &self,
        body_for_titles_like: &str,
        mut visit: impl FnMut(&str, Option<&str>) -> bool,
    ) -> StoreResult<()> {
        let mut stmt = self.conn.prepare_cached(
            "SELECT title, CASE WHEN instr(title, ?3) > 0 THEN body END \
             FROM observations WHERE session_id = ?1 AND kind = ?2 \
             ORDER BY created_at ASC, rowid ASC",
        )?;
        let mut rows = stmt.query(params![
            self.session_id,
            ObservationKind::UserPrompt.as_str(),
            body_for_titles_like,
        ])?;
        while let Some(row) = rows.next()? {
            let title: String = row.get(0)?;
            let body: Option<String> = row.get(1)?;
            if !visit(&title, body.as_deref()) {
                break;
            }
        }
        Ok(())
    }

    /// The first `limit` rows of the session, oldest first, as page lines.
    ///
    /// # Errors
    /// Propagates any SQL error.
    pub fn first_lines(&self, limit: usize) -> StoreResult<Vec<SessionLine>> {
        self.lines(limit, ObservationOrder::Asc)
    }

    /// The last `limit` rows of the session, oldest first, as page lines.
    ///
    /// # Errors
    /// Propagates any SQL error.
    pub fn last_lines(&self, limit: usize) -> StoreResult<Vec<SessionLine>> {
        let mut lines = self.lines(limit, ObservationOrder::Desc)?;
        lines.reverse();
        Ok(lines)
    }

    fn lines(&self, limit: usize, order: ObservationOrder) -> StoreResult<Vec<SessionLine>> {
        let direction = match order {
            ObservationOrder::Asc => "ASC",
            ObservationOrder::Desc => "DESC",
        };
        let sql = format!(
            "SELECT kind, extension, source_event, substr(title, 1, ?3), created_at \
             FROM observations WHERE session_id = ?1 \
             ORDER BY created_at {direction}, rowid {direction} LIMIT ?2"
        );
        let mut stmt = self.conn.prepare_cached(&sql)?;
        let mut rows = stmt.query(params![
            self.session_id,
            i64::try_from(limit).unwrap_or(i64::MAX),
            i64::try_from(SESSION_LINE_TITLE_CHARS).unwrap_or(80),
        ])?;
        let mut out = Vec::new();
        while let Some(row) = rows.next()? {
            let kind_str: String = row.get(0)?;
            let created_us: i64 = row.get(4)?;
            out.push(SessionLine {
                kind: kind_str
                    .parse::<ObservationKind>()
                    .map_err(StoreError::from)?,
                extension: row.get(1)?,
                source_event: row.get(2)?,
                title: row.get(3)?,
                created_at: Timestamp::from_microsecond(created_us).map_err(|e| {
                    StoreError::Memory(ai_memory_core::MemoryError::MalformedRecord(format!(
                        "bad timestamp: {e}"
                    )))
                })?,
            });
            self.rows_read.set(self.rows_read.get() + 1);
        }
        Ok(out)
    }

    /// Walk the session's rows in `order`, one resident at a time, and return
    /// the first value `visit` produces.
    ///
    /// `kinds` restricts the walk to those kinds (empty = every kind) and
    /// `at_or_before` starts it at an indexed `created_at` bound, which is how
    /// a caller that already knows the newest row of a kind (from
    /// [`Self::kind_summary`]) lands on it without walking the rows after it.
    /// The walk ends at the first `Some`, so a predicate that accepts early
    /// reads a handful of rows; one that never accepts walks the session, but
    /// still keeps a single row in memory.
    ///
    /// # Errors
    /// Propagates any SQL error.
    pub fn scan<T>(
        &self,
        order: ObservationOrder,
        kinds: &[ObservationKind],
        at_or_before: Option<i64>,
        mut visit: impl FnMut(&Observation) -> Option<T>,
    ) -> StoreResult<Option<T>> {
        let direction = match order {
            ObservationOrder::Asc => "ASC",
            ObservationOrder::Desc => "DESC",
        };
        let mut sql = String::from(
            "SELECT id, session_id, workspace_id, project_id, kind, extension, source_event, \
                    title, body, importance, created_at \
             FROM observations WHERE session_id = ?",
        );
        let mut sql_params: Vec<Value> = vec![Value::Blob(self.session_id.clone())];
        if let Some(bound) = at_or_before {
            sql.push_str(" AND created_at <= ?");
            sql_params.push(Value::Integer(bound));
        }
        if !kinds.is_empty() {
            sql.push_str(" AND kind IN (");
            for (i, kind) in kinds.iter().enumerate() {
                sql.push_str(if i == 0 { "?" } else { ", ?" });
                sql_params.push(Value::Text(kind.as_str().to_string()));
            }
            sql.push(')');
        }
        let _ = write!(sql, " ORDER BY created_at {direction}, rowid {direction}");
        let mut stmt = self.conn.prepare_cached(&sql)?;
        let mut rows = stmt.query(params_from_iter(sql_params))?;
        while let Some(row) = rows.next()? {
            let observation = row_to_observation(row)??;
            self.rows_read.set(self.rows_read.get() + 1);
            if let Some(found) = visit(&observation) {
                return Ok(Some(found));
            }
        }
        Ok(None)
    }

    /// Walk the session's rows in capture order (`created_at`, then `rowid`),
    /// one resident at a time, giving `visit` each row's `rowid` beside the
    /// materialised [`Observation`].
    ///
    /// A caller that wants more than one row back from a streamed pass keeps
    /// the `rowid`s it liked here and re-reads those rows with
    /// [`Self::row_by_rowid`]: one indexed point fetch per kept row instead
    /// of a second full walk.
    ///
    /// `visit` returning `false` stops the walk early, so a caller that
    /// needs only the first matching row does not pay for the rest. Like
    /// [`Self::scan`], this keeps a single row in memory whatever the
    /// session holds.
    ///
    /// # Errors
    /// Propagates any SQL error.
    pub fn each_row_with_rowid(
        &self,
        mut visit: impl FnMut(i64, &Observation) -> bool,
    ) -> StoreResult<()> {
        let mut stmt = self.conn.prepare_cached(
            "SELECT rowid, id, session_id, workspace_id, project_id, kind, extension, \
                    source_event, title, body, importance, created_at \
             FROM observations WHERE session_id = ?1 \
             ORDER BY created_at ASC, rowid ASC",
        )?;
        let mut rows = stmt.query(params![self.session_id])?;
        while let Some(row) = rows.next()? {
            let rowid: i64 = row.get(0)?;
            let observation = row_to_observation_at(row, 1)??;
            self.rows_read.set(self.rows_read.get() + 1);
            if !visit(rowid, &observation) {
                break;
            }
        }
        Ok(())
    }

    /// Materialise one row of the session by its `rowid` — the point fetch a
    /// streamed pass uses to re-read a body it chose to keep. One row, or
    /// none when the `rowid` belongs to another session or is gone.
    ///
    /// # Errors
    /// Propagates any SQL error.
    pub fn row_by_rowid(&self, rowid: i64) -> StoreResult<Option<Observation>> {
        let mut stmt = self.conn.prepare_cached(
            "SELECT id, session_id, workspace_id, project_id, kind, extension, source_event, \
                    title, body, importance, created_at \
             FROM observations WHERE session_id = ?1 AND rowid = ?2",
        )?;
        let mut rows = stmt.query(params![self.session_id, rowid])?;
        match rows.next()? {
            Some(row) => {
                let observation = row_to_observation(row)??;
                self.rows_read.set(self.rows_read.get() + 1);
                Ok(Some(observation))
            }
            None => Ok(None),
        }
    }
}

fn row_to_observation(row: &rusqlite::Row<'_>) -> rusqlite::Result<StoreResult<Observation>> {
    row_to_observation_at(row, 0)
}

/// [`row_to_observation`] with its columns shifted by `base` — the snapshot
/// streams whose `SELECT` leads with `rowid`.
fn row_to_observation_at(
    row: &rusqlite::Row<'_>,
    base: usize,
) -> rusqlite::Result<StoreResult<Observation>> {
    let id_bytes: Vec<u8> = row.get(base)?;
    let session_bytes: Vec<u8> = row.get(base + 1)?;
    let workspace_bytes: Vec<u8> = row.get(base + 2)?;
    let project_bytes: Vec<u8> = row.get(base + 3)?;
    let kind_str: String = row.get(base + 4)?;
    let extension: Option<String> = row.get(base + 5)?;
    let source_event: Option<String> = row.get(base + 6)?;
    let title: String = row.get(base + 7)?;
    let body: String = row.get(base + 8)?;
    let importance: i64 = row.get(base + 9)?;
    let created_us: i64 = row.get(base + 10)?;
    Ok(materialise_observation(
        id_bytes,
        session_bytes,
        workspace_bytes,
        project_bytes,
        kind_str,
        extension,
        source_event,
        title,
        body,
        importance,
        created_us,
    ))
}

fn row_to_observation_record(
    row: &rusqlite::Row<'_>,
) -> rusqlite::Result<StoreResult<ObservationRecord>> {
    let id_bytes: Vec<u8> = row.get(0)?;
    let session_bytes: Vec<u8> = row.get(1)?;
    let kind: String = row.get(2)?;
    let title: String = row.get(3)?;
    let body: String = row.get(4)?;
    let importance: i64 = row.get(5)?;
    let created_us: i64 = row.get(6)?;
    let extension: Option<String> = row.get(7)?;
    let source_event: Option<String> = row.get(8)?;
    let created_at = jiff::Timestamp::from_microsecond(created_us)
        .map(|ts| ts.to_string())
        .unwrap_or_default();
    let record = ObservationId::from_slice(&id_bytes).and_then(|id| {
        SessionId::from_slice(&session_bytes).map(|session_id| ObservationRecord {
            id,
            session_id,
            kind,
            title,
            body,
            importance: u8::try_from(importance.clamp(1, 10)).unwrap_or(1),
            created_at,
            extension,
            source_event,
        })
    });
    Ok(record.map_err(StoreError::from))
}

#[allow(clippy::too_many_arguments)]
fn materialise_observation(
    id_bytes: Vec<u8>,
    session_bytes: Vec<u8>,
    workspace_bytes: Vec<u8>,
    project_bytes: Vec<u8>,
    kind_str: String,
    extension: Option<String>,
    source_event: Option<String>,
    title: String,
    body: String,
    importance: i64,
    created_us: i64,
) -> StoreResult<Observation> {
    Ok(Observation {
        id: ObservationId::from_slice(&id_bytes)?,
        session_id: SessionId::from_slice(&session_bytes)?,
        workspace_id: WorkspaceId::from_slice(&workspace_bytes)?,
        project_id: ProjectId::from_slice(&project_bytes)?,
        kind: kind_str
            .parse::<ObservationKind>()
            .map_err(StoreError::from)?,
        extension,
        source_event,
        title,
        body,
        importance: u8::try_from(importance.clamp(1, 10)).unwrap_or(1),
        created_at: jiff::Timestamp::from_microsecond(created_us).map_err(|e| {
            StoreError::Memory(ai_memory_core::MemoryError::MalformedRecord(format!(
                "bad timestamp: {e}"
            )))
        })?,
    })
}

/// One stored embedding row, materialised for the vector path.
#[derive(Debug, Clone)]
pub struct StoredEmbedding {
    /// Page identifier (always the `is_latest=1` row's id).
    pub id: PageId,
    /// Relative wiki path.
    pub path: PagePath,
    /// Unit-normalised vector.
    pub vector: Vec<f32>,
}

fn score_desc(a: &(PageId, PagePath, f32), b: &(PageId, PagePath, f32)) -> std::cmp::Ordering {
    b.2.partial_cmp(&a.2).unwrap_or(std::cmp::Ordering::Equal)
}

fn dot_embedding_bytes(query: &[f32], bytes: &[u8], dim: u32) -> StoreResult<f32> {
    let dim = dim as usize;
    if query.len() != dim {
        return Err(StoreError::Memory(
            ai_memory_core::MemoryError::MalformedRecord(format!(
                "query vector dim {} != expected {}",
                query.len(),
                dim
            )),
        ));
    }
    let expected = dim * 4;
    if bytes.len() != expected {
        return Err(StoreError::Memory(
            ai_memory_core::MemoryError::MalformedRecord(format!(
                "embedding bytes {} != expected {}",
                bytes.len(),
                expected
            )),
        ));
    }
    Ok(query
        .iter()
        .zip(bytes.as_chunks::<4>().0)
        .map(|(q, chunk)| f32::from_le_bytes(*chunk) * q)
        .sum())
}

fn bytes_to_f32_vec(bytes: &[u8], dim: u32) -> StoreResult<Vec<f32>> {
    let expected = (dim as usize) * 4;
    if bytes.len() != expected {
        return Err(StoreError::Memory(
            ai_memory_core::MemoryError::MalformedRecord(format!(
                "embedding bytes {} != expected {}",
                bytes.len(),
                expected
            )),
        ));
    }
    let mut out = Vec::with_capacity(dim as usize);
    for chunk in bytes.as_chunks::<4>().0 {
        out.push(f32::from_le_bytes(*chunk));
    }
    Ok(out)
}

/// Pack a `&[f32]` into little-endian bytes for storage. Inverse of
/// [`bytes_to_f32_vec`].
#[must_use]
pub fn f32_vec_to_bytes(v: &[f32]) -> Vec<u8> {
    let mut out = Vec::with_capacity(v.len() * 4);
    for x in v {
        out.extend_from_slice(&x.to_le_bytes());
    }
    out
}

/// One row's worth of input for the M8 retention formula.
#[derive(Debug, Clone, Serialize)]
pub struct DecayCandidate {
    /// Stable identifier.
    pub id: PageId,
    /// Relative wiki path.
    pub path: PagePath,
    /// Tier (the sweep only considers `episodic`).
    pub tier: ai_memory_core::Tier,
    /// Pinned flag — true means "never decay".
    pub pinned: bool,
    /// `updated_at` in microseconds since epoch.
    pub updated_at_us: i64,
    /// Total query/access hits.
    pub access_count: u32,
    /// `last_accessed_at` in microseconds since epoch, or `None` if never accessed.
    pub last_accessed_at_us: Option<i64>,
    /// Frontmatter JSON; the sweep peeks at it for an explicit
    /// `pinned: true` (which overrides the schema flag).
    pub frontmatter_json: String,
    /// TTL instant in microseconds since epoch. The sweep hard-deletes
    /// pages past this regardless of tier or pin.
    pub expires_at_us: Option<i64>,
    /// Per-page salience once explicit feedback has moved it (V37);
    /// `None` means "use `DecayParams::salience_default`".
    pub salience: Option<f64>,
    /// A2 tier-down marker (V65): microseconds since epoch when this page was
    /// extractively compacted, or `None` if it has never been compacted. The
    /// forget sweep and the curator both skip a page whose marker is set so a
    /// deliberately-short compacted page is never re-compacted or re-classified
    /// as a fresh cold candidate.
    pub compacted_at_us: Option<i64>,
}

/// One forget-sweep tombstone eligible for permanent cleanup.
#[derive(Debug, Clone, Serialize)]
pub struct DecayTombstone {
    /// Evicted head whose ancestry chain is awaiting deletion.
    pub id: PageId,
    /// Relative wiki path associated with the evicted chain.
    pub path: PagePath,
}

fn row_to_decay_candidate(
    row: &rusqlite::Row<'_>,
) -> rusqlite::Result<StoreResult<DecayCandidate>> {
    let id_bytes: Vec<u8> = row.get(0)?;
    let path: String = row.get(1)?;
    let tier_str: String = row.get(2)?;
    let pinned: i64 = row.get(3)?;
    let updated_at_us: i64 = row.get(4)?;
    let access_count: i64 = row.get(5)?;
    let last_accessed_at_us: Option<i64> = row.get(6)?;
    let frontmatter_json: String = row.get(7)?;
    let expires_at_us: Option<i64> = row.get(8)?;
    let salience: Option<f64> = row.get(9)?;
    let compacted_at_us: Option<i64> = row.get(10)?;
    Ok(materialise_decay_candidate(
        id_bytes,
        path,
        tier_str,
        pinned,
        updated_at_us,
        access_count,
        last_accessed_at_us,
        frontmatter_json,
        expires_at_us,
        salience,
        compacted_at_us,
    ))
}

#[allow(clippy::too_many_arguments)]
fn materialise_decay_candidate(
    id_bytes: Vec<u8>,
    path: String,
    tier_str: String,
    pinned: i64,
    updated_at_us: i64,
    access_count: i64,
    last_accessed_at_us: Option<i64>,
    frontmatter_json: String,
    expires_at_us: Option<i64>,
    salience: Option<f64>,
    compacted_at_us: Option<i64>,
) -> StoreResult<DecayCandidate> {
    Ok(DecayCandidate {
        id: PageId::from_slice(&id_bytes)?,
        path: PagePath::new(path)?,
        tier: tier_str
            .parse::<ai_memory_core::Tier>()
            .map_err(StoreError::from)?,
        pinned: pinned != 0,
        updated_at_us,
        access_count: u32::try_from(access_count.max(0)).unwrap_or(u32::MAX),
        last_accessed_at_us,
        frontmatter_json,
        expires_at_us,
        salience,
        compacted_at_us,
    })
}

fn auto_improve_group_counts(
    conn: &Connection,
    column: &str,
    workspace_id: WorkspaceId,
    project_id: ProjectId,
    since_created_at: i64,
    extra_where: Option<&str>,
) -> rusqlite::Result<Vec<AutoImproveTelemetryCount>> {
    let learning_filter = "kind NOT IN ('curator_report', 'auto_improve_report')";
    let filter = extra_where.unwrap_or(learning_filter);
    let sql = format!(
        "SELECT COALESCE({column}, '(none)') AS key, COUNT(*) AS count
         FROM auto_improve_proposals
         WHERE workspace_id = ?1 AND project_id = ?2 AND staged_at >= ?3 AND {filter}
         GROUP BY key ORDER BY count DESC, key ASC"
    );
    let mut stmt = conn.prepare(&sql)?;
    let rows = stmt.query_map(
        params![
            workspace_id.as_bytes(),
            project_id.as_bytes(),
            since_created_at
        ],
        telemetry_count_from_row,
    )?;
    let mut out = Vec::new();
    for row in rows {
        out.push(row?);
    }
    Ok(out)
}

fn auto_improve_rejection_group_counts(
    conn: &Connection,
    expr: &str,
    workspace_id: WorkspaceId,
    project_id: ProjectId,
    since_created_at: i64,
    limit: i64,
) -> rusqlite::Result<Vec<AutoImproveTelemetryCount>> {
    let sql = format!(
        "SELECT {expr} AS key, COUNT(*) AS count
         FROM auto_improve_rejections r
         LEFT JOIN auto_improve_proposals p ON p.id = r.source_proposal_id
         WHERE r.workspace_id = ?1 AND r.project_id = ?2 AND r.created_at >= ?3
           AND (r.source_proposal_id IS NULL OR COALESCE(p.kind, '') NOT IN ('curator_report', 'auto_improve_report'))
         GROUP BY key ORDER BY count DESC, key ASC LIMIT ?4"
    );
    let mut stmt = conn.prepare(&sql)?;
    let rows = stmt.query_map(
        params![
            workspace_id.as_bytes(),
            project_id.as_bytes(),
            since_created_at,
            limit
        ],
        telemetry_count_from_row,
    )?;
    let mut out = Vec::new();
    for row in rows {
        out.push(row?);
    }
    Ok(out)
}

fn auto_improve_repeated_rejection_fingerprints(
    conn: &Connection,
    workspace_id: WorkspaceId,
    project_id: ProjectId,
    since_created_at: i64,
    limit: i64,
) -> rusqlite::Result<Vec<AutoImproveTelemetryCount>> {
    let mut stmt = conn.prepare(
        "SELECT r.normalized_fingerprint AS key, COUNT(*) AS count
         FROM auto_improve_rejections r
         LEFT JOIN auto_improve_proposals p ON p.id = r.source_proposal_id
         WHERE r.workspace_id = ?1 AND r.project_id = ?2 AND r.created_at >= ?3
           AND (r.source_proposal_id IS NULL OR COALESCE(p.kind, '') NOT IN ('curator_report', 'auto_improve_report'))
         GROUP BY normalized_fingerprint HAVING count > 1
         ORDER BY count DESC, key ASC LIMIT ?4",
    )?;
    let rows = stmt.query_map(
        params![
            workspace_id.as_bytes(),
            project_id.as_bytes(),
            since_created_at,
            limit
        ],
        telemetry_count_from_row,
    )?;
    let mut out = Vec::new();
    for row in rows {
        out.push(row?);
    }
    Ok(out)
}

fn telemetry_count_from_row(
    row: &rusqlite::Row<'_>,
) -> rusqlite::Result<AutoImproveTelemetryCount> {
    let count: i64 = row.get(1)?;
    Ok(AutoImproveTelemetryCount {
        key: row.get(0)?,
        count: usize::try_from(count).unwrap_or(usize::MAX),
    })
}

/// Normalize a cwd for comparison: treat Windows backslashes as path
/// separators and trim trailing separators while keeping a bare root as `/`.
/// Drive-letter and UNC paths are ASCII-lowercased: the server often runs
/// on Linux (Docker Desktop) while the hook cwd is a Windows host path,
/// and Explorer/Git/PowerShell disagree on `C:` vs `c:`. Unix paths stay
/// byte-exact (`/Repo` is not `/repo`). Pure and string-only; it does not
/// touch the filesystem.
pub(crate) fn normalize_cwd(p: &str) -> std::borrow::Cow<'_, str> {
    let replaced = if p.contains('\\') {
        std::borrow::Cow::Owned(p.replace('\\', "/"))
    } else {
        std::borrow::Cow::Borrowed(p)
    };
    let trimmed = replaced.trim_end_matches('/');
    let core = if trimmed.is_empty() {
        std::borrow::Cow::Borrowed("/")
    } else if trimmed.len() == replaced.len() {
        replaced
    } else {
        std::borrow::Cow::Owned(trimmed.to_string())
    };
    if is_windows_style_path(&core) {
        std::borrow::Cow::Owned(core.to_ascii_lowercase())
    } else {
        core
    }
}

fn is_windows_style_path(path: &str) -> bool {
    let bytes = path.as_bytes();
    (bytes.len() >= 2 && bytes[0].is_ascii_alphabetic() && bytes[1] == b':')
        || path.starts_with("//")
}

/// True when `descendant` is the same directory as `ancestor` or nested
/// below it, with component-boundary awareness: `/repo` contains
/// `/repo/api` but neither `/repo-other` nor `/repository`. Inputs are
/// normalized first. Pure; no SQL `LIKE`, so `%`/`_` in a path cannot act
/// as wildcards.
pub(crate) fn cwd_within(ancestor: &str, descendant: &str) -> bool {
    let a = normalize_cwd(ancestor);
    let d = normalize_cwd(descendant);
    if a == d {
        return true;
    }
    if a == "/" {
        // Root is an ancestor of every other absolute path.
        return d.starts_with('/') && d.len() > 1;
    }
    // Byte-prefix plus a `/` boundary right after it. `starts_with` is
    // byte-exact and `/` is ASCII, so this is UTF-8 safe.
    d.starts_with(a.as_ref()) && d.as_bytes().get(a.len()) == Some(&b'/')
}

fn filter_briefing_slots(
    snapshot: &mut BriefingSnapshot,
    visibility: &ai_memory_core::SlotVisibility,
) {
    snapshot.slots.retain(|page| visibility.allows(&page.path));
    snapshot
        .recent_pages
        .retain(|page| visibility.allows(&page.path));
}

fn slot_visibility_sql(
    visibility: &ai_memory_core::SlotVisibility,
    param_index: usize,
) -> (String, Option<String>) {
    if !visibility.hides_other_namespaces() {
        return ("path GLOB '_slots/*'".to_string(), None);
    }
    match visibility.own_namespace() {
        Some(namespace) => (
            format!(
                "path GLOB '_slots/*' AND (path NOT GLOB '_slots/*/*' OR path GLOB ?{param_index})"
            ),
            Some(format!("{}{namespace}/*", ai_memory_core::SLOT_PREFIX)),
        ),
        None => (
            "path GLOB '_slots/*' AND path NOT GLOB '_slots/*/*'".to_string(),
            None,
        ),
    }
}

fn slot_exclusion_sql(
    visibility: &ai_memory_core::SlotVisibility,
    param_index: usize,
) -> (String, Option<String>) {
    if !visibility.hides_other_namespaces() {
        return ("1".to_string(), None);
    }
    match visibility.own_namespace() {
        Some(namespace) => (
            format!("(path NOT GLOB '_slots/*/*' OR path GLOB ?{param_index})"),
            Some(format!("{}{namespace}/*", ai_memory_core::SLOT_PREFIX)),
        ),
        None => ("path NOT GLOB '_slots/*/*'".to_string(), None),
    }
}

/// SQL fragment restricting a handoff query to what `filter` can actually see,
/// plus the owner key it expects bound at `?{param_index}` — the first free
/// positional parameter of the statement it is spliced into.
///
/// The count and the fetch must agree: a briefing that advertises a pending
/// baton the same caller cannot retrieve is worse than no count at all, because
/// the agent keeps asking for something that will always come back empty.
///
/// The owner key is BOUND, never interpolated. It is not a validated
/// identifier: it is [`ai_memory_core::IdentityKey::storage_key`] TEXT, and on
/// a server behind a trusted proxy what follows the prefix is whatever
/// `X-Memory-Actor-Sub` carried — an OIDC subject the engine never parses — so
/// nothing upstream constrains its characters.
/// One open handoff, as an operator needs to see it to decide what to cancel.
///
/// Content-free by construction: identity, provenance and age only. The
/// summary body is deliberately absent — this exists so
/// `memory_handoff_cancel` has an id to be given, not to render the handoff.
#[derive(Debug, Clone, serde::Serialize)]
pub struct OpenHandoff {
    pub id: String,
    pub from_agent: String,
    pub to_agent: Option<String>,
    pub cwd: Option<String>,
    pub created_at_ms: i64,
}

fn handoff_owner_sql(filter: &OwnerFilter, param_index: usize) -> (String, Option<String>) {
    match filter {
        OwnerFilter::Any => (String::new(), None),
        OwnerFilter::Unattributed => (" AND owner_user IS NULL".to_string(), None),
        OwnerFilter::User(user) => (
            format!(" AND (owner_user IS NULL OR owner_user = ?{param_index})"),
            Some(user.clone()),
        ),
    }
}

fn is_handoff_candidate(h: &Handoff, cwd_filter: Option<&str>, owner_filter: &OwnerFilter) -> bool {
    // Ownership is checked FIRST, before the manual short-circuit below.
    // Order matters: a manual handoff is project-wide by cwd, so checking the
    // owner afterwards would let one operator's `memory_handoff_begin` be
    // claimed by the next session to start, whoever it belongs to — the exact
    // cross-operator mixing this filter exists to stop. Handoffs with no owner
    // (every pre-V39 row, and anything written without an actor) stay visible
    // to everyone, which preserves single-operator behaviour untouched.
    if !owner_filter.admits(h.origin.owner_user.as_deref()) {
        return false;
    }
    // Manual handoffs (memory_handoff_begin always sets from_session_id = None)
    // are project-wide and always candidates, whatever cwd they carry. Only auto
    // SessionEnd handoffs are cwd-path-boundary scoped. This makes "a manual
    // handoff always beats the auto one" deterministic on from_session_id,
    // instead of relying on a manual handoff happening to have a NULL cwd.
    if h.origin.from_session_id.is_none() {
        return true;
    }
    auto_handoff_matches_cwd(h.origin.cwd.as_deref(), cwd_filter)
}

/// Whether an automatic handoff is eligible for a session starting in
/// `cwd_filter`. Shared with the acceptance path so selection and supersession
/// apply exactly the same path-boundary rule.
pub(crate) fn auto_handoff_matches_cwd(
    handoff_cwd: Option<&str>,
    cwd_filter: Option<&str>,
) -> bool {
    match (cwd_filter, handoff_cwd) {
        // Project-wide read: every open handoff is a candidate.
        (None, _) => true,
        // No stored cwd: treat as project-wide.
        (_, None) => true,
        // cwd-bearing auto handoffs match by path-boundary.
        (Some(session_cwd), Some(handoff_cwd)) => cwd_within(handoff_cwd, session_cwd),
    }
}

pub(crate) fn handoff_selection_key(
    manual: bool,
    created_at_micros: i64,
    cwd: Option<&str>,
    id: HandoffId,
) -> (bool, i64, usize, [u8; 16]) {
    // Cwd specificity discriminates only equal-time AUTO handoffs. For manual
    // handoffs it must be neutral so the newest manual wins, not whichever
    // happens to carry the longest cwd. Normalize before counting so legacy
    // `/repo/` rows do not outrank equivalent `/repo` rows.
    let auto_specificity = if manual {
        0
    } else {
        cwd.map_or(0, |cwd| normalize_cwd(cwd).len())
    };
    (
        manual,            // manual beats auto
        created_at_micros, // newest
        auto_specificity,  // most specific equal-time auto cwd
        *id.as_bytes(),    // deterministic final tie-break
    )
}

fn prefer_handoff(a: &Handoff, b: &Handoff) -> std::cmp::Ordering {
    handoff_selection_key(
        a.origin.from_session_id.is_none(),
        a.lifecycle.created_at.as_microsecond(),
        a.origin.cwd.as_deref(),
        a.scope.id,
    )
    .cmp(&handoff_selection_key(
        b.origin.from_session_id.is_none(),
        b.lifecycle.created_at.as_microsecond(),
        b.origin.cwd.as_deref(),
        b.scope.id,
    ))
}

/// Pick the handoff to deliver from a project's open handoffs.
///
/// See [`ReaderPool::latest_open_handoff`] for the full contract: manual handoffs
/// are project-wide, auto handoffs are filtered by cwd path-boundary, and a
/// manual handoff always beats an auto one, then newest, with cwd specificity
/// only breaking timestamp ties.
#[cfg(test)]
fn select_open_handoff(candidates: Vec<Handoff>, cwd_filter: Option<&str>) -> Option<Handoff> {
    candidates
        .into_iter()
        .filter(|h| is_handoff_candidate(h, cwd_filter, &OwnerFilter::Any))
        .max_by(prefer_handoff)
}

/// Build a [`Handoff`] from a row selected with the 18-column handoff SELECT
/// every handoff query in this file shares.
///
/// Reading the row here (instead of destructuring it into a long positional
/// argument list) keeps the column order defined in exactly one place next to
/// the `SELECT`s that produce it.
fn row_to_handoff(row: &rusqlite::Row<'_>) -> rusqlite::Result<StoreResult<Handoff>> {
    let id_bytes: Vec<u8> = row.get(0)?;
    let ws_bytes: Vec<u8> = row.get(1)?;
    let pj_bytes: Vec<u8> = row.get(2)?;
    let from_session_bytes: Option<Vec<u8>> = row.get(3)?;
    let from_agent: String = row.get(4)?;
    let to_agent: Option<String> = row.get(5)?;
    let cwd: Option<String> = row.get(6)?;
    let summary: String = row.get(7)?;
    let open_q_json: String = row.get(8)?;
    let next_s_json: String = row.get(9)?;
    let files_json: String = row.get(10)?;
    let state: String = row.get(11)?;
    let created_us: i64 = row.get(12)?;
    let accepted_by: Option<String> = row.get(13)?;
    let accepted_at_us: Option<i64> = row.get(14)?;
    let accepted_by_session_bytes: Option<Vec<u8>> = row.get(15)?;
    let owner_user: Option<String> = row.get(16)?;
    let accepted_by_user: Option<String> = row.get(17)?;

    Ok((|| {
        for (label, value) in [
            ("handoff owner", owner_user.as_deref()),
            ("accepting handoff operator", accepted_by_user.as_deref()),
        ] {
            if value.is_some_and(|value| IdentityKey::from_storage_key(value).is_none()) {
                return Err(StoreError::MalformedRecord(format!(
                    "{label} is not a qualified identity storage key"
                )));
            }
        }
        let open_questions: Vec<String> = serde_json::from_str(&open_q_json)?;
        let next_steps: Vec<String> = serde_json::from_str(&next_s_json)?;
        let files_touched: Vec<String> = serde_json::from_str(&files_json)?;
        let from_session = from_session_bytes
            .as_deref()
            .map(SessionId::from_slice)
            .transpose()?;
        let accepted_session = accepted_by_session_bytes
            .as_deref()
            .map(SessionId::from_slice)
            .transpose()?;
        Ok(Handoff {
            scope: HandoffScope {
                id: HandoffId::from_slice(&id_bytes)?,
                workspace_id: WorkspaceId::from_slice(&ws_bytes)?,
                project_id: ProjectId::from_slice(&pj_bytes)?,
            },
            origin: HandoffOrigin {
                from_session_id: from_session,
                from_agent: parse_agent(&from_agent),
                to_agent: to_agent.as_deref().map(parse_agent),
                cwd,
                owner_user,
            },
            content: HandoffContent {
                summary,
                open_questions,
                next_steps,
                files_touched,
            },
            lifecycle: HandoffLifecycle {
                state: state.parse::<HandoffState>().map_err(StoreError::from)?,
                created_at: jiff::Timestamp::from_microsecond(created_us).map_err(|e| {
                    StoreError::Memory(ai_memory_core::MemoryError::MalformedRecord(format!(
                        "bad created_at: {e}"
                    )))
                })?,
                accepted_by: accepted_by.as_deref().map(parse_agent),
                accepted_at: accepted_at_us
                    .map(jiff::Timestamp::from_microsecond)
                    .transpose()
                    .map_err(|e| {
                        StoreError::Memory(ai_memory_core::MemoryError::MalformedRecord(format!(
                            "bad accepted_at: {e}"
                        )))
                    })?,
                accepted_by_session: accepted_session,
                accepted_by_user,
            },
        })
    })())
}

fn parse_agent(s: &str) -> AgentKind {
    AgentKind::from_wire(s)
}

fn count(conn: &Connection, sql: &str) -> StoreResult<u64> {
    count_bound(conn, sql, &[])
}

/// `COUNT(*)` with an explicit parameter list.
///
/// The scope-less [`count`] and the scoped `count_project` / `count_workspace`
/// helpers each bind a fixed shape; a predicate spliced in by the caller (the
/// handoff owner filter) adds one more parameter to whichever shape it lands in,
/// so it needs a helper that takes the whole list.
fn count_bound(conn: &Connection, sql: &str, params: &[&dyn rusqlite::ToSql]) -> StoreResult<u64> {
    let n: Option<i64> = conn.query_row(sql, params, |row| row.get(0)).optional()?;
    Ok(u64::try_from(n.unwrap_or(0)).unwrap_or(0))
}

fn count_project(
    conn: &Connection,
    sql: &str,
    workspace_id: WorkspaceId,
    project_id: ProjectId,
) -> StoreResult<u64> {
    let n: Option<i64> = conn
        .query_row(
            sql,
            params![workspace_id.as_bytes(), project_id.as_bytes()],
            |row| row.get(0),
        )
        .optional()?;
    Ok(u64::try_from(n.unwrap_or(0)).unwrap_or(0))
}

/// Cross-project link degree for a project: `(dependents, dependencies)`.
/// `dependents` = distinct other projects whose pages link into this one;
/// `dependencies` = distinct other projects this one links out to. Counts
/// resolved links between latest unexpired pages only (`to_page_id` is set);
/// project ids are globally unique, so a bare `!= project_id` excludes self
/// across all workspaces.
fn cross_project_degree(
    conn: &Connection,
    workspace_id: WorkspaceId,
    project_id: ProjectId,
    now_us: i64,
) -> StoreResult<(u64, u64)> {
    let tp_ttl = not_expired("tp", "?3");
    let fp_ttl = not_expired("fp", "?3");
    let dependents: Option<i64> = conn
        .query_row(
            &format!(
                "SELECT COUNT(DISTINCT fp.project_id) \
                 FROM links l \
                 JOIN pages tp ON tp.id = l.to_page_id \
                     AND tp.workspace_id = ?1 AND tp.project_id = ?2 AND tp.is_latest = 1{tp_ttl} \
                 JOIN pages fp ON fp.id = l.from_page_id AND fp.is_latest = 1{fp_ttl} \
                 WHERE fp.project_id != ?2"
            ),
            params![workspace_id.as_bytes(), project_id.as_bytes(), now_us],
            |row| row.get(0),
        )
        .optional()?;
    let dependencies: Option<i64> = conn
        .query_row(
            &format!(
                "SELECT COUNT(DISTINCT tp.project_id) \
                 FROM links l \
                 JOIN pages fp ON fp.id = l.from_page_id \
                     AND fp.workspace_id = ?1 AND fp.project_id = ?2 AND fp.is_latest = 1{fp_ttl} \
                 JOIN pages tp ON tp.id = l.to_page_id AND tp.is_latest = 1{tp_ttl} \
                 WHERE tp.project_id != ?2"
            ),
            params![workspace_id.as_bytes(), project_id.as_bytes(), now_us],
            |row| row.get(0),
        )
        .optional()?;
    Ok((
        u64::try_from(dependents.unwrap_or(0)).unwrap_or(0),
        u64::try_from(dependencies.unwrap_or(0)).unwrap_or(0),
    ))
}

/// Run a one-row `SELECT workspace_id, project_id ... WHERE id = ?1` lookup.
fn scope_row(
    conn: &Connection,
    sql: &str,
    id: &[u8; 16],
) -> StoreResult<Option<(WorkspaceId, ProjectId)>> {
    let row = conn
        .query_row(sql, params![id], |row| {
            Ok((row.get::<_, Vec<u8>>(0)?, row.get::<_, Vec<u8>>(1)?))
        })
        .optional()?;
    match row {
        Some((ws, proj)) => Ok(Some((
            WorkspaceId::from_slice(&ws)?,
            ProjectId::from_slice(&proj)?,
        ))),
        None => Ok(None),
    }
}

fn count_workspace(conn: &Connection, sql: &str, workspace_id: WorkspaceId) -> StoreResult<u64> {
    let n: Option<i64> = conn
        .query_row(sql, params![workspace_id.as_bytes()], |row| row.get(0))
        .optional()?;
    Ok(u64::try_from(n.unwrap_or(0)).unwrap_or(0))
}

fn normalize_fts_query(query: &str, stopwords: &FtsStopwords) -> String {
    // Delegates to prepare_fts5_query: neutralises `word:` column syntax and
    // quotes tokens so `-` / `*` are not FTS5 operators.
    prepare_fts5_query(query, stopwords)
}

/// Count rows in a time-bounded window. Used by [`ReaderPool::briefing`]
/// to compute "last 7 days" / "last 30 days" activity slices.
fn window_activity(
    conn: &Connection,
    days: u32,
    cutoff_us: i64,
    now_us: i64,
) -> StoreResult<ActivityWindow> {
    let count_since = |sql: &str| -> StoreResult<u64> {
        let n: Option<i64> = conn
            .query_row(sql, params![cutoff_us], |row| row.get(0))
            .optional()?;
        Ok(u64::try_from(n.unwrap_or(0)).unwrap_or(0))
    };
    // `pages` is the only table counted here with a TTL, so it is the only one
    // that needs `now_us` bound alongside the cutoff.
    let pages_updated: Option<i64> = conn
        .query_row(
            &format!(
                "SELECT COUNT(*) FROM pages WHERE is_latest = 1 AND updated_at > ?1{not_expired}",
                not_expired = not_expired("pages", "?2"),
            ),
            params![cutoff_us, now_us],
            |row| row.get(0),
        )
        .optional()?;
    Ok(ActivityWindow {
        days,
        // `sessions` schema uses `started_at`, not `created_at` — easy
        // to forget because the other tables all use `created_at`.
        sessions: count_since("SELECT COUNT(*) FROM sessions WHERE started_at > ?1")?,
        observations: count_since("SELECT COUNT(*) FROM observations WHERE created_at > ?1")?,
        pages_updated: u64::try_from(pages_updated.unwrap_or(0)).unwrap_or(0),
    })
}

fn window_activity_project(
    conn: &Connection,
    days: u32,
    cutoff_us: i64,
    now_us: i64,
    workspace_id: WorkspaceId,
    project_id: ProjectId,
) -> StoreResult<ActivityWindow> {
    let count_since = |sql: &str| -> StoreResult<u64> {
        let n: Option<i64> = conn
            .query_row(
                sql,
                params![workspace_id.as_bytes(), project_id.as_bytes(), cutoff_us],
                |row| row.get(0),
            )
            .optional()?;
        Ok(u64::try_from(n.unwrap_or(0)).unwrap_or(0))
    };
    Ok(ActivityWindow {
        days,
        sessions: count_since(
            "SELECT COUNT(*) FROM sessions WHERE workspace_id = ?1 AND project_id = ?2 AND started_at > ?3",
        )?,
        observations: count_since(
            "SELECT COUNT(*) FROM observations WHERE workspace_id = ?1 AND project_id = ?2 AND created_at > ?3",
        )?,
        // See the TTL note in `window_activity`; the guard needs a fourth bind,
        // so this one statement does not go through `count_since`.
        pages_updated: {
            let n: Option<i64> = conn
                .query_row(
                    &format!(
                        "SELECT COUNT(*) FROM pages \
                         WHERE workspace_id = ?1 AND project_id = ?2 AND is_latest = 1 \
                           AND updated_at > ?3{not_expired}",
                        not_expired = not_expired("pages", "?4"),
                    ),
                    params![
                        workspace_id.as_bytes(),
                        project_id.as_bytes(),
                        cutoff_us,
                        now_us
                    ],
                    |row| row.get(0),
                )
                .optional()?;
            u64::try_from(n.unwrap_or(0)).unwrap_or(0)
        },
    })
}

/// `visible` is a [`readable_repository_predicate`] over `project_id`, or
/// empty; every table counted here carries that column.
fn window_activity_workspace(
    conn: &Connection,
    days: u32,
    cutoff_us: i64,
    now_us: i64,
    workspace_id: WorkspaceId,
    visible: &str,
) -> StoreResult<ActivityWindow> {
    let count_since = |sql: &str| -> StoreResult<u64> {
        let n: Option<i64> = conn
            .query_row(sql, params![workspace_id.as_bytes(), cutoff_us], |row| {
                row.get(0)
            })
            .optional()?;
        Ok(u64::try_from(n.unwrap_or(0)).unwrap_or(0))
    };
    Ok(ActivityWindow {
        days,
        sessions: count_since(&format!(
            "SELECT COUNT(*) FROM sessions WHERE workspace_id = ?1 AND started_at > ?2{visible}"
        ))?,
        observations: count_since(&format!(
            "SELECT COUNT(*) FROM observations WHERE workspace_id = ?1 AND created_at > ?2{visible}"
        ))?,
        // See the TTL note in `window_activity`; the guard needs a third bind,
        // so this one statement does not go through `count_since`.
        pages_updated: {
            let n: Option<i64> = conn
                .query_row(
                    &format!(
                        "SELECT COUNT(*) FROM pages WHERE workspace_id = ?1 AND is_latest = 1 \
                         AND updated_at > ?2{visible}{not_expired}",
                        not_expired = not_expired("pages", "?3"),
                    ),
                    params![workspace_id.as_bytes(), cutoff_us, now_us],
                    |row| row.get(0),
                )
                .optional()?;
            u64::try_from(n.unwrap_or(0)).unwrap_or(0)
        },
    })
}

/// Materialise one row from the briefing's recent-pages / rules queries
/// into a [`BriefingPage`]. The row shape is `(path, title, kind,
/// updated_at_us)` — all queries above MUST select those columns in
/// that order.
fn briefing_page_from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<StoreResult<BriefingPage>> {
    let path: String = row.get(0)?;
    let title: String = row.get(1)?;
    let kind: String = row.get(2)?;
    let updated_us: i64 = row.get(3)?;
    Ok(jiff::Timestamp::from_microsecond(updated_us)
        .map(|ts| BriefingPage {
            path,
            title,
            kind,
            updated_at: ts.to_string(),
        })
        .map_err(|e| {
            StoreError::Memory(ai_memory_core::MemoryError::MalformedRecord(format!(
                "bad updated_at: {e}"
            )))
        }))
}

/// Materialise one row from the briefing's `settled_first` query into a
/// [`SettledPage`]. The row shape is `(path, title, kind,
/// evidence_count)`.
fn settled_page_from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<SettledPage> {
    let path: String = row.get(0)?;
    let title: String = row.get(1)?;
    let kind: String = row.get(2)?;
    let evidence_count: i64 = row.get(3)?;
    Ok(SettledPage {
        path,
        title,
        kind,
        evidence_count: u32::try_from(evidence_count).unwrap_or(u32::MAX),
    })
}

/// Reject cwds that can't safely participate in a `repo_path` prefix
/// match. Trailing slash is already trimmed by the caller; this catches:
/// empty / single-slash / dot-segments (a `/foo/../bar` resolved-by-LIKE
/// could match a stored `/foo` parent the cwd doesn't logically belong
/// to, since LIKE doesn't normalise paths). Treats any failure as "no
/// match" so the caller falls through to the safe create-by-basename path.
fn is_safe_cwd_for_prefix_match(cwd: &str) -> bool {
    if cwd.is_empty() || cwd == "/" {
        return false;
    }
    for segment in cwd.split('/') {
        if segment == "." || segment == ".." {
            return false;
        }
    }
    true
}

fn has_trailing_path_separator(path: &str) -> bool {
    path.len() > 1 && path.ends_with(['/', '\\'])
}

fn checkout(inner: &Inner) -> StoreResult<Connection> {
    {
        let mut pool = inner.pool.lock();
        if pool.closed {
            return Err(StoreError::ReaderClosed);
        }
        if let Some(conn) = pool.idle.pop() {
            return Ok(conn);
        }
    }
    open_read_only(&inner.db_path)
}

fn checkin(inner: &Inner, conn: Connection) {
    let mut pool = inner.pool.lock();
    // A connection returned after `close` is dropped, not pooled: pooling it
    // would revive a reader the shutdown just released.
    if !pool.closed && pool.idle.len() < inner.soft_cap {
        pool.idle.push(conn);
    }
}

fn open_read_only(path: &Path) -> StoreResult<Connection> {
    let flags = OpenFlags::SQLITE_OPEN_READ_ONLY
        | OpenFlags::SQLITE_OPEN_URI
        | OpenFlags::SQLITE_OPEN_NO_MUTEX;
    let conn = Connection::open_with_flags(path, flags)?;
    conn.pragma_update(None, "busy_timeout", 5_000)?;
    Ok(conn)
}

#[cfg(test)]
mod tests {

    #[tokio::test]
    async fn answer_evidence_metadata_uses_session_time_only_in_the_same_scope() {
        use ai_memory_core::PageId;
        let tmp = tempfile::TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store.writer.get_or_create_workspace("local").await.unwrap();
        let project = store
            .writer
            .get_or_create_project(ws, "app", None)
            .await
            .unwrap();
        let other_project = store
            .writer
            .get_or_create_project(ws, "other", None)
            .await
            .unwrap();
        let other_ws = store.writer.get_or_create_workspace("other").await.unwrap();
        let other_ws_project = store
            .writer
            .get_or_create_project(other_ws, "app", None)
            .await
            .unwrap();
        let early = SessionId::new();
        let late = SessionId::new();
        let conn = rusqlite::Connection::open(store.db_path()).unwrap();
        for (id, started_at) in [(early, 100), (late, 200)] {
            conn.execute(
                "INSERT INTO sessions (id,workspace_id,project_id,agent_kind,started_at) VALUES (?1,?2,?3,'codex',?4)",
                rusqlite::params![id.as_bytes(),ws.as_bytes(),project.as_bytes(),started_at],
            ).unwrap();
        }
        let early_page = PageId::new();
        let late_page = PageId::new();
        let foreign_project_page = PageId::new();
        let foreign_workspace_page = PageId::new();
        for (id, workspace, project_id, session, updated_at) in [
            (early_page, ws, project, early, 900),
            (late_page, ws, project, late, 300),
            (foreign_project_page, ws, other_project, late, 700),
            (
                foreign_workspace_page,
                other_ws,
                other_ws_project,
                late,
                800,
            ),
        ] {
            conn.execute(
                "INSERT INTO pages (id,workspace_id,project_id,path,title,tier,body,body_sha256,created_at,updated_at) \
                 VALUES (?1,?2,?3,?4,'same topic','episodic','body',zeroblob(32),1,?5)",
                rusqlite::params![id.as_bytes(),workspace.as_bytes(),project_id.as_bytes(),format!("sessions/{session}.md"),updated_at],
            ).unwrap();
        }
        let metadata = store
            .reader
            .answer_evidence_metadata(vec![
                early_page,
                late_page,
                foreign_project_page,
                foreign_workspace_page,
            ])
            .await
            .unwrap();
        assert_eq!(metadata[&early_page].updated_at, 100);
        assert_eq!(metadata[&late_page].updated_at, 200);
        assert!(
            metadata[&late_page].updated_at > metadata[&early_page].updated_at,
            "session chronology wins despite the older session page being ingested later"
        );
        assert_eq!(
            metadata[&foreign_project_page].updated_at, 700,
            "same session filename in another project must use its own page timestamp"
        );
        assert_eq!(
            metadata[&foreign_workspace_page].updated_at, 800,
            "same session filename in another workspace must use its own page timestamp"
        );
    }

    #[tokio::test]
    async fn answer_evidence_metadata_returns_only_requested_ids_without_expanding_links() {
        use ai_memory_core::PageId;
        let tmp = tempfile::TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("admitted")
            .await
            .unwrap();
        let project = store
            .writer
            .get_or_create_project(ws, "app", None)
            .await
            .unwrap();
        let foreign_ws = store
            .writer
            .get_or_create_workspace("foreign")
            .await
            .unwrap();
        let foreign_project = store
            .writer
            .get_or_create_project(foreign_ws, "app", None)
            .await
            .unwrap();
        let requested = PageId::new();
        let unrelated = PageId::new();
        let foreign = PageId::new();
        let conn = rusqlite::Connection::open(store.db_path()).unwrap();
        for (id, workspace, project_id, title) in [
            (foreign, foreign_ws, foreign_project, "foreign title"),
            (requested, ws, project, "requested title"),
            (unrelated, ws, project, "unrequested title"),
        ] {
            conn.execute(
                "INSERT INTO pages (id,workspace_id,project_id,path,title,tier,body,body_sha256,created_at,updated_at) \
                 VALUES (?1,?2,?3,?4,?5,'semantic','body must not be loaded',zeroblob(32),1,123)",
                rusqlite::params![id.as_bytes(),workspace.as_bytes(),project_id.as_bytes(),id.to_string(),title],
            ).unwrap();
        }
        // Even malformed historical linkage must not expand the admitted set.
        conn.execute(
            "UPDATE pages SET supersedes=?1 WHERE id=?2",
            rusqlite::params![foreign.as_bytes(), requested.as_bytes()],
        )
        .unwrap();
        let metadata = store
            .reader
            .answer_evidence_metadata(vec![requested, requested, PageId::new()])
            .await
            .unwrap();
        assert_eq!(metadata.len(), 1);
        let row = &metadata[&requested];
        assert_eq!((row.workspace_id, row.project_id), (ws, project));
        assert_eq!(row.title, "requested title");
        assert_eq!(row.updated_at, 123);
        assert_eq!(row.supersedes, Some(foreign));
        assert!(!metadata.contains_key(&foreign));
        assert!(!metadata.contains_key(&unrelated));
        assert!(
            store
                .reader
                .answer_evidence_metadata(vec![])
                .await
                .unwrap()
                .is_empty()
        );
        assert!(matches!(
            store
                .reader
                .answer_evidence_metadata(vec![requested; 301])
                .await,
            Err(crate::StoreError::InvalidState(_))
        ));
    }

    /// `close` is a state, not a one-off sweep: a connection checked out
    /// before it is dropped on return, and nothing opens after it. The control
    /// half shows the same return pools the connection while the pool is open.
    #[test]
    fn a_closed_pool_drops_a_returned_connection_and_refuses_checkout() {
        use super::{ReaderPool, checkin, checkout};
        use crate::error::StoreError;

        let tmp = tempfile::TempDir::new().unwrap();
        let path = tmp.path().join("pool.sqlite");
        rusqlite::Connection::open(&path).unwrap();
        let pool = ReaderPool::new(&path, 4).unwrap();

        let open = checkout(&pool.inner).unwrap();
        checkin(&pool.inner, open);
        assert_eq!(pool.inner.pool.lock().idle.len(), 1, "control: pooled");

        let held = checkout(&pool.inner).unwrap();
        pool.close();
        assert_eq!(pool.inner.pool.lock().idle.len(), 0, "idle set released");
        checkin(&pool.inner, held);
        assert_eq!(
            pool.inner.pool.lock().idle.len(),
            0,
            "a connection returned after close was pooled again"
        );
        assert!(matches!(
            checkout(&pool.inner),
            Err(StoreError::ReaderClosed)
        ));
        pool.close();
    }

    /// The percentage is what an operator actually reads, and it divides by a
    /// figure that is zero on a fresh database.
    #[test]
    fn reclaimable_pct_is_zero_on_an_empty_database_rather_than_nan() {
        let empty = StorageStatus::default();
        assert_eq!(empty.database_bytes, 0);
        assert_eq!(empty.reclaimable_pct(), 0.0);
        assert!(empty.reclaimable_pct().is_finite(), "never NaN or inf");

        let quarter = StorageStatus {
            page_size: 4096,
            page_count: 400,
            freelist_count: 100,
            database_bytes: 400 * 4096,
            reclaimable_bytes: 100 * 4096,
            data_dir_free_bytes: None,
        };
        assert!((quarter.reclaimable_pct() - 25.0).abs() < f64::EPSILON);
    }

    /// The signal this field exists for: a store's own size says nothing
    /// about disk headroom, so `storage_status` must also report the
    /// filesystem's free space. A temp dir always has some, so this is
    /// `Some(n)` with `n > 0`, not just "doesn't crash".
    #[tokio::test]
    async fn storage_status_reports_filesystem_free_space() {
        let tmp = tempfile::TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let status = store.reader.storage_status().await.unwrap();
        let free = status
            .data_dir_free_bytes
            .expect("free space should be readable for a real temp dir");
        assert!(free > 0);
    }

    /// Stream timings are an explain-only surface: the normal path returns
    /// none (it reads no clock for them), the explained path times every
    /// stream that ran and leaves the rest out.
    #[tokio::test]
    async fn stream_timings_exist_only_on_the_explained_path() {
        let tmp = tempfile::TempDir::new().unwrap();
        let store = crate::Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "app", None)
            .await
            .unwrap();
        let search = |explain: bool| {
            store.reader.hybrid_search_inner(
                ws,
                proj,
                "anything".into(),
                None,
                String::new(),
                String::new(),
                0,
                5,
                None,
                explain,
                false,
                &OwnerFilter::Any,
                super::PageFilter::default(),
            )
        };
        let (_, off, _) = search(false).await.unwrap();
        assert_eq!(off, super::StreamTimings::default());
        let (_, on, _) = search(true).await.unwrap();
        assert!(on.fts_ms.is_some() && on.entity_ms.is_some() && on.graph_ms.is_some());
        assert!(on.observation_ms.is_some(), "the stream is on by default");
        assert!(on.vector_ms.is_none(), "no query vector, no vector scan");
        assert!(on.rerank_ms.is_none(), "the store never reranks");
    }

    #[test]
    fn stream_timings_accumulate_across_scopes() {
        let mut total = super::StreamTimings::default();
        total.accumulate(&super::StreamTimings {
            fts_ms: Some(1.5),
            ..Default::default()
        });
        total.accumulate(&super::StreamTimings {
            fts_ms: Some(2.0),
            graph_ms: Some(0.25),
            ..Default::default()
        });
        assert_eq!(total.fts_ms, Some(3.5));
        assert_eq!(total.graph_ms, Some(0.25));
        assert_eq!(
            total.vector_ms, None,
            "a stream that never ran stays absent"
        );
    }

    /// The single-scope manifest lookup the wiki resolves a new scope's
    /// `_meta.md` names from. It carries `repo_path`, and it is keyed by the
    /// full pair: a project id offered under the wrong workspace resolves to
    /// nothing rather than leaking the other workspace's name into a
    /// manifest.
    #[tokio::test]
    async fn scope_row_by_ids_returns_manifest_names_and_isolates_workspaces() {
        let tmp = tempfile::TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store.writer.get_or_create_workspace("acme").await.unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "webapp", Some("/repo/webapp".into()))
            .await
            .unwrap();
        let other_ws = store.writer.get_or_create_workspace("other").await.unwrap();

        let row = store
            .reader
            .scope_row_by_ids(ws, proj)
            .await
            .unwrap()
            .expect("the scope exists");
        assert_eq!(row.workspace_name, "acme");
        assert_eq!(row.project_name, "webapp");
        assert_eq!(row.repo_path.as_deref(), Some("/repo/webapp"));
        assert!(row.identity.is_none());
        assert!(row.identity_source.is_none());
        assert!(row.canonical_name.is_none());
        assert!(row.legacy_name.is_none());

        assert!(
            store
                .reader
                .scope_row_by_ids(other_ws, proj)
                .await
                .unwrap()
                .is_none(),
            "a project id under the wrong workspace resolves to nothing"
        );
        assert!(
            store
                .reader
                .scope_row_by_ids(ws, ai_memory_core::ProjectId::new())
                .await
                .unwrap()
                .is_none(),
            "an unknown project id is None, not an error"
        );
    }

    use super::{
        DESCRIPTOR_MAX_CHARS, StorageStatus, entity_query_tokens, handoff_listing_sql, like_escape,
        page_descriptor, page_descriptor_expr,
    };
    use crate::Store;

    #[test]
    fn a_metadata_styled_descriptor_source_is_echoed_verbatim() {
        // Every line here is a metadata bullet, so all of them are skipped
        // and nothing accumulates. The fallback then echoes the raw input —
        // the result is not empty, it is the unusable input reproduced whole.
        //
        // This is the failure mode for a writer that fills frontmatter
        // `summary` in the same house style it renders a session page's
        // metadata block in. Because `summary` wins the COALESCE, such a
        // page trades a usable body-derived descriptor for this, and nothing
        // anywhere reports an error. Writers must emit plain prose.
        let metadata_styled = "- **session_id:** `9f2c`\n- **observations:** 2";
        assert_eq!(
            page_descriptor(metadata_styled, "Some title"),
            metadata_styled
        );
    }

    use ai_memory_core::{
        AgentKind, Handoff, HandoffContent, HandoffId, HandoffLifecycle, HandoffOrigin,
        HandoffScope, HandoffState, NewHandoff, NewPage, NewSession, OwnerFilter, PageEvidence,
        PageEvidenceKind, PagePath, ProjectId, SessionId, Tier, WorkspaceId,
    };

    #[test]
    fn named_handoff_listing_uses_owner_index_for_both_ranges() {
        let tmp = tempfile::TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let conn = rusqlite::Connection::open(store.db_path()).unwrap();
        let ws = WorkspaceId::new();
        let proj = ProjectId::new();
        let (sql, owner) = handoff_listing_sql(false, &OwnerFilter::User("user:alice".into()), 50);
        let mut stmt = conn.prepare(&format!("EXPLAIN QUERY PLAN {sql}")).unwrap();
        let details = stmt
            .query_map(
                rusqlite::params![ws.as_bytes(), proj.as_bytes(), owner.unwrap()],
                |row| row.get::<_, String>(3),
            )
            .unwrap()
            .collect::<Result<Vec<_>, _>>()
            .unwrap();
        assert_eq!(
            details
                .iter()
                .filter(|detail| detail.contains("idx_handoffs_project_owner_recent"))
                .count(),
            2,
            "shared and owned ranges must both use the owner index: {details:?}"
        );
    }

    /// Every query plan step that reads observations through alias `o`.
    fn observation_probe_plan(
        conn: &rusqlite::Connection,
        sql: &str,
        named: &[(&str, &dyn rusqlite::ToSql)],
    ) -> (Vec<String>, Vec<String>) {
        let mut stmt = conn.prepare(&format!("EXPLAIN QUERY PLAN {sql}")).unwrap();
        let details = stmt
            .query_map(named, |row| row.get::<_, String>(3))
            .unwrap()
            .collect::<Result<Vec<_>, _>>()
            .unwrap();
        let probes = details
            .iter()
            .filter(|detail| detail.starts_with("SEARCH o "))
            .cloned()
            .collect();
        (details, probes)
    }

    #[test]
    fn session_observation_probes_use_the_session_index() {
        // A fresh store has no `sqlite_stat1`, the same state in which a
        // production store picked the project index and rescanned the whole
        // project per session.
        let tmp = tempfile::TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let conn = rusqlite::Connection::open(store.db_path()).unwrap();
        let ws = WorkspaceId::new();
        let proj = ProjectId::new();
        let sid = SessionId::new();
        let (ws_bytes, proj_bytes, sid_bytes) = (ws.as_bytes(), proj.as_bytes(), sid.as_bytes());
        let (since, actor, limit, offset) = (0_i64, "user:alice", 50_i64, 0_i64);
        let owners = [
            OwnerFilter::Any,
            OwnerFilter::User(actor.into()),
            OwnerFilter::Unattributed,
        ];
        let assert_session_bounded =
            |label: String, sql: &str, named: &[(&str, &dyn rusqlite::ToSql)]| {
                let (details, probes) = observation_probe_plan(&conn, sql, named);
                assert!(
                    !probes.is_empty()
                        && probes
                            .iter()
                            .all(|detail| detail.contains("idx_observations_session")),
                    "{label}: the observation probe must be bounded by session, not by \
                 project: {details:?}"
                );
            };
        for owner in &owners {
            let mut base: Vec<(&str, &dyn rusqlite::ToSql)> =
                vec![(":ws", &ws_bytes), (":proj", &proj_bytes)];
            if matches!(owner, OwnerFilter::User(_)) {
                base.push((":actor", &actor));
            }
            for has_since in [false, true] {
                let mut named = base.clone();
                if has_since {
                    named.push((":since", &since));
                }
                assert_session_bounded(
                    format!("by-agent since={has_since} owner={owner:?}"),
                    &super::session_counts_by_agent_sql(has_since, owner),
                    &named,
                );
            }
            for exact in [false, true] {
                for include_open in [false, true] {
                    let mut named = base.clone();
                    named.push((":limit", &limit));
                    named.push((":offset", &offset));
                    if exact {
                        named.push((":sid", &sid_bytes));
                    }
                    let sql = super::sessions_for_scope_sql(exact, owner, include_open);
                    let label =
                        format!("sessions exact={exact} open={include_open} owner={owner:?}");
                    // The point lookup has two probes (count and membership);
                    // both must use the session index.
                    if exact {
                        let (details, probes) = observation_probe_plan(&conn, &sql, &named);
                        assert_eq!(probes.len(), 2, "{label}: {details:?}");
                    }
                    assert_session_bounded(label, &sql, &named);
                }
            }
        }
    }

    #[test]
    fn interrupted_session_probes_use_the_session_index() {
        // Same fresh-store state as `session_observation_probes_use_the_session_index`:
        // without `sqlite_stat1` the planner answered these probes from the
        // project index, and every observation row rescanned the project and
        // searched its handoffs again (#1879).
        let tmp = tempfile::TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let conn = rusqlite::Connection::open(store.db_path()).unwrap();
        let (ws, proj, receiver) = (WorkspaceId::new(), ProjectId::new(), SessionId::new());
        let (ws_bytes, proj_bytes, receiver_bytes) =
            (ws.as_bytes(), proj.as_bytes(), receiver.as_bytes());
        let actor = "user:alice";
        let owners = [
            OwnerFilter::Any,
            OwnerFilter::User(actor.into()),
            OwnerFilter::Unattributed,
        ];
        for owner in &owners {
            for has_receiver in [false, true] {
                let mut named: Vec<(&str, &dyn rusqlite::ToSql)> =
                    vec![(":ws", &ws_bytes), (":proj", &proj_bytes)];
                if matches!(owner, OwnerFilter::User(_)) {
                    named.push((":actor", &actor));
                }
                if has_receiver {
                    named.push((":receiver", &receiver_bytes));
                }
                let sql = super::latest_interrupted_session_candidate_sql(owner, has_receiver);
                let mut stmt = conn.prepare(&format!("EXPLAIN QUERY PLAN {sql}")).unwrap();
                // (id, parent, detail) so a step's enclosing subqueries are known.
                let plan = stmt
                    .query_map(named.as_slice(), |row| {
                        Ok((
                            row.get::<_, i64>(0)?,
                            row.get::<_, i64>(1)?,
                            row.get::<_, String>(3)?,
                        ))
                    })
                    .unwrap()
                    .collect::<Result<Vec<_>, _>>()
                    .unwrap();
                let label = format!("owner={owner:?} receiver={has_receiver}");
                let observation_reads: Vec<&str> = plan
                    .iter()
                    .map(|(_, _, detail)| detail.as_str())
                    .filter(|detail| {
                        detail.contains("observations")
                            || ["o", "work"].iter().any(|alias| {
                                detail.starts_with(&format!("SEARCH {alias} "))
                                    || detail.starts_with(&format!("SCAN {alias}"))
                            })
                    })
                    .collect();
                assert!(
                    observation_reads.len() == 2
                        && observation_reads
                            .iter()
                            .all(|detail| detail.contains("idx_observations_session")),
                    "{label}: activity and work must each be one session-bounded probe: {plan:?}"
                );
                let handoff_reads: Vec<_> = plan
                    .iter()
                    .filter(|(_, _, detail)| detail.contains("handoffs"))
                    .collect();
                assert!(
                    handoff_reads.len() == 1 && handoff_reads[0].2.starts_with("SEARCH handoffs "),
                    "{label}: the scope's handoffs must be read once through a scope index: \
                     {plan:?}"
                );
                // Only a handoff at or after some candidate's newest work can
                // cover it; without the bound the read sorts the project's
                // whole handoff history.
                assert!(
                    handoff_reads[0].2.contains("created_at>?"),
                    "{label}: the handoffs read must be bounded by the oldest candidate work: \
                     {plan:?}"
                );
                let mut parent = handoff_reads[0].1;
                while let Some((_, up, detail)) = plan.iter().find(|(id, _, _)| *id == parent) {
                    assert!(
                        !detail.starts_with("CORRELATED"),
                        "{label}: handoffs must not be searched once per session: {plan:?}"
                    );
                    parent = *up;
                }
            }
        }
    }

    #[test]
    fn authority_candidate_window_is_bounded_and_saturating() {
        use super::authority_candidate_limit;

        assert_eq!(authority_candidate_limit(0), 0);
        assert_eq!(authority_candidate_limit(1), 20);
        assert_eq!(authority_candidate_limit(10), 40);
        assert_eq!(authority_candidate_limit(1_000), 1_300);
        assert_eq!(authority_candidate_limit(usize::MAX), usize::MAX);
    }

    /// Build an open handoff for the pure-selection tests. `manual` toggles
    /// the manual (`from_session_id == None`) vs auto distinction; `t` is the
    /// creation time in microseconds; `summary` doubles as a label to assert
    /// which handoff won.
    fn handoff(summary: &str, cwd: Option<&str>, manual: bool, t: i64) -> Handoff {
        Handoff {
            scope: HandoffScope {
                id: HandoffId::new(),
                workspace_id: WorkspaceId::new(),
                project_id: ProjectId::new(),
            },
            origin: HandoffOrigin {
                from_session_id: if manual { None } else { Some(SessionId::new()) },
                from_agent: AgentKind::ClaudeCode,
                to_agent: None,
                cwd: cwd.map(str::to_string),
                owner_user: None,
            },
            content: HandoffContent {
                summary: summary.to_string(),
                open_questions: vec![],
                next_steps: vec![],
                files_touched: vec![],
            },
            lifecycle: HandoffLifecycle {
                state: HandoffState::Open,
                created_at: jiff::Timestamp::from_microsecond(t).unwrap(),
                accepted_by: None,
                accepted_at: None,
                accepted_by_session: None,
                accepted_by_user: None,
            },
        }
    }

    fn pick(candidates: Vec<Handoff>, cwd: Option<&str>) -> String {
        super::select_open_handoff(candidates, cwd)
            .map_or_else(|| "—".to_string(), |h| h.content.summary)
    }

    #[test]
    fn cwd_within_respects_component_boundaries() {
        use super::cwd_within;
        assert!(cwd_within("/repo", "/repo"));
        assert!(cwd_within("/repo", "/repo/api"));
        assert!(cwd_within("/repo", "/repo/api/v2"));
        assert!(cwd_within("/repo/", "/repo/api")); // trailing slash normalized
        assert!(cwd_within("/", "/anything/here"));
        assert!(!cwd_within("/repo", "/repo-other")); // sibling, not descendant
        assert!(!cwd_within("/repo", "/repository")); // longer name, not a child
        assert!(!cwd_within("/repo/api", "/repo")); // parent is not within child
    }

    #[test]
    fn cwd_within_handles_windows_backslash_boundaries() {
        use super::cwd_within;
        assert!(cwd_within(r"C:\repo", r"C:\repo\api"));
        assert!(cwd_within(r"C:\repo\", r"C:\repo\api"));
        assert!(!cwd_within(r"C:\repo", r"C:\repo-other"));
    }

    /// Docker Desktop runs the server on Linux while hook cwd is a Windows
    /// host path. Explorer, Git, and PowerShell disagree on drive-letter
    /// case, so a byte-exact compare misses the auto-handoff and the
    /// repo_path prefix match for the same directory.
    #[test]
    fn cwd_within_windows_drive_letter_is_case_insensitive() {
        use super::cwd_within;
        assert!(cwd_within(r"C:\Users\alice\repo", r"c:\users\alice\repo"));
        assert!(cwd_within(
            r"C:\Users\alice\repo",
            r"c:\Users\alice\repo\src"
        ));
        assert!(!cwd_within(
            r"C:\Users\alice\repo",
            r"c:\Users\alice\repo-other"
        ));
        // Unix paths stay case-sensitive: /Repo and /repo are different dirs.
        assert!(!cwd_within("/Repo", "/repo"));
        assert!(!cwd_within("/Repo", "/repo/src"));
    }

    // The realistic scenario matrix (see the cwd the SessionEnd hook injects):
    // a manual handoff is cwd=NULL, an auto handoff carries the session cwd.

    #[test]
    fn handoff_manual_beats_auto_same_dir() {
        // The reported bug: a detailed manual handoff must win over the vague
        // SessionEnd auto handoff even though the auto one is newer.
        let c = vec![
            handoff("MAN-detail", None, true, 1),
            handoff("auto-vague", Some("/repo"), false, 2),
        ];
        assert_eq!(pick(c, Some("/repo")), "MAN-detail");
    }

    #[test]
    fn handoff_auto_reaches_subdir() {
        let c = vec![handoff("auto", Some("/repo"), false, 1)];
        assert_eq!(pick(c, Some("/repo/api")), "auto");
    }

    #[test]
    fn handoff_manual_survives_from_subdir() {
        let c = vec![
            handoff("MAN-detail", None, true, 1),
            handoff("auto-vague", Some("/repo"), false, 2),
        ];
        assert_eq!(pick(c, Some("/repo/api")), "MAN-detail");
    }

    #[test]
    fn handoff_tolerates_trailing_slash_in_session_cwd() {
        let c = vec![handoff("auto", Some("/repo"), false, 1)];
        assert_eq!(pick(c, Some("/repo/")), "auto");
    }

    #[test]
    fn handoff_lone_manual_is_delivered() {
        let c = vec![handoff("MAN", None, true, 1)];
        assert_eq!(pick(c, Some("/repo")), "MAN");
    }

    #[test]
    fn handoff_newest_manual_wins_even_if_older_manual_has_cwd() {
        // An older manual that happens to carry a cwd must NOT outrank the
        // newest manual just because its cwd string is longer. The cwd
        // specificity tiebreak applies only to auto handoffs; among manuals the
        // newest wins. (Regression seen in real data: a cwd-bearing manual was
        // delivered ahead of the newer cwd-less one.)
        let c = vec![
            handoff(
                "old-with-cwd",
                Some("/var/home/luka/Trabalho/waba/bsp-core"),
                true,
                1,
            ),
            handoff("newest-null", None, true, 2),
        ];
        assert_eq!(
            pick(c, Some("/var/home/luka/Trabalho/waba/bsp-core")),
            "newest-null"
        );
    }

    #[test]
    fn handoff_manual_with_nonmatching_cwd_still_beats_auto() {
        // Even if the model passed a cwd on the manual handoff that does not
        // match the next session's dir, the manual handoff is project-wide and
        // still wins over the auto one. Deterministic on from_session_id, not
        // on the manual handoff happening to have a NULL cwd.
        let c = vec![
            handoff("MAN", Some("/some/other/place"), true, 1),
            handoff("auto", Some("/repo"), false, 2),
        ];
        assert_eq!(pick(c, Some("/repo")), "MAN");
    }

    #[test]
    fn handoff_sibling_subdirs_do_not_leak() {
        // A /mono/web session must not receive the /mono/api handoff, even
        // though that sibling handoff is newer.
        let c = vec![
            handoff("web", Some("/mono/web"), false, 1),
            handoff("api", Some("/mono/api"), false, 2),
        ];
        assert_eq!(pick(c, Some("/mono/web")), "web");
    }

    #[test]
    fn handoff_dangerous_prefix_never_matches() {
        let c = vec![handoff("repo", Some("/repo"), false, 1)];
        assert_eq!(pick(c, Some("/repo-other")), "—");
    }

    #[test]
    fn handoff_newer_parent_beats_stale_specific_ancestor() {
        let c = vec![
            handoff("a", Some("/a"), false, 2),
            handoff("ab", Some("/a/b"), false, 1),
        ];
        assert_eq!(pick(c, Some("/a/b/c")), "a");
    }

    #[test]
    fn handoff_legacy_trailing_slash_does_not_beat_newer_equivalent_auto() {
        let c = vec![
            handoff("old-slash", Some("/repo/"), false, 1),
            handoff("new-no-slash", Some("/repo"), false, 2),
        ];
        assert_eq!(pick(c, Some("/repo/api")), "new-no-slash");
    }

    #[test]
    fn handoff_wildcard_characters_are_literal_path_components() {
        let c = vec![
            handoff("percent", Some("/repo/%"), false, 2),
            handoff("underscore", Some("/repo/_x"), false, 3),
            handoff("repo", Some("/repo"), false, 1),
        ];
        assert_eq!(pick(c.clone(), Some("/repo/abc")), "repo");
        assert_eq!(pick(c, Some("/repo/ax")), "repo");
    }

    #[test]
    fn handoff_parent_session_does_not_inherit_deep_handoff() {
        // A handoff left deep in /repo/api is not delivered to a /repo session.
        let c = vec![handoff("deep", Some("/repo/api"), false, 1)];
        assert_eq!(pick(c, Some("/repo")), "—");
    }

    #[test]
    fn handoff_none_filter_is_project_wide() {
        // The web overview passes no cwd: every open handoff is a candidate,
        // manual still preferred.
        let c = vec![
            handoff("auto-deep", Some("/repo/api"), false, 1),
            handoff("MAN", None, true, 2),
        ];
        assert_eq!(pick(c, None), "MAN");
    }

    #[tokio::test]
    async fn latest_open_handoff_preserves_workspace_project_isolation() {
        let tmp = tempfile::TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws_a = store.writer.get_or_create_workspace("a").await.unwrap();
        let ws_b = store.writer.get_or_create_workspace("b").await.unwrap();
        let proj_a = store
            .writer
            .get_or_create_project(ws_a, "same-name", None)
            .await
            .unwrap();
        let proj_b = store
            .writer
            .get_or_create_project(ws_b, "same-name", None)
            .await
            .unwrap();

        store
            .writer
            .insert_handoff(NewHandoff {
                workspace_id: ws_b,
                project_id: proj_b,
                from_session_id: None,
                from_agent: AgentKind::ClaudeCode,
                to_agent: None,
                cwd: None,
                summary: "wrong workspace".into(),
                open_questions: vec![],
                next_steps: vec![],
                files_touched: vec![],
                owner_user: None,
            })
            .await
            .unwrap();
        store
            .writer
            .insert_handoff(NewHandoff {
                workspace_id: ws_a,
                project_id: proj_a,
                from_session_id: None,
                from_agent: AgentKind::ClaudeCode,
                to_agent: None,
                cwd: None,
                summary: "right project".into(),
                open_questions: vec![],
                next_steps: vec![],
                files_touched: vec![],
                owner_user: None,
            })
            .await
            .unwrap();

        let handoff = store
            .reader
            .latest_open_handoff(
                ws_a,
                proj_a,
                Some("/repo".into()),
                ai_memory_core::OwnerFilter::Any,
            )
            .await
            .unwrap()
            .unwrap();
        assert_eq!(handoff.content.summary, "right project");
    }

    #[tokio::test]
    async fn accepting_newest_auto_expires_only_older_matching_autos() {
        let tmp = tempfile::TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "repo", Some("/repo".into()))
            .await
            .unwrap();

        async fn insert_auto(
            store: &Store,
            workspace_id: WorkspaceId,
            project_id: ProjectId,
            cwd: &str,
            summary: &str,
        ) -> HandoffId {
            let session_id = SessionId::new();
            store
                .writer
                .begin_session(NewSession {
                    occurred_at: None,
                    id: session_id,
                    workspace_id,
                    project_id,
                    agent_kind: AgentKind::ClaudeCode,
                    cwd: Some(cwd.into()),
                    actor_user: None,
                })
                .await
                .unwrap();
            let id = store
                .writer
                .insert_handoff(NewHandoff {
                    workspace_id,
                    project_id,
                    from_session_id: Some(session_id),
                    from_agent: AgentKind::ClaudeCode,
                    to_agent: None,
                    cwd: Some(cwd.into()),
                    summary: summary.into(),
                    open_questions: vec![],
                    next_steps: vec![],
                    files_touched: vec![],
                    owner_user: None,
                })
                .await
                .unwrap();
            // A SessionEnd baton: its source is over.
            store.writer.end_session(session_id, None).await.unwrap();
            id
        }

        let superseded_same_cwd =
            insert_auto(&store, ws, proj, "/repo/api", "older same cwd").await;
        tokio::time::sleep(std::time::Duration::from_millis(2)).await;
        let stale_specific = insert_auto(&store, ws, proj, "/repo/api", "stale specific").await;
        assert_eq!(
            store
                .reader
                .handoff_by_id(superseded_same_cwd)
                .await
                .unwrap()
                .unwrap()
                .lifecycle
                .state,
            HandoffState::Expired,
            "a newer auto from the exact cwd must bound pre-accept accumulation"
        );
        tokio::time::sleep(std::time::Duration::from_millis(2)).await;
        let newest_parent = insert_auto(&store, ws, proj, "/repo", "newest parent").await;
        let sibling = insert_auto(&store, ws, proj, "/repo/web", "sibling").await;

        let selected = store
            .reader
            .latest_open_handoff(
                ws,
                proj,
                Some("/repo/api/src".into()),
                ai_memory_core::OwnerFilter::Any,
            )
            .await
            .unwrap()
            .unwrap();
        assert_eq!(
            selected.scope.id, newest_parent,
            "newest eligible auto must win"
        );

        // A manual handoff appearing between selection and acceptance must not
        // be swept by automatic-handoff cleanup.
        let manual = store
            .writer
            .insert_handoff(NewHandoff {
                workspace_id: ws,
                project_id: proj,
                from_session_id: None,
                from_agent: AgentKind::Codex,
                to_agent: None,
                cwd: None,
                summary: "manual".into(),
                open_questions: vec![],
                next_steps: vec![],
                files_touched: vec![],
                owner_user: None,
            })
            .await
            .unwrap();
        store
            .writer
            .accept_handoff(ai_memory_core::HandoffAcceptance {
                handoff_id: selected.scope.id,
                workspace_id: ws,
                project_id: proj,
                accepting_agent: AgentKind::Codex,
                accepting_session: None,
                accepting_user: None,
                owner_filter: ai_memory_core::OwnerFilter::Any,
                receiving_cwd: Some("/repo/api/src".into()),
            })
            .await
            .unwrap();

        assert_eq!(
            store
                .reader
                .handoff_by_id(stale_specific)
                .await
                .unwrap()
                .unwrap()
                .lifecycle
                .state,
            HandoffState::Expired
        );
        assert_eq!(
            store
                .reader
                .handoff_by_id(newest_parent)
                .await
                .unwrap()
                .unwrap()
                .lifecycle
                .state,
            HandoffState::Accepted
        );
        for untouched in [sibling, manual] {
            assert_eq!(
                store
                    .reader
                    .handoff_by_id(untouched)
                    .await
                    .unwrap()
                    .unwrap()
                    .lifecycle
                    .state,
                HandoffState::Open
            );
        }
    }

    /// A stored `repo_path` equal to the operator's `$HOME` must never be
    /// prefix-matched: such a row would be a catch-all parent for every
    /// project beneath the home directory. A normal nested repo under
    /// `$HOME` must still match.
    #[tokio::test]
    async fn prefix_match_skips_home_dir_but_keeps_nested_repo() {
        let tmp = tempfile::TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        // A "$HOME catch-all" project whose repo_path is the home dir.
        store
            .writer
            .get_or_create_project(ws, "home", Some(String::from("/home/tester")))
            .await
            .unwrap();
        // A real nested repo beneath the home dir.
        let app_id = store
            .writer
            .get_or_create_project(ws, "app", Some(String::from("/home/tester/projects/app")))
            .await
            .unwrap();

        // A cwd somewhere under $HOME but not under any real repo must NOT
        // resolve to the $HOME catch-all row.
        let matched = store
            .reader
            .find_project_by_cwd_prefix(
                ws,
                String::from("/home/tester/random/dir"),
                Some("/home/tester"),
            )
            .await
            .unwrap();
        assert_eq!(
            matched, None,
            "a stored repo_path equal to $HOME must never be prefix-matched"
        );

        // A cwd inside a genuine nested repo still resolves to that repo.
        let matched = store
            .reader
            .find_project_by_cwd_prefix(
                ws,
                String::from("/home/tester/projects/app/src"),
                Some("/home/tester"),
            )
            .await
            .unwrap();
        assert_eq!(
            matched.map(|(id, _)| id),
            Some(app_id),
            "a genuine nested repo under $HOME must still prefix-match"
        );
    }

    #[tokio::test]
    async fn prefix_match_treats_percent_and_underscore_as_literal_path_bytes() {
        let tmp = tempfile::TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let literal_id = store
            .writer
            .get_or_create_project(
                ws,
                "literal",
                Some(String::from("/tmp/ai_memory_%literal/repo_under")),
            )
            .await
            .unwrap();

        let matched = store
            .reader
            .find_project_by_cwd_prefix(
                ws,
                String::from("/tmp/ai_memory_%literal/repo_under/src"),
                None,
            )
            .await
            .unwrap();
        assert_eq!(matched.map(|(id, _)| id), Some(literal_id));

        let widened = store
            .reader
            .find_project_by_cwd_prefix(
                ws,
                String::from("/tmp/aiXmemory_Aliteral/repoXunder/src"),
                None,
            )
            .await
            .unwrap();
        assert_eq!(widened, None, "wildcards in repo_path must stay literal");
    }

    #[tokio::test]
    async fn prefix_match_handles_legacy_windows_backslash_repo_path() {
        let tmp = tempfile::TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let project_id = ProjectId::new();
        let conn =
            rusqlite::Connection::open(tmp.path().join("db").join(crate::DB_FILENAME)).unwrap();
        conn.execute(
            "INSERT INTO projects (id, workspace_id, name, repo_path, created_at) \
             VALUES (?1, ?2, ?3, ?4, ?5)",
            rusqlite::params![
                project_id.as_bytes(),
                ws.as_bytes(),
                "app",
                r"C:\Users\tester\app",
                jiff::Timestamp::now().as_microsecond()
            ],
        )
        .unwrap();

        let matched = store
            .reader
            .find_project_by_cwd_prefix(
                ws,
                String::from("C:/Users/tester/app/crates/core"),
                Some(r"C:\Users\tester"),
            )
            .await
            .unwrap();

        assert_eq!(matched.map(|(id, _)| id), Some(project_id));
    }

    #[tokio::test]
    async fn prefix_match_ignores_legacy_trailing_separator_repo_path() {
        let tmp = tempfile::TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let project_id = ProjectId::new();
        let conn =
            rusqlite::Connection::open(tmp.path().join("db").join(crate::DB_FILENAME)).unwrap();
        conn.execute(
            "INSERT INTO projects (id, workspace_id, name, repo_path, created_at) \
             VALUES (?1, ?2, ?3, ?4, ?5)",
            rusqlite::params![
                project_id.as_bytes(),
                ws.as_bytes(),
                "legacy-trailing",
                "/repo/foo/",
                jiff::Timestamp::now().as_microsecond()
            ],
        )
        .unwrap();

        let matched = store
            .reader
            .find_project_by_cwd_prefix(ws, String::from("/repo/foo/bar"), None)
            .await
            .unwrap();

        assert_eq!(matched, None, "legacy trailing separator must not match");
    }

    #[test]
    fn entity_query_tokens_lowercases_filters_short_and_bounds() {
        // A compound token yields the whole form AND its parts, so a
        // query can spell an entity `writer-actor` or `writer actor`.
        assert_eq!(
            entity_query_tokens("How does the Writer-Actor use SQLite?"),
            vec![
                "how".to_string(),
                "does".to_string(),
                "the".to_string(),
                "writer-actor".to_string(),
                "writer".to_string(),
                "actor".to_string(),
                "use".to_string(),
                "sqlite".to_string(),
            ],
        );
        assert!(
            entity_query_tokens("a of an X").is_empty(),
            "sub-3-char tokens are noise for prefix matching",
        );
        assert_eq!(
            entity_query_tokens("dup dup dup"),
            vec!["dup".to_string()],
            "tokens de-duplicate",
        );
        assert!(entity_query_tokens(&"word ".repeat(50)).len() <= 12);
        assert!(
            entity_query_tokens(&"x".repeat(1_000_000)).is_empty(),
            "an oversized untrusted token must be rejected before lowercase allocation"
        );
        assert_eq!(
            entity_query_tokens(&format!("{} usable", "x".repeat(1_000_000))),
            vec!["usable".to_string()],
            "a rejected compound must not hide later bounded tokens"
        );
    }

    #[test]
    fn like_escape_neutralises_wildcards() {
        // `_` is LIKE's single-char wildcard and appears in real entity
        // names (`writer_actor`), so it must not match `writerxactor`.
        assert_eq!(like_escape("writer_actor"), "writer\\_actor");
        assert_eq!(like_escape("100%"), "100\\%");
        assert_eq!(like_escape("back\\slash"), "back\\\\slash");
        assert_eq!(like_escape("plain-name"), "plain-name");
    }

    #[test]
    fn page_descriptor_skips_heading_and_rule_lines() {
        let body = concat!(
            "# Session 2026-04-20\n",
            "\n",
            "---\n",
            "\n",
            "## Summary\n",
            "\n",
            "Switched the scheduler to a single writer actor.\n",
        );
        assert_eq!(
            page_descriptor(body, ""),
            "Switched the scheduler to a single writer actor."
        );
    }

    #[test]
    fn page_descriptor_fills_the_budget_across_prose_lines() {
        // A short opening line must not cost the rest of the budget: the
        // `_lint` pages open with "N finding(s)." and everything that tells
        // you what the findings were comes after it.
        let body = concat!(
            "# Lint findings\n",
            "\n",
            "501 finding(s).\n",
            "\n",
            "## 1 - stale (info)\n",
            "\n",
            "Episodic page sessions/e24f6fbc.md is 30 days old with zero accesses.\n",
        );
        assert_eq!(
            page_descriptor(body, ""),
            "501 finding(s). Episodic page sessions/e24f6fbc.md is 30 days old \
             with zero accesses."
        );
    }

    #[test]
    fn page_descriptor_falls_back_to_raw_text_when_all_lines_are_structural() {
        assert_eq!(page_descriptor("# Only a title\n", ""), "# Only a title");
        assert_eq!(page_descriptor("   ", ""), "");
    }

    #[test]
    fn page_descriptor_skips_metadata_bullets_and_the_repeated_title() {
        // The compiled session-page shape: the title again as prompt 1, with
        // the metadata block in between. What the reader does not already
        // have is prompt 2 onward.
        let title = "vamos revisar o deploy";
        let body = concat!(
            "# vamos revisar o deploy\n",
            "\n",
            "## Session metadata\n",
            "\n",
            "- **session_id:** `4e79a7ce-55e9-44c1-bcb5-74a6fe740900`\n",
            "- **started_at:** 2026-08-22T19:26:07Z\n",
            "- **observations:** 59\n",
            "\n",
            "## Prompts\n",
            "\n",
            "1. vamos revisar o deploy\n",
            "2. o rollback falhou no passo do migrate\n",
        );
        assert_eq!(
            page_descriptor(body, title),
            "o rollback falhou no passo do migrate"
        );
    }

    #[test]
    fn page_descriptor_keeps_a_line_that_only_starts_with_a_complete_title() {
        // `truncate_for_title` appends the ellipsis only past 80 chars, so a
        // title without one is complete. A longer line that merely opens with
        // it is a different sentence, not a repeat.
        let title = "vamos revisar o deploy";
        let body = "# vamos revisar o deploy\n\n1. vamos revisar o deploy\n2. vamos revisar o deploy e o rollback do migrate\n";
        assert_eq!(
            page_descriptor(body, title),
            "vamos revisar o deploy e o rollback do migrate"
        );
    }

    #[test]
    fn page_descriptor_matches_a_title_truncated_with_an_ellipsis() {
        let title = "vamos revisar o deploy do SHVIA-WEB e o rollback\u{2026}";
        let body = "# x\n\n1. vamos revisar o deploy do SHVIA-WEB e o rollback do migrate\n2. depois o resto\n";
        assert_eq!(page_descriptor(body, title), "depois o resto");
    }

    #[test]
    fn page_descriptor_truncates_on_a_character_boundary() {
        let body = "\u{e7}".repeat(DESCRIPTOR_MAX_CHARS + 10);
        let out = page_descriptor(&body, "");
        assert_eq!(out.chars().count(), DESCRIPTOR_MAX_CHARS);
        assert!(out.ends_with('\u{2026}'));
    }

    #[test]
    fn page_descriptor_expr_prefers_a_non_blank_frontmatter_summary() {
        let sql = page_descriptor_expr("pages.body", "pages.frontmatter_json");
        assert!(sql.contains("json_extract(pages.frontmatter_json, '$.summary')"));
        assert!(sql.contains("NULLIF(TRIM("));
        assert!(sql.contains("substr(pages.body, 1, 600)"));
    }

    fn evidence_test_page(ws: WorkspaceId, proj: ProjectId, path: &str) -> NewPage {
        NewPage {
            workspace_id: ws,
            project_id: proj,
            path: PagePath::new(path).unwrap(),
            title: "test".into(),
            body: "body".into(),
            tier: Tier::Semantic,
            frontmatter_json: serde_json::json!({}),
            pinned: false,
            links: Vec::new(),
            author_id: None,
            expires_at: None,
            entities: Vec::new(),
            evidence: Vec::new(),
        }
    }

    /// The web dashboard's per-page agent badge: the harness whose
    /// session most recently cited a page as evidence. Only the *latest*
    /// citation should win when a page has been touched by more than one
    /// agent, and a page with no session evidence at all must be absent
    /// from the map rather than reported as some default.
    #[tokio::test]
    async fn latest_page_agent_kinds_prefers_the_most_recent_session_citation() {
        let tmp = tempfile::TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store.writer.get_or_create_workspace("acme").await.unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "webapp", None)
            .await
            .unwrap();

        let codex_session = SessionId::new();
        store
            .writer
            .begin_session(NewSession {
                occurred_at: None,
                id: codex_session,
                workspace_id: ws,
                project_id: proj,
                agent_kind: AgentKind::Codex,
                cwd: None,
                actor_user: None,
            })
            .await
            .unwrap();
        let claude_session = SessionId::new();
        store
            .writer
            .begin_session(NewSession {
                occurred_at: None,
                id: claude_session,
                workspace_id: ws,
                project_id: proj,
                agent_kind: AgentKind::ClaudeCode,
                cwd: None,
                actor_user: None,
            })
            .await
            .unwrap();

        // Cited first by Codex, then by Claude Code — the join must report
        // the later one, not the first or an arbitrary one.
        let mut page = evidence_test_page(ws, proj, "concepts/attribution.md");
        page.evidence = vec![PageEvidence {
            kind: PageEvidenceKind::Session,
            source_id: codex_session.to_string(),
        }];
        store.writer.upsert_page(page.clone()).await.unwrap();
        page.evidence = vec![PageEvidence {
            kind: PageEvidenceKind::Session,
            source_id: claude_session.to_string(),
        }];
        store.writer.upsert_page(page).await.unwrap();

        // A hand-written page with no session evidence at all.
        let unattributed = evidence_test_page(ws, proj, "concepts/no-evidence.md");
        store.writer.upsert_page(unattributed).await.unwrap();

        let by_path = store
            .reader
            .latest_page_agent_kinds("acme", "webapp")
            .await
            .unwrap();
        assert_eq!(
            by_path.get("concepts/attribution.md"),
            Some(&AgentKind::ClaudeCode),
            "the later citation must win"
        );
        assert!(
            !by_path.contains_key("concepts/no-evidence.md"),
            "a page with no session evidence must be absent, not defaulted"
        );
    }
}