Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! 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("&"),
'<' => out.push_str("<"),
'>' => out.push_str(">"),
'"' => out.push_str("""),
'\'' => out.push_str("'"),
_ => 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"
);
}
}