Skip to content

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

Rust

fix(query): retain newer corrections and prefer complete evidence

Mihael Zamin Sousacaeeea0353ee
diff --cc CHANGELOG.md
index ba1b91c4,3fc46553..43b8f09b
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -13,11 -13,20 +13,27 @@@ version in [`docs/changelog/`](docs/cha
### Added
+- Added an optional `[query_answer] max_context_tokens` admission budget for
+ answer synthesis. It preserves retrieval hits, reports omitted or clipped
- evidence, and skips the model when no meaningful evidence fits. The default
++ evidence, prioritizes known newer corrections, prefers whole snippets and
++ clips only complete trailing sentences or statements into leftover space. It
++ skips the model when no meaningful evidence fits. The default
+ remains disabled (#1684).
+
+ - `GET /admin/status` and `ai-memory status --json` now carry a
+ `consolidation` block: the queue counts plus up to 20 `failed_sessions`
+ (`session_id`, `attempts`, `failed_at_us`, scrubbed `last_error`), newest
+ first. A consolidation run that gives up after its retries now has a
+ machine-readable record with the session ids needed to re-run it, instead of
+ only a journal line and the `/health` panel's count — which also resets with
+ the process. The web health panel's own view stays counts-only, and an older
+ server's status shape is unchanged (#1692).
+
+ - Added the bundled `coding-v1` retrieval-evaluation corpus for offline checks
+ of decision rationale, resolved-error causes, correction evidence, and late
+ session details. It reuses the existing scorer and A/B reports; it measures
+ evidence retrieval, not semantic answer correctness or handoff behavior (#1686).
+
- `[auto_improve.eval] builtin = "structure"` runs the eval gate's structural
checks in process, so the gate needs no interpreter, no scorer script inside
the container and no timeout to hit. It checks an H1, an upper-case
diff --cc README.md
index b24a40ab,7137d1cc..115ca43a
--- a/README.md
+++ b/README.md
@@@ -687,12 -687,6 +687,13 @@@ for consolidation; OpenAI, Voyage, Gemi
endpoints for embeddings. Configuration lives in
[`docs/llm-providers.md`](docs/llm-providers.md).
+For optional synthesized query answers, operators can set
+`[query_answer] max_context_tokens` to limit admitted evidence while retaining
- all retrieval hits. It is disabled by default. See the
++all retrieval hits. Known newer corrections take priority, and whole snippets
++are preferred over sentence-bounded fragments. It is disabled by default. See the
+[configuration reference](docs/ARCHITECTURE.md#configuration-configtoml) for the
+conservative counting rule and omission receipt.
+
## Architecture
One Rust binary runs an MCP/HTTP server and owns one data directory:
diff --cc crates/ai-memory-mcp/src/server.rs
index 17b26c1a,57e2ee24..10708e50
--- a/crates/ai-memory-mcp/src/server.rs
+++ b/crates/ai-memory-mcp/src/server.rs
@@@ -822,6 -819,6 +822,8 @@@ struct QueryHit
hit: ai_memory_store::PageHit,
#[serde(skip_serializing_if = "Option::is_none")]
score_details: Option<ai_memory_store::SearchExplain>,
++ #[serde(skip)]
++ evidence: Option<ai_memory_store::AnswerEvidenceMeta>,
}
impl From<ai_memory_store::PageHit> for QueryHit {
@@@ -829,6 -826,6 +831,7 @@@
Self {
hit,
score_details: None,
++ evidence: None,
}
}
}
@@@ -2999,6 -2981,6 +3002,7 @@@ impl AiMemoryServer
.map(|(hit, details)| QueryHit {
hit,
score_details: details,
++ evidence: None,
})
.collect(),
answer: None,
@@@ -3181,7 -3162,7 +3185,11 @@@
bump_actor.as_ref(),
);
hits.into_iter()
-- .map(|(hit, score_details)| QueryHit { hit, score_details })
++ .map(|(hit, score_details)| QueryHit {
++ hit,
++ score_details,
++ evidence: None,
++ })
.collect()
}
}
@@@ -3251,10 -3232,10 +3259,13 @@@
hits.iter().map(|(h, _)| h.id).collect(),
bump_actor.as_ref(),
);
-- global_scope_hits.extend(
-- hits.into_iter()
-- .map(|(hit, score_details)| QueryHit { hit, score_details }),
-- );
++ global_scope_hits.extend(hits.into_iter().map(|(hit, score_details)| {
++ QueryHit {
++ hit,
++ score_details,
++ evidence: None,
++ }
++ }));
}
Ok(_) => {}
Err(e) => {
@@@ -3269,6 -3250,6 +3280,7 @@@
.map(|(hit, score_details)| QueryHit {
hit,
score_details: score_details.filter(|_| explain),
++ evidence: None,
})
.collect();
// Pin before search: when the caller opts in AND this is a
@@@ -3278,7 -3259,7 +3290,7 @@@
// the query appears once, and the combined list is re-truncated to the
// requested limit so the total stays bounded. Default off → this branch
// never runs and the ordering is byte-identical.
-- let hits = if args.pin_first.unwrap_or(false) && resolved_scopes.is_none() {
++ let mut hits = if args.pin_first.unwrap_or(false) && resolved_scopes.is_none() {
let (ws, proj) = self
.effective_ids_for_read_args_with_actor(
args.workspace.as_deref(),
@@@ -3315,7 -3295,7 +3327,25 @@@
let (answer, answer_unavailable) = if args.answer.unwrap_or(false) {
match self.llm.as_ref() {
Some(llm) => {
- let (request, sources) = build_answer_request(
++ if self
++ .answer_max_context_tokens
++ .is_some_and(|limit| limit > 0)
++ {
++ let ids = hits
++ .iter()
++ .chain(&global_scope_hits)
++ .map(|hit| hit.hit.id)
++ .collect();
++ let metadata = self
++ .reader
++ .answer_evidence_metadata(ids)
++ .await
++ .map_err(|e| McpError::internal_error(e.to_string(), None))?;
++ for hit in hits.iter_mut().chain(&mut global_scope_hits) {
++ hit.evidence = metadata.get(&hit.hit.id).cloned();
++ }
++ }
+ let plan = prepare_answer_request(
&args.query,
&hits,
&global_scope_hits,
@@@ -7791,156 -7763,6 +7821,251 @@@ fn validate_answer_citations
})
}
+/// Accounting uses one UTF-8 byte per estimated input token. The fixed
+/// envelope allowance covers unrepresented provider framing approximately.
+const ANSWER_ENVELOPE_RESERVE: usize = 1_024;
- const MIN_CLIPPED_EVIDENCE_CHARS: usize = 16;
++const MIN_CLIPPED_EVIDENCE_CHARS: usize = 1;
+
+#[derive(Debug, Serialize)]
+struct AnswerContext {
+ admitted: usize,
+ omitted: usize,
+ clipped: usize,
+ estimated_input_tokens: usize,
+ reserved_output_tokens: u32,
+ max_context_tokens: usize,
+}
+
+struct AnswerRequestPlan<'a> {
+ request: Option<ai_memory_llm::ChatRequest>,
+ sources: AnswerSources<'a>,
+ context: Option<AnswerContext>,
+}
+
+fn answer_context_notice(admitted: usize, omitted: usize, clipped: usize) -> String {
+ format!(
+ "\n[Answer context: {admitted} admitted, {omitted} omitted, {clipped} clipped. Retrieval hits are unchanged.]\n"
+ )
+}
+
++fn answer_evidence_newer(a: &QueryHit, b: &QueryHit) -> bool {
++ match (&a.evidence, &b.evidence) {
++ (Some(x), Some(y)) if x.workspace_id == y.workspace_id && x.project_id == y.project_id => {
++ x.supersedes == Some(b.hit.id)
++ || (y.supersedes != Some(a.hit.id)
++ && !x.title.trim().is_empty()
++ && x.title.trim().to_lowercase() == y.title.trim().to_lowercase()
++ && (!a.hit.superseded || b.hit.superseded)
++ && x.updated_at > y.updated_at)
++ }
++ _ => false,
++ }
++}
++
++fn answer_evidence_order<'a>(hits: &'a [QueryHit], global: &'a [QueryHit]) -> Vec<&'a QueryHit> {
++ let pending: Vec<_> = hits.iter().chain(global).collect();
++
++ let count = pending.len();
++ let edges: Vec<Vec<bool>> = pending
++ .iter()
++ .map(|new| {
++ pending
++ .iter()
++ .map(|old| answer_evidence_newer(new, old))
++ .collect()
++ })
++ .collect();
++ let mut incoming: Vec<usize> = (0..count)
++ .map(|old| edges.iter().filter(|row| row[old]).count())
++ .collect();
++ let mut remaining = vec![true; count];
++ let mut ordered = Vec::with_capacity(count);
++ for _ in 0..count {
++ // Stable topological order preserves unrelated retrieval ranks.
++ let index = (0..count)
++ .find(|&old| remaining[old] && incoming[old] == 0)
++ .or_else(|| (0..count).find(|&i| remaining[i]))
++ .unwrap_or(0);
++ remaining[index] = false;
++ for old in 0..count {
++ if edges[index][old] {
++ incoming[old] = incoming[old].saturating_sub(1);
++ }
++ }
++ ordered.push(pending[index]);
++ }
++ ordered
++}
++
++fn answer_snippet_prefix(hit: &QueryHit, number: usize) -> String {
++ format!(
++ "{}. path: `{}`\n title: {}\n superseded: {}\n snippet: ",
++ number,
++ hit.hit.path.as_str(),
++ hit.hit.title,
++ hit.hit.superseded
++ )
++}
++
++// A complete trailing sentence can preserve a correction lost by prefix clipping.
++// This bounded syntactic rule does not infer meaning from stored prose.
++fn answer_sentence_suffix(snippet: &str, available: usize) -> Option<String> {
++ let code = ["//", "fn ", "const ", "```"]
++ .iter()
++ .any(|prefix| snippet.trim_start().starts_with(prefix));
++ let terminator = |i: usize, c: char| {
++ matches!(c, '。' | '!' | '?')
++ || ((matches!(c, '.' | '!' | '?') || (code && matches!(c, ';' | '}')))
++ && snippet[i + c.len_utf8()..]
++ .chars()
++ .next()
++ .is_none_or(char::is_whitespace))
++ };
++ let end = snippet
++ .char_indices()
++ .rev()
++ .find(|(i, c)| terminator(*i, *c))
++ .map(|(i, c)| i + c.len_utf8())?;
++ // A partial trailing qualification may reverse an earlier sentence.
++ // Omit rather than silently discard that qualification.
++ if !snippet[end..].trim().is_empty() {
++ return None;
++ }
++ let starts = std::iter::once(0).chain(
++ snippet[..end]
++ .char_indices()
++ .filter(|(i, c)| terminator(*i, *c))
++ .map(|(i, c)| i + c.len_utf8()),
++ );
++ for start in starts {
++ let text = snippet[start..end].trim();
++ let head_marker = if start == 0 { "" } else { "… " };
++ if text.chars().filter(|c| c.is_alphanumeric()).count() >= MIN_CLIPPED_EVIDENCE_CHARS
++ && head_marker.len() + text.len() <= available
++ {
++ return Some(format!("{head_marker}{text}"));
++ }
++ }
++ None
++}
++
+fn prepare_answer_request<'a>(
+ query: &str,
+ hits: &'a [QueryHit],
+ global_scope_hits: &'a [QueryHit],
+ reasoning: ReasoningTier,
+ max_context_tokens: Option<usize>,
+) -> AnswerRequestPlan<'a> {
+ let Some(limit) = max_context_tokens else {
+ let (request, sources) = build_answer_request(query, hits, global_scope_hits, reasoning);
+ return AnswerRequestPlan {
+ request: Some(request),
+ sources,
+ context: None,
+ };
+ };
+ let output = reasoning.scale_max_tokens(2_000);
+ let total = hits.len().saturating_add(global_scope_hits.len());
+ let schema_bytes = serde_json::to_vec(&schemars::schema_for!(AnswerSynthesis))
+ .map(|schema| schema.len())
+ .unwrap_or(usize::MAX);
+ let fixed = ANSWER_SYSTEM_PROMPT
+ .len()
+ .saturating_add(schema_bytes)
+ .saturating_add(ANSWER_ENVELOPE_RESERVE);
+ let mut user = format!("## Question\n\n{query}\n\n## Memory page snippets\n\n");
+ // Reserving the largest count widths keeps the final notice inside the
+ // allowance even when clipping leaves fewer sources than anticipated.
+ let notice_reserve = answer_context_notice(total, total, 1).len();
+ let input_limit = limit.saturating_sub(output as usize);
+ let mut remaining = input_limit.saturating_sub(
+ fixed
+ .saturating_add(user.len())
+ .saturating_add(notice_reserve),
+ );
+ // Full retrieval hits remain visible. Even if admission omits one of two
+ // distinct rows sharing a path, a path-only response would be ambiguous.
+ let mut all_sources = AnswerSources::new();
+ for hit in hits.iter().chain(global_scope_hits) {
+ all_sources
+ .entry(hit.hit.path.as_str())
+ .and_modify(|id| {
+ if *id != Some(hit.hit.id) {
+ *id = None;
+ }
+ })
+ .or_insert(Some(hit.hit.id));
+ }
+ let mut sources = AnswerSources::new();
+ let mut admitted = 0;
+ let mut clipped = 0;
- for hit in hits.iter().chain(global_scope_hits) {
++ let ordered = answer_evidence_order(hits, global_scope_hits);
++ let mut omitted: Vec<&QueryHit> = Vec::new();
++ let mut unadmitted: Vec<&QueryHit> = Vec::new();
++ for hit in ordered {
++ // An unadmitted correction must not be replaced by its obsolete predecessor.
++ if unadmitted.iter().any(|new| answer_evidence_newer(new, hit)) {
++ unadmitted.push(hit);
++ continue;
++ }
+ let snippet = ai_memory_store::plain_snippet(&hit.hit.snippet);
+ if !snippet.chars().any(char::is_alphanumeric) {
+ continue;
+ }
- let prefix = format!(
- "{}. path: `{}`\n title: {}\n superseded: {}\n snippet: ",
- admitted + 1,
- hit.hit.path.as_str(),
- hit.hit.title,
- hit.hit.superseded
- );
- let available = remaining.saturating_sub(prefix.len().saturating_add(2));
- let is_clipped = snippet.len() > available;
- let selected = if is_clipped {
- ai_memory_core::truncate_utf8_bytes(&snippet, available)
- } else {
- snippet
- };
- if selected.trim().is_empty()
- || (is_clipped
- && selected
- .trim_end_matches('…')
- .chars()
- .filter(|c| c.is_alphanumeric())
- .count()
- < MIN_CLIPPED_EVIDENCE_CHARS)
- {
- break;
- }
- let used = prefix
- .len()
- .saturating_add(selected.len())
- .saturating_add(2);
++ let prefix = answer_snippet_prefix(hit, admitted + 1);
++ let used = prefix.len().saturating_add(snippet.len()).saturating_add(2);
+ if used > remaining {
- break;
++ omitted.push(hit);
++ unadmitted.push(hit);
++ continue;
+ }
+ user.push_str(&prefix);
- user.push_str(&selected);
++ user.push_str(&snippet);
+ user.push_str("\n\n");
+ remaining -= used;
+ admitted += 1;
- clipped += usize::from(is_clipped);
+ sources.insert(hit.hit.path.as_str(), all_sources[hit.hit.path.as_str()]);
- if is_clipped {
++ }
++ // Whole snippets first; at most one sentence-safe fragment uses leftover space.
++ for hit in omitted {
++ let prefix = answer_snippet_prefix(hit, admitted + 1);
++ let available = remaining.saturating_sub(prefix.len().saturating_add(2));
++ let snippet = ai_memory_store::plain_snippet(&hit.hit.snippet);
++ if let Some(selected) = answer_sentence_suffix(&snippet, available) {
++ user.push_str(&prefix);
++ user.push_str(&selected);
++ user.push_str("\n\n");
++ admitted += 1;
++ clipped = 1;
++ sources.insert(hit.hit.path.as_str(), all_sources[hit.hit.path.as_str()]);
+ break;
+ }
+ }
+ user.push_str(&answer_context_notice(admitted, total - admitted, clipped));
+ let context = AnswerContext {
+ admitted,
+ omitted: total - admitted,
+ clipped,
+ estimated_input_tokens: fixed.saturating_add(user.len()),
+ reserved_output_tokens: output,
+ max_context_tokens: limit,
+ };
+ let request = (admitted > 0).then(|| ai_memory_llm::ChatRequest {
+ system: Some(ANSWER_SYSTEM_PROMPT.into()),
+ messages: vec![ai_memory_llm::ChatMessage {
+ role: ai_memory_llm::Role::User,
+ content: user,
+ }],
+ max_tokens: output,
+ temperature: Some(0.1),
+ });
+ AnswerRequestPlan {
+ request,
+ sources,
+ context: Some(context),
+ }
+}
+
/// Build the structured-output request for `memory_query(answer=true)`. Inlines
/// the retrieved hit snippets (project hits first, then any `_global` scope
/// hits) as numbered, path-labelled context so the model can ground its answer
@@@ -8399,467 -8221,6 +8524,686 @@@ mod tests
.collect()
}
+ #[test]
+ #[ignore = "local builder microbenchmark; no provider calls"]
+ fn answer_budget_measurements() {
+ fn sample(mut run: impl FnMut()) -> (u128, u128) {
+ for _ in 0..20 {
+ run();
+ }
+ let mut samples = Vec::new();
+ for _ in 0..31 {
+ let start = std::time::Instant::now();
+ for _ in 0..20 {
+ run();
+ }
+ samples.push(start.elapsed().as_nanos() / 20);
+ }
+ samples.sort_unstable();
+ (samples[15], samples[29])
+ }
+ println!(
+ "C2CSV,fixture,hits,mode,request_built,content_bytes,content_scalars,admitted,omitted,clipped,estimated_input_tokens,reserved_output_tokens,p50_ns,p95_ns"
+ );
+ for (name, text) in [
+ (
+ "ascii",
+ "The deployment uses a worker queue with retry policy and bounded concurrency. ",
+ ),
+ (
+ "pt-BR",
+ "A implantação usa uma fila de tarefas com repetição e concorrência limitada. ",
+ ),
+ ("CJK", "部署使用任务队列、重试策略和受限并发。"),
+ (
+ "code",
+ "fn retry(attempt: usize) -> bool { attempt < 3 && queue.len() < 64 }\n",
+ ),
+ ] {
+ let snippet: String = text.repeat(20).chars().take(240).collect();
+ for n in [1, 10, 50, 100] {
+ let mut hits = answer_budget_hits(&vec![snippet.as_str(); n]);
+ for hit in &mut hits {
+ hit.hit.title = "Deployment decision".into();
+ }
+ for (suffix, query) in [
+ ("short", "What is the deployment decision?".to_owned()),
+ ("long", "Which decision? ".repeat(10_000)),
+ ] {
+ for (mode, budget) in [("disabled", None), ("16000", Some(16_000))] {
+ let (p50, p95) = sample(|| {
+ std::hint::black_box(prepare_answer_request(
+ std::hint::black_box(&query),
+ &hits,
+ &[],
+ ReasoningTier::Minimal,
+ budget,
+ ));
+ });
+ let plan = prepare_answer_request(
+ &query,
+ &hits,
+ &[],
+ ReasoningTier::Minimal,
+ budget,
+ );
+ let (bytes, scalars) = plan
+ .request
+ .as_ref()
+ .map(|request| {
+ let system = request.system.as_deref().unwrap_or_default();
+ (
+ system.len() + request.messages[0].content.len(),
+ system.chars().count()
+ + request.messages[0].content.chars().count(),
+ )
+ })
+ .unwrap_or_default();
+ let (admitted, omitted, clipped, estimated) = plan
+ .context
+ .as_ref()
+ .map(|context| {
+ (
+ context.admitted,
+ context.omitted,
+ context.clipped,
+ context.estimated_input_tokens.to_string(),
+ )
+ })
+ .unwrap_or((n, 0, 0, "NA".into()));
+ println!(
+ "C2CSV,{name}-{suffix},{n},{mode},{},{bytes},{scalars},{admitted},{omitted},{clipped},{estimated},2000,{p50},{p95}",
+ plan.request.is_some()
+ );
+ }
+ }
+ }
+ }
+ }
+
+ fn answer_budget_hits(snippets: &[&str]) -> Vec<QueryHit> {
+ rerank_test_hits(snippets.len())
+ .into_iter()
+ .zip(snippets)
+ .map(|((mut hit, _), snippet)| {
+ hit.snippet = (*snippet).into();
+ QueryHit::from(hit)
+ })
+ .collect()
+ }
+
+ #[test]
+ fn answer_budget_disabled_preserves_request_and_sources() {
+ let hits = answer_budget_hits(&["The current deployment uses the queue."]);
+ let (original, sources) = build_answer_request("question", &hits, &[], ReasoningTier::Max);
+ let plan = prepare_answer_request("question", &hits, &[], ReasoningTier::Max, None);
+ let actual = plan.request.unwrap();
+ assert_eq!(actual.system, original.system);
+ assert_eq!(actual.messages[0].content, original.messages[0].content);
+ assert_eq!(actual.max_tokens, original.max_tokens);
+ assert_eq!(actual.temperature, original.temperature);
+ assert_eq!(plan.sources, sources);
+ assert!(plan.context.is_none());
+ }
+
+ #[test]
+ fn answer_budget_exact_boundary_and_one_byte_over() {
+ for snippet in [
+ "The current architecture uses a bounded queue with retries.",
+ "A implantação usa uma fila com repetição e concorrência limitada.",
+ "当前部署使用任务队列、重试策略和受限并发。当前决定已替代之前的同步调用。",
+ "fn retry(n: usize) -> bool { n < 3 && queue.len() < 64 }",
+ ] {
+ let hits = answer_budget_hits(&[snippet]);
+ let full = prepare_answer_request(
+ "question",
+ &hits,
+ &[],
+ ReasoningTier::Minimal,
+ Some(100_000),
+ );
+ let context = full.context.unwrap();
+ let exact = context.estimated_input_tokens + context.reserved_output_tokens as usize;
+ let plan =
+ prepare_answer_request("question", &hits, &[], ReasoningTier::Minimal, Some(exact));
+ assert_eq!(plan.context.as_ref().unwrap().clipped, 0);
+ assert_eq!(plan.context.as_ref().unwrap().admitted, 1);
+ let plan = prepare_answer_request(
+ "question",
+ &hits,
+ &[],
+ ReasoningTier::Minimal,
+ Some(exact - 1),
+ );
+ let context = plan.context.unwrap();
- assert_eq!(context.clipped, 1, "{snippet}");
+ assert!(
+ context.estimated_input_tokens + (context.reserved_output_tokens as usize) < exact
+ );
- assert!(plan.request.unwrap().messages[0].content.contains('…'));
++ if let Some(request) = plan.request {
++ assert_eq!(context.clipped, 1, "{snippet}");
++ assert!(request.messages[0].content.contains('…'));
++ } else {
++ // A single complete sentence cannot fit one byte short; do
++ // not admit a cut word or an arbitrary sentence prefix.
++ assert_eq!(context.admitted, 0, "{snippet}");
++ assert_eq!(context.clipped, 0, "{snippet}");
++ assert!(plan.sources.is_empty());
++ }
+ }
+ }
+
+ #[test]
+ fn answer_budget_refuses_empty_or_meaningless_evidence() {
+ let hits = answer_budget_hits(&["An actual supported architecture decision."]);
+ for query in ["question".to_owned(), "long question ".repeat(10_000)] {
+ let plan = prepare_answer_request(&query, &hits, &[], ReasoningTier::Max, Some(1_000));
+ assert!(plan.request.is_none());
+ assert!(plan.sources.is_empty());
+ }
+ // With the same sufficient budget and evidence, only the long question
+ // prevents admission: fixed question content is charged before snippets.
+ let short =
+ prepare_answer_request("question", &hits, &[], ReasoningTier::Minimal, Some(10_000));
+ assert!(short.request.is_some());
+ let long = prepare_answer_request(
+ &"long question ".repeat(10_000),
+ &hits,
+ &[],
+ ReasoningTier::Minimal,
+ Some(10_000),
+ );
+ assert!(long.request.is_none());
+ assert!(long.sources.is_empty());
+ for snippets in [&[][..], &[" "][..], &["---```---```---```---```---"][..]] {
+ let empty = answer_budget_hits(snippets);
+ assert!(
+ prepare_answer_request(
+ "question",
+ &empty,
+ &[],
+ ReasoningTier::Minimal,
+ Some(100_000)
+ )
+ .request
+ .is_none()
+ );
+ }
+ let full = prepare_answer_request(
+ "question",
+ &hits,
+ &[],
+ ReasoningTier::Minimal,
+ Some(100_000),
+ );
+ let context = full.context.unwrap();
+ let tiny = context.estimated_input_tokens + context.reserved_output_tokens as usize
+ - hits[0].hit.snippet.len()
+ + 10;
+ assert!(
+ prepare_answer_request("question", &hits, &[], ReasoningTier::Minimal, Some(tiny))
+ .request
+ .is_none()
+ );
+ }
+
+ #[test]
+ fn answer_budget_keeps_ranked_evidence_and_excludes_omitted_citations() {
+ let hits = answer_budget_hits(&[
+ "The current decision uses PostgreSQL for persistence.",
+ "An unrelated procedure fills the remaining context.",
+ ]);
+ let first = prepare_answer_request(
+ "question",
+ &hits[..1],
+ &[],
+ ReasoningTier::Minimal,
+ Some(100_000),
+ );
+ let context = first.context.unwrap();
+ let limit = context.estimated_input_tokens + context.reserved_output_tokens as usize;
+ let plan =
+ prepare_answer_request("question", &hits, &[], ReasoningTier::Minimal, Some(limit));
+ let context = plan.context.unwrap();
+ assert_eq!(
+ (context.admitted, context.omitted, context.clipped),
+ (1, 1, 0)
+ );
+ assert_eq!(hits.len(), 2);
+ assert!(
+ validate_answer_citations(
+ AnswerSynthesis {
+ answer: "supported".into(),
+ citations: vec![hits[0].hit.path.to_string()]
+ },
+ &plan.sources
+ )
+ .is_some()
+ );
+ assert!(
+ validate_answer_citations(
+ AnswerSynthesis {
+ answer: "unsupported".into(),
+ citations: vec![hits[1].hit.path.to_string()]
+ },
+ &plan.sources
+ )
+ .is_none()
+ );
+ assert!(
+ plan.request.unwrap().messages[0]
+ .content
+ .contains("1 omitted")
+ );
+ }
+
+ #[test]
+ fn answer_budget_does_not_hide_same_path_ambiguity_by_omission() {
+ let mut hits = answer_budget_hits(&[
+ "Current evidence supplies a real supported answer.",
+ "Other-scope evidence must not be confused with it.",
+ ]);
+ hits[1].hit.path = hits[0].hit.path.clone();
+ let full = prepare_answer_request(
+ "question",
+ &hits[..1],
+ &[],
+ ReasoningTier::Minimal,
+ Some(100_000),
+ );
+ let context = full.context.unwrap();
+ let limit = context.estimated_input_tokens + context.reserved_output_tokens as usize;
+ let plan =
+ prepare_answer_request("question", &hits, &[], ReasoningTier::Minimal, Some(limit));
+ assert_eq!(plan.context.unwrap().admitted, 1);
+ assert!(
+ validate_answer_citations(
+ AnswerSynthesis {
+ answer: "ambiguous".into(),
+ citations: vec![hits[0].hit.path.to_string()]
+ },
+ &plan.sources
+ )
+ .is_none()
+ );
+ }
+
+ #[test]
+ fn answer_budget_labels_superseded_decisions_and_preserves_corrections() {
+ let mut hits = answer_budget_hits(&[
+ "Correction: current deployments use PostgreSQL, replacing SQLite.",
+ "Historical decision: deployments use SQLite.",
+ ]);
+ hits[1].hit.superseded = true;
+ let plan = prepare_answer_request(
+ "current deployment?",
+ &hits,
+ &[],
+ ReasoningTier::Minimal,
+ Some(10_000),
+ );
+ let body = &plan.request.as_ref().unwrap().messages[0].content;
+ assert!(body.contains("superseded: false"));
+ assert!(body.contains("superseded: true"));
+ assert!(body.contains("Correction: current deployments use PostgreSQL, replacing SQLite."));
+ assert_eq!(plan.context.unwrap().admitted, 2);
+ }
+
- /// A literal-retention oracle, not an answer-quality evaluator. Expected
- /// losses make the ranked-prefix policy's limits executable and visible.
++ /// A literal-retention oracle, not an answer-quality evaluator. These
++ /// labeled cases pin complete corrections and scoped recency ordering.
+ #[test]
+ fn answer_budget_labeled_evidence_retention_boundaries() {
+ const QUERY: &str = "What is the current decision?";
+ let fixtures = [
+ (
+ "en",
+ "Historical deployment decision: use SQLite for durable storage.",
+ "Correction: current deployment uses PostgreSQL.",
+ "current deployment uses PostgreSQL",
+ ),
+ (
+ "pt-BR",
+ "Decisão histórica de implantação: usar SQLite para armazenamento durável.",
+ "Correção: a implantação atual usa PostgreSQL.",
+ "a implantação atual usa PostgreSQL",
+ ),
+ (
+ "CJK",
+ "历史部署决定使用旧数据库保存持久数据,此记录仅描述之前的方案。",
+ "更正:当前部署使用新的数据库方案。",
+ "当前部署使用新的数据库方案",
+ ),
+ (
+ "code",
+ "// Historical deployment configuration: const DATABASE = \"sqlite\";",
+ "// Correction: const DATABASE = \"postgresql\";",
+ "const DATABASE = \"postgresql\";",
+ ),
+ ];
+ println!(
+ "C2RETENTION,fixture,case,baseline_literal_retained,candidate_literal_retained,admitted,omitted,clipped"
+ );
+ for (language, historical, correction, required_literal) in fixtures {
+ let combined = format!("{historical} {correction}");
+ for (case, snippets, retained, expected_counts) in [
+ ("exact-fit", vec![combined.as_str()], true, (1, 0, 0)),
- ("trimmed-tail", vec![combined.as_str()], false, (1, 0, 1)),
++ ("trimmed-tail", vec![combined.as_str()], true, (1, 0, 1)),
+ (
- "historical-first-omitted-correction",
++ "historical-first-current-selected",
+ vec![historical, correction],
- false,
++ true,
+ (1, 1, 0),
+ ),
+ (
+ "current-first-omitted-history",
+ vec![correction, historical],
+ true,
+ (1, 1, 0),
+ ),
+ ] {
+ let mut hits = answer_budget_hits(&snippets);
- if case == "historical-first-omitted-correction" {
- hits[0].hit.superseded = true;
- } else if case == "current-first-omitted-history" {
- hits[1].hit.superseded = true;
++ let selected_index = usize::from(case == "historical-first-current-selected");
++ if hits.len() > 1 {
++ let old_index = 1 - selected_index;
++ let workspace_id = WorkspaceId::new();
++ let project_id = ProjectId::new();
++ for (index, hit) in hits.iter_mut().enumerate() {
++ hit.evidence = Some(ai_memory_store::AnswerEvidenceMeta {
++ workspace_id,
++ project_id,
++ title: "Deployment decision".into(),
++ updated_at: if index == selected_index { 2 } else { 1 },
++ supersedes: None,
++ });
++ }
++ hits[selected_index].evidence.as_mut().unwrap().supersedes =
++ Some(hits[old_index].hit.id);
+ }
+ let before = serde_json::to_value(&hits).unwrap();
+ let baseline =
+ prepare_answer_request(QUERY, &hits, &[], ReasoningTier::Minimal, None);
+ let baseline_retained = baseline.request.as_ref().unwrap().messages[0]
+ .content
+ .contains(required_literal);
+ assert!(baseline_retained, "disabled baseline: {language}/{case}");
+ assert!(baseline.context.is_none());
+ let full_first = prepare_answer_request(
+ QUERY,
+ &hits[..1],
+ &[],
+ ReasoningTier::Minimal,
+ Some(100_000),
+ );
+ let context = full_first.context.unwrap();
+ let exact =
+ context.estimated_input_tokens + context.reserved_output_tokens as usize;
- // In the tail case the allowance ends before the correction;
- // the ellipsis consumes three bytes of the historical prefix.
++ // Preserve the original probe allowance: enough historical
++ // prefix bytes, now used to retain a complete correction.
+ let limit = if case == "trimmed-tail" {
+ exact - correction.len() - 1
+ } else {
+ exact
+ };
+ let plan =
+ prepare_answer_request(QUERY, &hits, &[], ReasoningTier::Minimal, Some(limit));
+ let context = plan.context.as_ref().unwrap();
+ let request = plan.request.as_ref().unwrap();
+ let body = &request.messages[0].content;
+ assert_eq!(
+ body.contains(required_literal),
+ retained,
+ "{language}/{case}"
+ );
+ assert_eq!(
+ (context.admitted, context.omitted, context.clipped),
+ expected_counts,
+ "{language}/{case}"
+ );
+ // Reconstruct the accounting from the actual request/schema,
+ // independently of the builder's remaining-capacity variable.
+ let schema = serde_json::to_vec(&schemars::schema_for!(AnswerSynthesis)).unwrap();
+ let input = request.system.as_ref().unwrap().len()
+ + request
+ .messages
+ .iter()
+ .map(|m| m.content.len())
+ .sum::<usize>()
+ + schema.len()
+ + ANSWER_ENVELOPE_RESERVE;
+ assert_eq!(context.estimated_input_tokens, input, "{language}/{case}");
+ assert!(
+ input + request.max_tokens as usize <= limit,
+ "{language}/{case}"
+ );
+ assert_eq!(plan.sources.len(), 1, "{language}/{case}");
+ assert_eq!(
- plan.sources.get(hits[0].hit.path.as_str()),
- Some(&Some(hits[0].hit.id)),
++ plan.sources.get(hits[selected_index].hit.path.as_str()),
++ Some(&Some(hits[selected_index].hit.id)),
+ "{language}/{case}"
+ );
+ if hits.len() > 1 {
- assert!(!plan.sources.contains_key(hits[1].hit.path.as_str()));
++ let omitted_index = 1 - selected_index;
++ assert!(
++ !plan
++ .sources
++ .contains_key(hits[omitted_index].hit.path.as_str())
++ );
+ assert!(
+ validate_answer_citations(
+ AnswerSynthesis {
+ answer: "unsupported omitted-source claim".into(),
- citations: vec![hits[1].hit.path.to_string()],
++ citations: vec![hits[omitted_index].hit.path.to_string()],
+ },
+ &plan.sources,
+ )
+ .is_none()
+ );
+ }
- if case == "historical-first-omitted-correction" {
- assert!(body.contains("superseded: true"));
- }
+ assert_eq!(serde_json::to_value(&hits).unwrap(), before);
+ println!(
+ "C2RETENTION,{language},{case},{baseline_retained},{retained},{},{},{}",
+ context.admitted, context.omitted, context.clipped
+ );
+ }
+ }
+ }
+
++ fn answer_test_metadata(hits: &mut [QueryHit]) {
++ let workspace_id = WorkspaceId::new();
++ let project_id = ProjectId::new();
++ for (index, hit) in hits.iter_mut().enumerate() {
++ hit.evidence = Some(ai_memory_store::AnswerEvidenceMeta {
++ workspace_id,
++ project_id,
++ title: "Deployment decision".into(),
++ updated_at: index as i64 + 1,
++ supersedes: None,
++ });
++ }
++ }
++
++ #[test]
++ fn answer_budget_newer_session_same_topic_precedes_old_retrieval_rank() {
++ let mut hits = answer_budget_hits(&[
++ "An earlier session selected SQLite for deployment.",
++ "A later session corrected the deployment to PostgreSQL.",
++ ]);
++ answer_test_metadata(&mut hits);
++ let before = serde_json::to_value(&hits).unwrap();
++ let order = answer_evidence_order(&hits, &[]);
++ assert_eq!(
++ order.iter().map(|hit| hit.hit.id).collect::<Vec<_>>(),
++ vec![hits[1].hit.id, hits[0].hit.id]
++ );
++ assert_eq!(serde_json::to_value(&hits).unwrap(), before);
++ }
++
++ #[test]
++ fn answer_budget_explicit_supersedes_wins_with_distinct_titles() {
++ let mut hits = answer_budget_hits(&[
++ "Earlier deployment decision.",
++ "Replacement deployment decision.",
++ ]);
++ answer_test_metadata(&mut hits);
++ let previous = hits[0].hit.id;
++ let replacement = hits[1].evidence.as_mut().unwrap();
++ replacement.title = "Replacement topic title".into();
++ // Explicit lineage, rather than title equality or timestamp alone,
++ // determines the ordering even if an imported timestamp is older.
++ replacement.updated_at = 0;
++ replacement.supersedes = Some(previous);
++ assert_eq!(answer_evidence_order(&hits, &[])[0].hit.id, hits[1].hit.id);
++ }
++
++ #[test]
++ fn answer_budget_explicit_same_topic_lineage_overrides_imported_timestamp() {
++ let mut hits = answer_budget_hits(&[
++ "Earlier deployment decision.",
++ "Replacement deployment decision.",
++ ]);
++ answer_test_metadata(&mut hits);
++ let previous = hits[0].hit.id;
++ let replacement = hits[1].evidence.as_mut().unwrap();
++ replacement.updated_at = 0;
++ replacement.supersedes = Some(previous);
++ assert!(answer_evidence_newer(&hits[1], &hits[0]));
++ assert!(!answer_evidence_newer(&hits[0], &hits[1]));
++ let order = answer_evidence_order(&hits, &[]);
++ assert_eq!(order[0].hit.id, hits[1].hit.id);
++ assert_eq!(order[1].hit.id, hits[0].hit.id);
++ }
++
++ #[test]
++ fn answer_budget_unrelated_scopes_titles_and_equal_times_preserve_rank() {
++ for variation in ["workspace", "project", "title", "equal-time", "no-metadata"] {
++ let mut hits =
++ answer_budget_hits(&["First ranked evidence.", "Second ranked evidence."]);
++ answer_test_metadata(&mut hits);
++ // A superseded flag alone must not reorder unrelated retrieval.
++ hits[0].hit.superseded = true;
++ match variation {
++ "workspace" => hits[1].evidence.as_mut().unwrap().workspace_id = WorkspaceId::new(),
++ "project" => hits[1].evidence.as_mut().unwrap().project_id = ProjectId::new(),
++ "title" => hits[1].evidence.as_mut().unwrap().title = "Unrelated topic".into(),
++ "equal-time" => hits[1].evidence.as_mut().unwrap().updated_at = 1,
++ _ => hits[1].evidence = None,
++ }
++ let order = answer_evidence_order(&hits[..1], &hits[1..]);
++ assert_eq!(
++ order.iter().map(|hit| hit.hit.id).collect::<Vec<_>>(),
++ vec![hits[0].hit.id, hits[1].hit.id],
++ "{variation}"
++ );
++ }
++ }
++
++ #[test]
++ fn answer_budget_whole_lower_ranked_snippet_precedes_oversized_fragment() {
++ let large = format!(
++ "{} Current deployment uses PostgreSQL.",
++ "Historical background. ".repeat(40)
++ );
++ let hits = answer_budget_hits(&[&large, "A complete independent deployment fact."]);
++ let full = prepare_answer_request(
++ "question",
++ &hits[1..],
++ &[],
++ ReasoningTier::Minimal,
++ Some(100_000),
++ );
++ let context = full.context.unwrap();
++ let limit = context.estimated_input_tokens + context.reserved_output_tokens as usize;
++ let plan =
++ prepare_answer_request("question", &hits, &[], ReasoningTier::Minimal, Some(limit));
++ let context = plan.context.unwrap();
++ assert_eq!(
++ (context.admitted, context.omitted, context.clipped),
++ (1, 1, 0)
++ );
++ assert_eq!(
++ plan.sources.get(hits[1].hit.path.as_str()),
++ Some(&Some(hits[1].hit.id))
++ );
++ assert!(!plan.sources.contains_key(hits[0].hit.path.as_str()));
++ let request = plan.request.unwrap();
++ assert!(
++ request.messages[0]
++ .content
++ .contains("A complete independent deployment fact.")
++ );
++ assert!(
++ !request.messages[0]
++ .content
++ .contains("Current deployment uses PostgreSQL.")
++ );
++ }
++
++ #[test]
++ fn answer_budget_supersession_chain_does_not_fall_back_to_old_ancestors() {
++ let mut hits = answer_budget_hits(&[
++ "The oldest obsolete database choice.",
++ "An intermediate obsolete database choice.",
++ "A current correction that cannot fit whole "
++ .repeat(100)
++ .as_str(),
++ ]);
++ answer_test_metadata(&mut hits);
++ hits[0].hit.superseded = true;
++ hits[1].hit.superseded = true;
++ hits[0].evidence.as_mut().unwrap().updated_at = 1000;
++ hits[1].evidence.as_mut().unwrap().supersedes = Some(hits[0].hit.id);
++ hits[2].evidence.as_mut().unwrap().supersedes = Some(hits[1].hit.id);
++ let order = answer_evidence_order(&hits, &[]);
++ assert_eq!(
++ order.iter().map(|h| h.hit.id).collect::<Vec<_>>(),
++ vec![hits[2].hit.id, hits[1].hit.id, hits[0].hit.id]
++ );
++ let full = prepare_answer_request(
++ "question",
++ &hits[..1],
++ &[],
++ ReasoningTier::Minimal,
++ Some(100_000),
++ );
++ let context = full.context.unwrap();
++ let limit = context.estimated_input_tokens + context.reserved_output_tokens as usize;
++ let plan =
++ prepare_answer_request("question", &hits, &[], ReasoningTier::Minimal, Some(limit));
++ assert!(plan.request.is_none());
++ assert!(plan.sources.is_empty());
++ }
++
++ #[test]
++ fn answer_budget_refuses_unsplittable_or_unterminated_fragments() {
++ for snippet in [
++ "anunsplittablewordwithoutanysentenceboundary".repeat(20),
++ "An older complete rule. A trailing correction without a terminator".repeat(20),
++ "A long unfinished deployment decision without a sentence terminator ".repeat(20),
++ "A prose sentence wrapped across lines\nthat must stay complete".repeat(20),
++ "A prose rule with a semicolon; and an unfinished qualification".repeat(20),
++ ] {
++ let hits = answer_budget_hits(&[&snippet]);
++ let full = prepare_answer_request(
++ "question",
++ &hits,
++ &[],
++ ReasoningTier::Minimal,
++ Some(100_000),
++ );
++ let context = full.context.unwrap();
++ let limit =
++ context.estimated_input_tokens + context.reserved_output_tokens as usize - 1;
++ let plan =
++ prepare_answer_request("question", &hits, &[], ReasoningTier::Minimal, Some(limit));
++ assert!(plan.request.is_none());
++ assert!(plan.sources.is_empty());
++ let context = plan.context.unwrap();
++ assert_eq!(
++ (context.admitted, context.omitted, context.clipped),
++ (0, 1, 0)
++ );
++ }
++ }
++
#[test]
fn answer_sources_distinguish_repeated_rows_from_ambiguous_paths() {
let mut hits: Vec<QueryHit> = rerank_test_hits(3)
diff --cc crates/ai-memory-mcp/tests/suite/query_answer.rs
index 6ae7fa72,ee56b611..1f9f4b24
--- a/crates/ai-memory-mcp/tests/suite/query_answer.rs
+++ b/crates/ai-memory-mcp/tests/suite/query_answer.rs
@@@ -644,171 -629,3 +644,211 @@@ async fn answer_live_provider_smoke()
"live provider answer must be non-empty: {resp}"
);
}
+
+#[tokio::test]
+async fn answer_budget_never_calls_provider_without_evidence_and_keeps_hits() {
+ let h = harness_with_budget(
+ true,
+ json!({"answer":"unreachable", "citations":[]}),
+ Some(1),
+ )
+ .await;
+ seed_needle(&h).await;
+ let resp = call(
+ &h.router,
+ "memory_query",
+ query_args("needle", json!({"answer":true})),
+ )
+ .await;
+ assert_eq!(hit_paths(&resp), ["notes/topic.md"]);
+ assert!(resp.get("answer").is_none());
+ assert!(
+ resp["answer_unavailable"]
+ .as_str()
+ .unwrap()
+ .contains("no meaningful evidence")
+ );
+ assert_eq!(resp["answer_context"]["omitted"], 1);
+ assert_eq!(h.calls.unwrap().load(Ordering::SeqCst), 0);
+}
+
+#[tokio::test]
+async fn answer_budget_is_inert_on_default_and_no_provider_queries() {
+ for with_provider in [true, false] {
+ let h = harness_with_budget(
+ with_provider,
+ json!({"answer":"unused", "citations":[]}),
+ Some(1),
+ )
+ .await;
+ seed_needle(&h).await;
+ let default = call(&h.router, "memory_query", query_args("needle", json!({}))).await;
+ assert!(default.get("answer_context").is_none());
+ assert!(default.get("answer_unavailable").is_none());
+ if !with_provider {
+ let answer = call(
+ &h.router,
+ "memory_query",
+ query_args("needle", json!({"answer":true})),
+ )
+ .await;
+ assert!(answer.get("answer_context").is_none());
+ assert!(
+ answer["answer_unavailable"]
+ .as_str()
+ .unwrap()
+ .contains("no LLM")
+ );
+ }
+ }
+}
+
+async fn seed_budget_pages(h: &Harness, second: bool) {
+ let mut first = page(
+ h.ws,
+ h.proj,
+ "notes/topic.md",
+ "needle: current deployment uses PostgreSQL.",
+ );
+ first.pinned = true;
+ h.store.writer.upsert_page(first).await.unwrap();
+ if second {
+ h.store
+ .writer
+ .upsert_page(page(
+ h.ws,
+ h.proj,
+ "notes/omitted.md",
+ "needle: unrelated procedure for the build system.",
+ ))
+ .await
+ .unwrap();
+ }
+}
+
+#[tokio::test]
+async fn answer_budget_transport_accepts_admitted_and_rejects_omitted_sources() {
+ let response = |path: &str| json!({"answer":"PostgreSQL", "citations":[path]});
+ let full = harness_with_budget(true, response("notes/topic.md"), Some(100_000)).await;
+ seed_budget_pages(&full, false).await;
+ let arguments = || query_args("needle", json!({"answer":true, "pin_first":true}));
+ let resp = call(&full.router, "memory_query", arguments()).await;
+ assert_eq!(resp["answer"]["citations"], json!(["notes/topic.md"]));
+ let limit = resp["answer_context"]["estimated_input_tokens"]
+ .as_u64()
+ .unwrap()
+ + resp["answer_context"]["reserved_output_tokens"]
+ .as_u64()
+ .unwrap();
+ for path in ["notes/topic.md", "notes/omitted.md"] {
+ let h = harness_with_budget(true, response(path), Some(limit as usize)).await;
+ seed_budget_pages(&h, true).await;
+ let resp = call(&h.router, "memory_query", arguments()).await;
+ assert_eq!(hit_paths(&resp), ["notes/topic.md", "notes/omitted.md"]);
+ assert_eq!(resp["answer_context"]["admitted"], 1);
+ assert_eq!(resp["answer_context"]["omitted"], 1);
+ assert_eq!(h.calls.as_ref().unwrap().load(Ordering::SeqCst), 1);
+ if path == "notes/topic.md" {
+ assert_eq!(resp["answer"]["citations"], json!([path]));
+ assert!(resp.get("answer_unavailable").is_none());
+ } else {
+ assert!(resp.get("answer").is_none());
+ assert!(
+ resp["answer_unavailable"]
+ .as_str()
+ .unwrap()
+ .contains("citations")
+ );
+ }
+ }
+}
+
+#[tokio::test]
+async fn answer_budget_receipt_matches_request_at_provider_boundary() {
+ // Inspect the actual structured call, including its schema. A canned answer
+ // alone cannot detect a handler that accounts one prompt and sends another.
+ for (tier, output) in [
+ ("minimal", 2_000_u64),
+ ("low", 3_000),
+ ("medium", 4_000),
+ ("high", 6_000),
+ ("max", 8_000),
+ ] {
+ let h = harness_with_budget(
+ true,
+ json!({"answer":"PostgreSQL", "citations":["notes/topic.md"]}),
+ Some(16_000),
+ )
+ .await;
+ seed_budget_pages(&h, true).await;
+ let resp = call(
+ &h.router,
+ "memory_query",
+ query_args("needle", json!({"answer":true, "reasoning":tier})),
+ )
+ .await;
+ let requests = h.requests.lock().unwrap();
+ assert_eq!(requests.len(), 1, "{tier}");
+ let (request, schema) = &requests[0];
+ let actual_input = request.system.as_ref().unwrap().len()
+ + request
+ .messages
+ .iter()
+ .map(|m| m.content.len())
+ .sum::<usize>()
+ + serde_json::to_vec(schema).unwrap().len()
+ + 1_024;
+ assert_eq!(request.max_tokens as u64, output, "{tier}");
+ assert_eq!(resp["answer_context"]["reserved_output_tokens"], output);
+ assert_eq!(
+ resp["answer_context"]["estimated_input_tokens"],
+ actual_input
+ );
+ assert!(actual_input + request.max_tokens as usize <= 16_000);
+ assert_eq!(resp["answer_context"]["admitted"], 2);
+ assert_eq!(resp["answer_context"]["omitted"], 0);
+ assert_eq!(resp["answer_context"]["clipped"], 0);
+ assert_eq!(hit_paths(&resp).len(), 2);
+ assert_eq!(h.calls.as_ref().unwrap().load(Ordering::SeqCst), 1);
+ }
+}
++
++#[tokio::test]
++async fn answer_budget_uses_store_recency_without_reordering_retrieval_hits() {
++ let h = harness_with_budget(
++ true,
++ json!({"answer":"PostgreSQL", "citations":["notes/current.md"]}),
++ Some(100_000),
++ )
++ .await;
++ let mut old = page(
++ h.ws,
++ h.proj,
++ "notes/old.md",
++ "needle: historical deployment uses SQLite.",
++ );
++ old.title = "Deployment decision".into();
++ old.pinned = true;
++ h.store.writer.upsert_page(old).await.unwrap();
++ // The two writes need distinct stored modification times for this fixture.
++ tokio::time::sleep(std::time::Duration::from_millis(2)).await;
++ let mut current = page(
++ h.ws,
++ h.proj,
++ "notes/current.md",
++ "needle: current deployment uses PostgreSQL.",
++ );
++ current.title = "Deployment decision".into();
++ h.store.writer.upsert_page(current).await.unwrap();
++ let response = call(
++ &h.router,
++ "memory_query",
++ query_args("needle", json!({"answer":true,"pin_first":true})),
++ )
++ .await;
++ assert_eq!(hit_paths(&response), ["notes/old.md", "notes/current.md"]);
++ let requests = h.requests.lock().unwrap();
++ let body = &requests[0].0.messages[0].content;
++ assert!(body.find("notes/current.md").unwrap() < body.find("notes/old.md").unwrap());
++ assert_eq!(response["answer"]["citations"], json!(["notes/current.md"]));
++}
diff --cc crates/ai-memory-store/src/lib.rs
index 6a59f99c,6a59f99c..820cb0a5
--- a/crates/ai-memory-store/src/lib.rs
+++ b/crates/ai-memory-store/src/lib.rs
@@@ -83,14 -83,14 +83,15 @@@ pub use project_authz::
RESTRICTED_PROJECT_FORBIDDEN, authorize_project, resolve_project_authz,
};
pub use reader::{
-- ActivityWindow, AgentSessionCount, AuditEvent, AuditLogFilter, AutoImproveCandidateSession,
-- AutoImproveParkedClaim, BriefPageBody, BriefingPage, BriefingSnapshot, ClientActivity,
-- ContaminationFinding, ContaminationReport, ContaminationSummary, ContradictionEdge,
-- CrossProjectEdge, DecayCandidate, DecayTombstone, DerivedIndexStatus, EmbeddingTripleCount,
-- FTS_HIGHLIGHT_END, FTS_HIGHLIGHT_START, FeedbackFinding, GraphVia, HealthDetail, HealthPage,
-- HybridSearch, HybridSearchOutcome, IdleOpenSession, InboxCount, InboxEntry, LinkGraph,
-- LinkGraphEdge, LinkGraphNode, ObservationHit, ObservationOrder, ObservationPage,
-- ObservationPageResult, ObservationProjectionTotals, ObservationRecord, OpenSession, PAGE_KINDS,
++ ActivityWindow, AgentSessionCount, AnswerEvidenceMeta, AuditEvent, AuditLogFilter,
++ AutoImproveCandidateSession, AutoImproveParkedClaim, BriefPageBody, BriefingPage,
++ BriefingSnapshot, ClientActivity, ContaminationFinding, ContaminationReport,
++ ContaminationSummary, ContradictionEdge, CrossProjectEdge, DecayCandidate, DecayTombstone,
++ DerivedIndexStatus, EmbeddingTripleCount, FTS_HIGHLIGHT_END, FTS_HIGHLIGHT_START,
++ FeedbackFinding, GraphVia, HealthDetail, HealthPage, HybridSearch, HybridSearchOutcome,
++ IdleOpenSession, InboxCount, InboxEntry, LinkGraph, LinkGraphEdge, LinkGraphNode,
++ ObservationHit, ObservationOrder, ObservationPage, ObservationPageResult,
++ ObservationProjectionTotals, ObservationRecord, OpenSession, PAGE_KINDS,
PAGE_VERSIONS_MAX_LIMIT, PROJECT_LINK_GRAPH_MAX_NODES, PageAuthor, PageFilter, PageHit,
PageHitWithMeta, PageLinks, PageLinksPreview, PageMeta, PageSummary, PageVersion,
PageVersionBody, PageVersions, ProjectCoordinateCollisionReason, ProjectCoordinateDiagnostic,
diff --cc crates/ai-memory-store/src/reader.rs
index 3cb6c1fb,071df62b..b14faf6c
--- a/crates/ai-memory-store/src/reader.rs
+++ b/crates/ai-memory-store/src/reader.rs
@@@ -2655,7 -2675,7 +2675,93 @@@ struct Pool
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
@@@ -15124,6 -15187,6 +15273,161 @@@ fn open_read_only(path: &Path) -> Store
#[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.
diff --cc docs/ARCHITECTURE.md
index b033eb03,316f749c..cff33fc3
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@@ -733,7 -733,7 +733,7 @@@ does not need to ride on the public pro
| Tool | Hint | Purpose |
|---|---|---|
- | `memory_query` | read-only | FTS5 + entity-match + graph RRF + optional vector RRF + observation-evidence stream (on by default) search, followed by bounded kind/tier/pinned/tag authority adjustment and raw fallback. Bumps access counters for page hits. Defaults to the current project; single-project calls (project implicit or named with `workspace`+`project`) also union the reserved `_global` preferences scope as `global_scope_hits`, and only an explicit multi-`scopes` set opts out (#930); `scopes` searches named sibling projects; `global=true` searches every project at once (each hit annotated with its workspace + project). With `AI_MEMORY_RERANKER=llm`, project/scopes candidate pools are fused before at most one final LLM relevance pass; query/title/snippet data is bounded and JSON-encoded, and any timeout, provider error, invalid/incomplete score set, or four-call concurrency saturation preserves the adjusted order. The distinct `global=true` FTS-only ranker and supplemental global-preference hits are not reranked. `explain=true` attaches per-hit `score_details` (per-stream ranks, matched entities, raw FTS/cosine/entity inverse-frequency scores, the matched observation ids when the observation stream voted, RRF contributions, graph provenance including the typed edge kind (`causes`/`fixes`/`contradicts`) a neighbour was reached by, the page's evidence count, authority multiplier, and optional rerank score) to project/scopes hits plus a top-level `streams_active` list and a `timings` object with each stream's wall time in milliseconds (`fts_ms`, `entity_ms`, `vector_ms` for the stored-vector scans, `graph_ms`, `observation_ms`, `rerank_ms`; a stream that did not run is left out, and `scopes` searches sum per stream). Timings are read only on an explained query; the normal path takes no clock reading for them. The global FTS-only ranker reports its active stream and `fts_ms` without per-hit details; `as_of` reports no timings. `include_expired=true` also returns TTL-expired pages. `include_superseded=true` also returns superseded (non-latest) page versions across the FTS/entity/vector/graph streams, each hit labelled `superseded: true` (the current version is never marked); default-off is byte-identical to the latest-only behaviour, and `global=true` / `as_of` are unaffected. `pin_first=true` prepends the project's bounded pinned latest pages (`ReaderPool::list_pinned_pages`, cap 10) ahead of the fused hits, deduped by page id (a pinned page that also matches appears once, marked `pinned: true`) and re-truncated to the requested limit; it applies to single-project searches (default or `workspace`+`project`), is ignored on `scopes`/`global`/`as_of`, and default-off is byte-identical. `answer=true` (opt-in, off by default) additionally synthesizes a cited natural-language answer over the top hits via the configured LLM provider (`complete_structured`, JSON-schema `{ answer, citations }`), attached as `answer: { text, citations }`. Citation paths must identify exactly one supplied page version, including supplemental preferences. Repeated citations are deduplicated in model order. An unknown path or a path shared by distinct page IDs withholds the whole answer and returns `answer_unavailable` with the unchanged retrieval hits; this includes same-path historical versions. Empty citations remain valid for abstention. This validates source identity, not the truth of generated claims. With no provider configured it returns the hits plus an `answer_unavailable` note instead of erroring, and with `answer` unset/`false` no provider is accessed and the response is byte-identical (invariant #13). It applies to the normal single-project/`scopes` path; `global`/`as_of` ignore it. Optional `[query_answer] max_context_tokens` bounds synthesis admission while preserving all retrieval hits. Each UTF-8 input byte counts as one estimated token; serialized schema bytes and a fixed 1024-unit provider-envelope allowance also count, and the reasoning tier's output allowance is reserved separately. This is a conservative admission contract, not a guarantee for every provider's tokenizer or framing. Evidence follows ranking order, with a UTF-8-safe clipped final snippet only when at least 16 alphanumeric source characters remain (a syntactic minimum, not semantic verification). Empty and punctuation-only snippets are omitted. `answer_context` reports `admitted`, `omitted`, `clipped`, `estimated_input_tokens`, `reserved_output_tokens` and `max_context_tokens`; it appears only when admission runs. If fixed content or evidence cannot fit, the provider is not called and `answer_unavailable` accompanies the full hits. The question is never silently clipped. Citation validation uses only admitted sources. Superseded status is explicit in budgeted prompts. Clipping can remove a qualification or correction; callers should inspect the receipt and original hits. An explicit zero or undersized limit prevents synthesis; only omission disables admission. Omitted configuration preserves existing wire request and response bytes. Answer quality is not yet eval-validated. An optional `reasoning` tier (`minimal` (default) / `low` / `medium` / `high` / `max`) tunes the synthesis effort: `ChatRequest` carries no per-request reasoning field (the provider-level `reasoning_effort` is fixed at construction from config), so the tier maps to a per-tier max-token budget scaled off the path's base (answer base 2 000; `minimal` = 1x = byte-identical, `low` 1.5x, `medium` 2x, `high` 3x, `max` 4x). The tier is inert unless the `answer` LLM path runs (invariant #13); an unknown value is rejected by the schema (invariant #7). Optional `kind`, `tag`, `tier` and `path_prefix` filters narrow candidates before ranking, on every stream including the CJK substring search. |
-| `memory_query` | read-only | FTS5 + entity-match + graph RRF + optional vector RRF + observation-evidence stream (on by default) search, followed by bounded kind/tier/pinned/tag authority adjustment and raw fallback. Bumps access counters for page hits. Defaults to the current project; single-project calls (project implicit or named with `workspace`+`project`) also union the reserved `_global` preferences scope as `global_scope_hits`, and only an explicit multi-`scopes` set opts out (#930); `scopes` searches named sibling projects; `global=true` searches every project at once (each hit annotated with its workspace + project). With `AI_MEMORY_RERANKER=llm`, project/scopes candidate pools are fused before at most one final LLM relevance pass; query/title/snippet data is bounded and JSON-encoded, and any timeout, provider error, invalid/incomplete score set, or four-call concurrency saturation preserves the adjusted order. The distinct `global=true` FTS-only ranker and supplemental global-preference hits are not reranked. `explain=true` attaches per-hit `score_details` (per-stream ranks, matched entities, raw FTS/cosine/entity inverse-frequency scores, the matched observation ids when the observation stream voted, RRF contributions, graph provenance including the typed edge kind (`causes`/`fixes`/`contradicts`) a neighbour was reached by, the page's evidence count, authority multiplier, and optional rerank score) to project/scopes hits plus a top-level `streams_active` list and a `timings` object with each stream's wall time in milliseconds (`fts_ms`, `entity_ms`, `vector_ms` for the stored-vector scans, `graph_ms`, `observation_ms`, `rerank_ms`; a stream that did not run is left out, and `scopes` searches sum per stream). Timings are read only on an explained query; the normal path takes no clock reading for them. The global FTS-only ranker reports its active stream and `fts_ms` without per-hit details; `as_of` reports no timings. `include_expired=true` also returns TTL-expired pages. `include_superseded=true` also returns superseded (non-latest) page versions across the FTS/entity/vector/graph streams, each hit labelled `superseded: true` (the current version is never marked); default-off is byte-identical to the latest-only behaviour, and `global=true` / `as_of` are unaffected. `pin_first=true` prepends the project's bounded pinned latest pages (`ReaderPool::list_pinned_pages`, cap 10) ahead of the fused hits, deduped by page id (a pinned page that also matches appears once, marked `pinned: true`) and re-truncated to the requested limit; it applies to single-project searches (default or `workspace`+`project`), is ignored on `scopes`/`global`/`as_of`, and default-off is byte-identical. `answer=true` (opt-in, off by default) additionally synthesizes a cited natural-language answer over the top hits via the configured LLM provider (`complete_structured`, JSON-schema `{ answer, citations }`), attached as `answer: { text, citations }`. Citation paths must identify exactly one supplied page version, including supplemental preferences. Repeated citations are deduplicated in model order. An unknown path or a path shared by distinct page IDs withholds the whole answer and returns `answer_unavailable` with the unchanged retrieval hits; this includes same-path historical versions. Empty citations remain valid for abstention. This validates source identity, not the truth of generated claims. With no provider configured it returns the hits plus an `answer_unavailable` note instead of erroring, and with `answer` unset/`false` no provider is accessed and the response is byte-identical (invariant #13). It applies to the normal single-project/`scopes` path; `global`/`as_of` ignore it. Answer quality is not yet eval-validated. An optional `reasoning` tier (`minimal` (default) / `low` / `medium` / `high` / `max`) tunes the synthesis effort: `ChatRequest` carries no per-request reasoning field (the provider-level `reasoning_effort` is fixed at construction from config), so the tier maps to a per-tier max-token budget scaled off the path's base (answer base 2 000; `minimal` = 1x = byte-identical, `low` 1.5x, `medium` 2x, `high` 3x, `max` 4x). The tier is inert unless the `answer` LLM path runs (invariant #13); an unknown value is rejected by the schema (invariant #7). Optional `kind`, `tag`, `tier` and `path_prefix` filters narrow candidates before ranking, on every stream including the CJK substring search. |
++| `memory_query` | read-only | FTS5 + entity-match + graph RRF + optional vector RRF + observation-evidence stream (on by default) search, followed by bounded kind/tier/pinned/tag authority adjustment and raw fallback. Bumps access counters for page hits. Defaults to the current project; single-project calls (project implicit or named with `workspace`+`project`) also union the reserved `_global` preferences scope as `global_scope_hits`, and only an explicit multi-`scopes` set opts out (#930); `scopes` searches named sibling projects; `global=true` searches every project at once (each hit annotated with its workspace + project). With `AI_MEMORY_RERANKER=llm`, project/scopes candidate pools are fused before at most one final LLM relevance pass; query/title/snippet data is bounded and JSON-encoded, and any timeout, provider error, invalid/incomplete score set, or four-call concurrency saturation preserves the adjusted order. The distinct `global=true` FTS-only ranker and supplemental global-preference hits are not reranked. `explain=true` attaches per-hit `score_details` (per-stream ranks, matched entities, raw FTS/cosine/entity inverse-frequency scores, the matched observation ids when the observation stream voted, RRF contributions, graph provenance including the typed edge kind (`causes`/`fixes`/`contradicts`) a neighbour was reached by, the page's evidence count, authority multiplier, and optional rerank score) to project/scopes hits plus a top-level `streams_active` list and a `timings` object with each stream's wall time in milliseconds (`fts_ms`, `entity_ms`, `vector_ms` for the stored-vector scans, `graph_ms`, `observation_ms`, `rerank_ms`; a stream that did not run is left out, and `scopes` searches sum per stream). Timings are read only on an explained query; the normal path takes no clock reading for them. The global FTS-only ranker reports its active stream and `fts_ms` without per-hit details; `as_of` reports no timings. `include_expired=true` also returns TTL-expired pages. `include_superseded=true` also returns superseded (non-latest) page versions across the FTS/entity/vector/graph streams, each hit labelled `superseded: true` (the current version is never marked); default-off is byte-identical to the latest-only behaviour, and `global=true` / `as_of` are unaffected. `pin_first=true` prepends the project's bounded pinned latest pages (`ReaderPool::list_pinned_pages`, cap 10) ahead of the fused hits, deduped by page id (a pinned page that also matches appears once, marked `pinned: true`) and re-truncated to the requested limit; it applies to single-project searches (default or `workspace`+`project`), is ignored on `scopes`/`global`/`as_of`, and default-off is byte-identical. `answer=true` (opt-in, off by default) additionally synthesizes a cited natural-language answer over the top hits via the configured LLM provider (`complete_structured`, JSON-schema `{ answer, citations }`), attached as `answer: { text, citations }`. Citation paths must identify exactly one supplied page version, including supplemental preferences. Repeated citations are deduplicated in model order. An unknown path or a path shared by distinct page IDs withholds the whole answer and returns `answer_unavailable` with the unchanged retrieval hits; this includes same-path historical versions. Empty citations remain valid for abstention. This validates source identity, not the truth of generated claims. With no provider configured it returns the hits plus an `answer_unavailable` note instead of erroring, and with `answer` unset/`false` no provider is accessed and the response is byte-identical (invariant #13). It applies to the normal single-project/`scopes` path; `global`/`as_of` ignore it. Optional `[query_answer] max_context_tokens` bounds synthesis admission while preserving all retrieval hits. Each UTF-8 input byte counts as one estimated token; serialized schema bytes and a fixed 1024-unit provider-envelope allowance also count, and the reasoning tier's output allowance is reserved separately. This is a conservative admission contract, not a guarantee for every provider's tokenizer or framing. Answer admission gives known supersession successors priority over predecessors, and newer evidence priority within the same workspace/project and normalized exact title. A bounded metadata query reads only already-authorized hit IDs; canonical session pages use session start time rather than ingestion time. Unrelated evidence retains retrieval order. Whole snippets are admitted before any clipping. Otherwise-unused space may hold one final complete trailing sentence or statement, with ellipses marking removed text; a fragment with no complete boundary is omitted. The boundary rule recognizes sentence punctuation and code statement terminators and does not perform semantic inference. Empty and punctuation-only snippets are omitted. `answer_context` reports `admitted`, `omitted`, `clipped`, `estimated_input_tokens`, `reserved_output_tokens` and `max_context_tokens`; it appears only when admission runs. If fixed content or evidence cannot fit, the provider is not called and `answer_unavailable` accompanies the full hits. The question is never silently clipped. Citation validation uses only admitted sources. Superseded status is explicit in budgeted prompts. Clipping can remove a qualification or correction; callers should inspect the receipt and original hits. An explicit zero or undersized limit prevents synthesis; only omission disables admission. Omitted configuration preserves existing wire request and response bytes. Answer quality is not yet eval-validated. An optional `reasoning` tier (`minimal` (default) / `low` / `medium` / `high` / `max`) tunes the synthesis effort: `ChatRequest` carries no per-request reasoning field (the provider-level `reasoning_effort` is fixed at construction from config), so the tier maps to a per-tier max-token budget scaled off the path's base (answer base 2 000; `minimal` = 1x = byte-identical, `low` 1.5x, `medium` 2x, `high` 3x, `max` 4x). The tier is inert unless the `answer` LLM path runs (invariant #13); an unknown value is rejected by the schema (invariant #7). Optional `kind`, `tag`, `tier` and `path_prefix` filters narrow candidates before ranking, on every stream including the CJK substring search. |
| `memory_recent` | read-only | Most-recently-updated `is_latest=1` pages. |
| `memory_read_page` | read-only | Fetch the FULL body of a single wiki page by `path` or by top FTS5 hit for a `query`; optional `workspace` + `project` targets a named sibling workspace/project. Use when an agent needs more than the 24-word snippets from `memory_query`. `include_related=true` also walks the link graph outward from the page (bounded BFS reusing the `page_links` primitive per node: default 1 hop, hard cap 3, global visited set for dedup/cycle-safety, total-node cap 50, cross-project aware) and returns a `related` array of reachable pages, each labelled with its `depth` (hop distance) and `direction` (`link`/`backlink`); default-off is byte-identical (no `related` field). The response carries the page's current version as `page_id`, the value compare-and-write calls pass back. A page whose `expires_at` TTL has passed is still returned and carries `expired: true`; a live page's response has no such field. |
| `memory_read_session_observations` | read-only | Page through ONE session's raw hook observations (`ObservationRecord` with full sanitized body, capped per row by `body_max_chars`), restricted to the rows that landed in the resolved scope and to sessions the caller may see; `total` and `elided_other_scope` report the in-scope count and the rows the session left in another project. `session_id` omitted reads the visible session with the newest captured work other than the caller's own, ended or cut off (`ReaderPool::recent_session_activity` over 30 days, preferring the caller session's cwd), else the latest completed visible session. |
diff --cc docs/benchmarks/query-answer-context-draft.md
index d5661a9c,00000000..c60d7254
mode 100644,000000..100644
--- a/docs/benchmarks/query-answer-context-draft.md
+++ b/docs/benchmarks/query-answer-context-draft.md
@@@ -1,111 -1,0 +1,137 @@@
+# Query-answer context admission: draft local measurements
+
+This receipt accompanies the default-disabled proposal in #1684. Its configuration,
- response contract and pruning policy still need maintainer agreement. It measures
++response contract was accepted by the maintainer in the review on #1689. It measures
+builder size and local execution time, not answer correctness or provider usage.
+
+## Provenance
+
+- Feature base: `e7e17555efb6a95596480249598ad517ff587310`.
+- Citation-validation prerequisite: `91aa3d26df4df8064b270f8d5242cfca465d08d7`.
+- Candidate code: `71f9cd36015ab4a578641630714615e5b37f4768`.
+- Run: 2026-10-25 UTC, Linux 6.18.55 x86_64, AMD EPYC 9V74, 9 visible logical CPUs.
+- Rust: `1.95.0 (59807616e 2026-04-14)`, debug test profile, `CARGO_INCREMENTAL=0`.
+- Provider/model: none. No model requests or paid evaluations.
+- Fixture: `server::tests::answer_budget_measurements`; SHA-256 of that function's
+ source through the following helper boundary:
+ `570d36eca47aaf411461991588642fbc432124ed6800bd99c1f1fe1d81bbd6e7`.
+- CSV SHA-256: `83d1ead149d3fe2c0108135ca6440fd8b29db39b872453cab918b66da4c787ed`.
+- Published candidate tree equals local tested commit `bd3179ef5d89ebdc5bd71167425d821d0c6e9f5e`
+ (tree `ac2c5787080eab464d7958a09ccc0c1733c64f41`).
+- Both modes ran in the candidate binary. Disabled admission delegates to the
+ unchanged baseline builder; this is a mode comparison, not two separately
+ compiled binaries. The disabled-request regression test compares their fields.
+
+The fixture uses 1, 10, 50 and 100 hits, each with a 240-scalar snippet, across
+ASCII, pt-BR, CJK and code. Questions are either 32 bytes or 160,000 bytes. Each
+mode uses 20 warmup calls and 31 timed trials of 20 calls. The CSV records per-call
+p50 and p95 nanoseconds from those trials. Other builds ran on the shared host,
+so these debug timings are exploratory and do not establish production latency.
+
+## Results
+
+The table shows the 100-hit short-question cases. Content bytes count only system
+and user messages. The enabled mode also counts serialized schema bytes and 1024
+envelope units, then reserves 2000 output tokens, within its 16000-unit target.
+The one-byte-per-estimated-input-token contract is not a tokenizer guarantee.
+
+| Fixture | Disabled bytes | Enabled bytes | Byte reduction | Admitted / omitted / clipped | Disabled p50 / p95 µs | Enabled p50 / p95 µs |
+|---|---:|---:|---:|---|---:|---:|
+| ascii | 31422 | 12156 | 61.31% | 35 / 65 / 0 | 261.37 / 270.36 | 185.12 / 200.18 |
+| pt-BR | 32922 | 12191 | 62.97% | 34 / 66 / 1 | 270.66 / 291.94 | 194.16 / 228.80 |
+| CJK | 79422 | 12189 | 84.65% | 15 / 85 / 1 | 728.71 / 1087.62 | 179.16 / 195.91 |
+| code | 31422 | 12156 | 61.31% | 35 / 65 / 0 | 250.47 / 491.15 | 179.76 / 276.06 |
+
+All long-question cases produced no request in the enabled mode. Their receipt
+can report estimated input above the limit: it explains the refused request,
+not a prompt sent to a provider. CSV `NA` means disabled mode has no input-token
+estimate; it does not mean zero tokens. `content_bytes=0` with `request_built=false`
+means no request was built.
+
+The one-hit ASCII case added local work: p50 rose from 5.317 µs to 49.540 µs,
+including schema sizing. Larger cases did less rendering because they omitted
+sources. No overhead acceptance threshold has been agreed.
+
+The CJK case admits only 15 of 100 sources at this conservative budget. Clipping
+can remove a correction or qualification. Deterministic tests check that supplied
+corrections remain intact when they fit and that superseded status is labelled;
+answer accuracy under pruning remains unmeasured and blocks a ready-for-review
+claim. Retrieval hits and ranking remain unchanged.
+
+Full measurements: [CSV](query-answer-context-draft.csv).
+
- ## Offline evidence-retention regression
++## Historical evidence-retention result (before review changes)
+
+`answer_budget_labeled_evidence_retention_boundaries` uses labeled English,
+pt-BR, CJK and code fixtures with an exact required current-fact literal. It
+checks the prompt produced by the actual builder, without a provider. Its
+16 cases specify these outcomes for each language:
+
+| Budget/order boundary | Required current-fact literal | Admission |
+|---|---|---|
+| Exact fit, history followed by correction in one snippet | Retained | 1 admitted, 0 omitted, 0 clipped |
+| Same snippet, allowance ends before its correction | Lost | 1 admitted, 0 omitted, 1 clipped |
+| Historical source first; only that source fits | Lost | 1 admitted, 1 omitted, 0 clipped |
+| Current correction first; only that source fits | Retained | 1 admitted, 1 omitted, 0 clipped |
+
+Measured on 2026-10-25 with local source commit
+`94293327faa450b52d13bea584e89865c185ac56`, Rust 1.95.0, on the Linux host
+described above: the disabled-mode baseline retained the required literal in
+16 of 16 cases; the bounded candidate retained it in 8 of 16 cases. These are
+deliberate boundary probes, not representative quality estimates or model-answer
+accuracy scores. One deterministic run records baseline and candidate retention
+separately for every case; it makes no provider calls.
+
+The assertions also reconstruct input accounting from the request and schema,
+check the configured bound, verify admitted/omitted citation identities, and
+compare full retrieval hits before and after admission. Historical-first
+fixtures mark the admitted historical source `superseded: true`; that label
+does not recover an omitted correction. Lines prefixed `C2RETENTION,` report
+the asserted outcomes when run with `--nocapture`.
+
+This is a literal-retention regression, not model answer-quality evaluation.
+The two loss cases deliberately pass only when they expose the known loss;
+they do not establish acceptable pruning quality. Clipping and ranked-prefix
+omission can remove the current fact while leaving historical evidence available
+for synthesis. That unresolved policy risk and maintainer contract agreement
+still block readiness. No prompt-only abstention guarantee is claimed.
+
+```sh
+cargo test -p ai-memory-mcp --lib answer_budget_labeled_evidence_retention_boundaries -- --nocapture
+```
+
+## Reproduce
+
+```sh
+cargo test -p ai-memory-mcp --lib answer_budget_measurements -- --ignored --nocapture
+```
+
+Lines beginning `C2CSV,` contain the receipt. Remove that prefix to recover the
+CSV. No provider configuration is needed. The test is ignored in normal CI so
+its timing loop does not become part of the everyday test run.
++
++## Reviewed admission policy
++
++The revised policy orders same-topic evidence by explicit supersession first,
++then evidence time within the same workspace/project and normalized exact title.
++Canonical session pages use session start time, so late ingestion cannot make
++an older session appear newer. This is a narrow metadata-based topic rule;
++prose similarity alone does not establish a topic relationship.
++
++It first admits whole snippets, skipping items that do not fit. If a newer
++correction was skipped, its known obsolete predecessor cannot consume that
++allowance instead. After whole-snippet selection, unused space can hold one
++complete trailing sentence or statement from an omitted snippet. Partial
++sentences and unsplittable text are omitted. Unicode punctuation and code
++statement boundaries are supported; this is a syntactic boundary rule, not a
++language parser. Wrapped prose newlines and semicolons do not permit clipping. Ellipses and the receipt make omissions visible.
++
++The original sixteen literal-retention probes now require all corrections to
++remain present. Additional tests cover same-topic session chronology, lineage
++over imported timestamps, independent topics/scopes, whole-snippet priority
++and safe refusal when no complete sentence fits. These probes do not measure
++model answer accuracy or prove that arbitrary omitted evidence is irrelevant.
++The earlier timings and 8/16 result above remain historical measurements.
++
++A snippet with an incomplete trailing qualification is omitted rather than
++clipped back to an earlier complete sentence; that tail might reverse the rule.
diff --cc docs/security-boundaries.md
index 8cd9f616,0a8e5aa0..5ebe363e
--- a/docs/security-boundaries.md
+++ b/docs/security-boundaries.md
@@@ -35,6 -41,6 +41,7 @@@ the legitimate restricted-project contr
| 1i | SessionEnd's bounded digest cannot read a foreign session by raw id | `ai-memory-store/src/reader.rs` `session_has_substantive_observation` joins the session row to the caller's `(workspace_id, project_id)`; `read_session_observations` validates that same tuple inside the read transaction before exposing its bounded snapshot, returning the same `SessionCollision` refusal for foreign and missing ids; `ai-memory-hooks/src/router.rs` supplies only the scope pinned by hook admission | `multi_session.rs` `session_end_readers_refuse_foreign_session_ids` (sibling-project and cross-workspace tuples cannot learn the substantive bit or open the snapshot; a missing id gets the same refusal; the owning tuple reads the one-row summary as the legitimate control). Removing either scope predicate fails its corresponding assertion | STRONG |
| 1i2 | The consolidation session read fails closed on a session with no observations in its target scope, and memory is bounded by the selection, not the session | `ai-memory-store/src/reader.rs` `read_session_observations_in_scope` opens the bounded session snapshot only when at least one observation of the session exists in the caller's `(workspace_id, project_id)` (an `EXISTS` over `observations`), returning `SessionCollision` for foreign, purged and missing alike; `SessionObservationSnapshot::projection_totals` reads `COUNT(*)` and `MIN`/`MAX(created_at)` in one aggregate inside the same read transaction; `SessionObservationSnapshot::row_by_rowid` re-reads a single row only when both `session_id = ?1` and `rowid = ?2` match, so a legitimate snapshot cannot fetch another session's body by raw rowid; `ai-memory-consolidate/src/projection.rs` `project_session_observations` streams rows one at a time, keeping only the two anchors' rowids and a bounded top-k heap of the best `limit - 2` rows (the shared `selection_key` the in-memory path sorts with), re-reading only the selected rows by rowid; residue candidate lists exist only while the opt-in residue is on; `ai-memory-consolidate/src/consolidator.rs` `consolidate_session` / `consolidate_session_multi` gate on the scope `resolve_target` already resolves (the observations' majority scope) and map the refusal to `EmptySession`, exactly as an empty session did before; auto-improve keeps its `session_project_ids` gate plus the sessions-row-gated `read_session_observations` (row 1i), and computes preflight, duration, report and prompt from one single snapshot read — a purge committed between the totals aggregate and the preflight decision cannot split the two generations, and a rowless session with the preflight minimums disabled is still reviewed with the empty `(none)` projection, as the full-load path did | `tests/suite/bounded_session_load.rs` `gated_reader_refuses_foreign_scopes` (a foreign workspace and a foreign project are refused with `SessionCollision`; the session's own scope reads the totals as the legitimate control), store `tests/suite/multi_session.rs` `rowid_fetch_refuses_foreign_sessions_with_legitimate_control` (a foreign session's rowid is refused through a legitimate snapshot in both directions; the session's own rowid reads as the control; removing only the session predicate from the rowid fetch fails it), `purged_session_is_refused_without_an_llm_call` (both entry points fail closed with `EmptySession` and no LLM call once the rows are gone), `stale_sessions_row_does_not_divert_the_write` (a sessions row frozen on another project does not move the write out of the observations' project), `hybrid_two_project_session_prompt_is_unchanged` (a two-project session keeps today's exact prompt: every row of the session id is projected, the page lands in the majority project), `streaming_projection_matches_the_frozen_base_projection` and `current_projection_matches_the_frozen_base_projection` (the new paths agree field for field with a verbatim frozen copy of the pre-change `projection.rs` — an independent rule — at the 256/257/300 sample-cap edges and below), `large_session_prompts_match_the_old_full_load_path` (at 150k, 100k and 5k rows the streaming prompts are byte-identical to the frozen projection and both `#[cfg(test)]` full-load oracles, with the top-k heap asserted bounded by the selection cap and zero residue tuples while residue is off), `auto_improve_review_uses_one_generation_of_the_session` (a purge committed inside the review's single snapshot read cannot split the report's count from the prompt's), `auto_improve_review_of_a_rowless_session_with_preflight_off` (a present rowless session with zero minimums still gets its `(none)` review), `zero_budget_streaming_path_keeps_the_old_no_budget_marker` (the zero-budget early return reaches the streaming path byte-identically), and the byte-identical equivalence tests against the full-load oracles (below and above the cap, residue on/off, character-budget pruning, `created_at` ties, 16-KiB bodies, routing text, auto-improve at/above its 48/72 limits and preflight) | STRONG — the LLM input is proven byte-identical to the pre-change full load, including against a frozen verbatim copy of the base projection; dropping the `EXISTS` predicate fails `gated_reader_refuses_foreign_scopes`; removing only the session predicate from the rowid fetch fails the store `rowid_fetch_refuses_foreign_sessions_with_legitimate_control` |
| 1j | Synthesized answer citations refer only to unambiguous evidence supplied in that request | `ai-memory-mcp/src/server.rs` `build_answer_request` records path-to-`PageId` identity while rendering snippets; `validate_answer_citations` refuses unknown or ambiguous paths before returning any answer text | `query_answer.rs` `answer_rejects_a_citation_not_in_the_request`, `answer_rejects_a_citation_from_an_unqueried_project`, `answer_rejects_same_path_citations_across_scopes`, `answer_global_preferences_accept_unique_paths_and_refuse_collisions`; controls: `answer_true_with_provider_synthesizes_cited_answer`, `answer_deduplicates_citations_in_model_order_and_preserves_unicode`; `server.rs` `answer_sources_distinguish_repeated_rows_from_ambiguous_paths` | STRONG for source identity (the four refusal cases fail with the validator guard removed); generated claims and citation-free abstentions are not semantically verified |
++| 1k | Budgeted answer chronology uses only retrieved IDs and same-scope session timestamps | `memory_query` passes only authorized hit IDs to bounded `answer_evidence_metadata`; its session join checks workspace and project and never expands links; evidence priority is scoped | Store `answer_evidence_metadata_returns_only_requested_ids_without_expanding_links`, `answer_evidence_metadata_uses_session_time_only_in_the_same_scope`; MCP `answer_budget_uses_store_recency_without_reordering_retrieval_hits`; unit `answer_budget_unrelated_scopes_titles_and_equal_times_preserve_rank` | Adversarial requested-only and foreign-session controls; mutation results recorded in the PR |
| 2 | Workspace isolation | same as #1; same-named project → distinct ids per workspace | `scope.rs` cross-workspace resolution rows; `multi_scope` dedup/validate; `ai-memory-web` `history_replay.rs` (another workspace's page path, version id and session id answer 404, same tests and bites as row 1) | STRONG |
| 2b | Managed-workstream discovery stays checkout-local, including pagination | `ai-memory-workstream/src/repository.rs` `inspect_repository_fingerprints` shares the launch identity derivation without checkpoint scans; `ai-memory-cli/src/commands/resume.rs` `candidates_for_checkout` queries only the cwd, never registry links; the explicit `--all` walk (`candidates_across_checkouts`) lists each linked checkout through its own fingerprint-scoped request and applies `--workspace` before any request; `ai-memory-hooks/src/workstream.rs` `list_recent_workstreams` resolves an authorized explicit scope on every page; `ai-memory-store/src/workstream.rs` `list_recent` applies workspace/project/repository/worktree predicates before `LIMIT`/`OFFSET` | `resume.rs` `resume_lists_all_current_checkout_rows_not_registered_foreign_checkouts` (same scope/remote foreign checkout refused, 125 local rows visible), `empty_current_checkout_does_not_fall_back_to_the_registry`, `resume_all_walks_every_linked_checkout_and_honours_the_workspace_filter` (a foreign workspace filter sends no request; the default picker still ignores the registry); `workstream.rs` `recent_workstream_pages_reach_older_rows_without_crossing_checkout_or_scope` (foreign repo, worktree, project and workspace excluded on every page; 105 legitimate rows reach the client, huge offsets return nothing); store `recent_workstreams_are_checkout_local_and_include_linked_harnesses` (page two keeps native harness links); `repository.rs` `reports_origin_push_url_and_linked_worktree` verifies lightweight/full fingerprint parity and distinct worktree keys; CLI `resume_yolo_displays_picker_without_scanning_git_status` verifies listing skips status scans | STRONG |
| 3 | Multi-user auth ladder | `ai-memory-core/src/actor.rs` `AuthLevel::authorize`; `ai-memory-mcp/src/auth.rs` middleware; `admin.rs` `require_root_for_multiuser_admin` / `require_root`; `identity.rs` authorizes `NormalRead` behind the same machine bearer middleware as MCP; `serve.rs` mounts API-only and web+API protected routers behind `require_dual_auth` | `admin.rs` `multiuser_admin_routes_reject_db_user_tier` / `…reject_anonymous` / `create_user_as_user_tier_returns_403`; `auth.rs` unknown-bearer 401; `actor.rs` `skip_admission_chain_rejects_db_users`; `identity.rs` `identity_real_auth_isolates_users_root_and_revoked_keys`, `identity_anonymous_ignores_forged_headers_and_proxy_qualifies_oidc` (distinct users and root, invalid/revoked keys, forged headers, anonymous control); `serve.rs` `api_only_mode_keeps_data_authenticated_and_web_absent` (anonymous API read refused, authenticated control admitted, browser route absent; #986) | STRONG |
@@@ -215,10 -221,3 +222,18 @@@ classification fails the test. Coverage
defects, so the guards live at integration level (`multi_session.rs`,
`handoff_ownership.rs`, `agent_messages.rs`, `active_project` pointer tests,
the MCP permission suites). Put boundary tests there.
+
+Query-answer input admission (when configured) validates citations only against
+admitted source identities. `server::tests::answer_budget_keeps_ranked_evidence_and_excludes_omitted_citations`
+attempts an omitted-source citation and checks a legitimate admitted citation;
+`query_answer::answer_budget_never_calls_provider_without_evidence_and_keeps_hits`
+checks the no-evidence provider boundary. The configuration does not change
+retrieval scope or authorize additional data access.
++
++Budgeted-answer recency uses metadata for at most 300 already-authorized hit IDs,
++without loading bodies or expanding supersession links. The store tests
++`answer_evidence_metadata_returns_only_requested_ids_without_expanding_links`
++and the session chronology test cover requested-only and same-scope joins.
++`answer_budget_uses_store_recency_without_reordering_retrieval_hits` verifies
++the production metadata-to-prompt path; existing foreign-project citation and
++shared-path ambiguity tests continue to enforce the authorization boundary.