Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(mcp): validate synthesized answer citation identities
Mihael Zamin Sousa0c7e8a42f6f3
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 77cfb862..fb9c5b93 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -11,6 +11,16 @@ version in [`docs/changelog/`](docs/changelog/):## [Unreleased]+### Fixed++- `memory_query(answer=true)` now validates model-generated citation paths+ against the snippets supplied in that request. Unknown paths and paths+ shared by distinct page versions withhold the answer, while retrieval hits+ remain available with an `answer_unavailable` note. Repeated citations are+ deduplicated in model order; the default query path makes no added calls+ (#1682).++## [3.2.3] - 2026-10-24### Changeddiff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex 9670f6f0..08d3baf9 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -939,8 +939,9 @@ async fn rerank_page_hits(/// Synthesized "dialectic" answer attached to a `memory_query` response when/// the caller opts in with `answer=true` and a provider is configured. The-/// `text` is a natural-language answer drawn strictly from the retrieved hit-/// snippets; `citations` are the page paths the model reported drawing from.+/// `text` is generated by the model from the supplied snippets;+/// `citations` are model-reported paths validated against the request's+/// evidence. This checks source identity, not whether each claim is supported.#[derive(Debug, Serialize)]struct QueryAnswer {text: String,@@ -3290,7 +3291,7 @@ impl AiMemoryServer {let (answer, answer_unavailable) = if args.answer.unwrap_or(false) {match self.llm.as_ref() {Some(llm) => {- let request = build_answer_request(+ let (request, sources) = build_answer_request(&args.query,&hits,&global_scope_hits,@@ -3305,13 +3306,17 @@ impl AiMemoryServer {).await{- Ok(synth) => (- Some(QueryAnswer {- text: synth.answer,- citations: synth.citations,- }),- None,- ),+ Ok(synth) => match validate_answer_citations(synth, &sources) {+ Some(answer) => (Some(answer), None),+ None => (+ None,+ Some(+ "answer citations did not identify unambiguous supplied evidence; \+ returning hits without an answer"+ .into(),+ ),+ ),+ },Err(e) => {// Redacted fields only: the `Display` of a provider// failure carries the upstream response body, and@@ -7691,10 +7696,8 @@ fn build_explore_request(/// `prompts/explore_system.md`.const EXPLORE_SYSTEM_PROMPT: &str = include_str!("../prompts/explore_system.md");-/// System prompt for the opt-in `memory_query(answer=true)` synthesis. Keeps-/// the model strictly grounded in the supplied snippets and forces the cited-/// paths to come from the provided context (invariant against fabricated-/// citations).+/// System prompt for the opt-in `memory_query(answer=true)` synthesis.+/// Citation membership is enforced separately after the provider returns.const ANSWER_SYSTEM_PROMPT: &str = "You answer a user's question using ONLY the \numbered memory-page snippets provided. Do not use any outside knowledge. \Write a concise, direct answer grounded strictly in those snippets. In \@@ -7703,17 +7706,46 @@ const ANSWER_SYSTEM_PROMPT: &str = "You answer a user's question using ONLY thesnippets do not contain enough information to answer, say so plainly in \`answer` and return an empty `citations` list.";+// A PageId identifies one scoped page version. A path shared by distinct IDs+// cannot identify which scope or version a path-only citation means; None marks+// that ambiguity without changing the public response or querying the store.+type AnswerSources<'a> = HashMap<&'a str, Option<PageId>>;++fn validate_answer_citations(+ synth: AnswerSynthesis,+ sources: &AnswerSources<'_>,+) -> Option<QueryAnswer> {+ if synth+ .citations+ .iter()+ .any(|path| !sources.get(path.as_str()).is_some_and(Option::is_some))+ {+ return None;+ }+ let mut seen = HashSet::new();+ let citations = synth+ .citations+ .iter()+ .filter(|path| seen.insert(path.as_str()))+ .cloned()+ .collect();+ Some(QueryAnswer {+ text: synth.answer,+ citations,+ })+}+/// 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/// and cite exact paths. Snippets are stripped of the FTS `<mark>` HTML so the/// model sees clean text.-fn build_answer_request(+fn build_answer_request<'a>(query: &str,- hits: &[QueryHit],- global_scope_hits: &[QueryHit],+ hits: &'a [QueryHit],+ global_scope_hits: &'a [QueryHit],reasoning: ReasoningTier,-) -> ai_memory_llm::ChatRequest {+) -> (ai_memory_llm::ChatRequest, AnswerSources<'a>) {fn clean(snippet: &str) -> String {ai_memory_store::plain_snippet(snippet)}@@ -7722,8 +7754,17 @@ fn build_answer_request(user.push_str(query);user.push_str("\n\n## Memory page snippets\n\n");let mut n = 0usize;+ let mut sources = AnswerSources::new();for hit in hits.iter().chain(global_scope_hits.iter()) {n += 1;+ sources+ .entry(hit.hit.path.as_str())+ .and_modify(|id| {+ if *id != Some(hit.hit.id) {+ *id = None;+ }+ })+ .or_insert(Some(hit.hit.id));user.push_str(&format!("{}. path: `{}`\n title: {}\n snippet: {}\n\n",n,@@ -7735,7 +7776,7 @@ fn build_answer_request(if n == 0 {user.push_str("(no snippets matched the query)\n\n");}- ai_memory_llm::ChatRequest {+ let request = ai_memory_llm::ChatRequest {system: Some(ANSWER_SYSTEM_PROMPT.into()),messages: vec![ai_memory_llm::ChatMessage {role: ai_memory_llm::Role::User,@@ -7745,7 +7786,8 @@ fn build_answer_request(// (byte-identical to the pre-tier answer path).max_tokens: reasoning.scale_max_tokens(2_000),temperature: Some(0.1),- }+ };+ (request, sources)}/// Synthetic anonymous request `Parts` for callers arriving without request@@ -8151,6 +8193,35 @@ mod tests {.collect()}+ #[test]+ fn answer_sources_distinguish_repeated_rows_from_ambiguous_paths() {+ let mut hits: Vec<QueryHit> = rerank_test_hits(3)+ .into_iter()+ .map(|(hit, _)| QueryHit::from(hit))+ .collect();+ hits[1].hit = hits[0].hit.clone();+ let path = hits[0].hit.path.as_str().to_owned();+ let (_, sources) = build_answer_request("query", &hits[..2], &[], ReasoningTier::Minimal);+ let answer = || AnswerSynthesis {+ answer: "A supported answer".into(),+ citations: vec![path.clone(), path.clone()],+ };+ assert_eq!(+ validate_answer_citations(answer(), &sources)+ .unwrap()+ .citations+ .as_slice(),+ std::slice::from_ref(&path)+ );++ // Different scoped rows (or versions) can have the same path. A later+ // repeat of the first row must not erase that ambiguity.+ hits[2].hit.path = hits[0].hit.path.clone();+ hits.swap(1, 2);+ let (_, sources) = build_answer_request("query", &hits, &[], ReasoningTier::Minimal);+ assert!(validate_answer_citations(answer(), &sources).is_none());+ }+#[tokio::test]async fn reranker_reorders_one_bounded_prefix_without_shrinking_large_limits() {let (_tmp, _store, server, _ws, _proj) = setup_server().await;diff --git a/crates/ai-memory-mcp/tests/suite/query_answer.rs b/crates/ai-memory-mcp/tests/suite/query_answer.rsindex c7241334..ee56b611 100644--- a/crates/ai-memory-mcp/tests/suite/query_answer.rs+++ b/crates/ai-memory-mcp/tests/suite/query_answer.rs@@ -41,6 +41,7 @@ const PROJ: &str = "scratch";/// synthesized shape AND that the default path never touches the LLM.struct FakeAnswerLlm {calls: Arc<AtomicUsize>,+ response: Value,}#[async_trait::async_trait]@@ -69,10 +70,7 @@ impl LlmProvider for FakeAnswerLlm {) -> LlmResult<serde_json::Value> {self.calls.fetch_add(1, Ordering::SeqCst);// Shape must deserialize into the server's answer-synthesis struct.- Ok(json!({- "answer": "The widget subsystem stores its needle in notes/topic.md.",- "citations": ["notes/topic.md"],- }))+ Ok(self.response.clone())}}@@ -100,6 +98,17 @@ fn mount(server: AiMemoryServer) -> Router {/// Build a harness; `with_provider` decides whether a fake LLM is attached.async fn harness(with_provider: bool) -> Harness {+ harness_with_response(+ with_provider,+ json!({+ "answer": "The widget subsystem stores its needle in notes/topic.md.",+ "citations": ["notes/topic.md"],+ }),+ )+ .await+}++async fn harness_with_response(with_provider: bool, response: Value) -> Harness {let tmp = TempDir::new().expect("tempdir");let store = Store::open(tmp.path()).expect("store");let ws = store.writer.get_or_create_workspace(WS).await.expect("ws");@@ -115,6 +124,7 @@ async fn harness(with_provider: bool) -> Harness {let calls = Arc::new(AtomicUsize::new(0));let provider: Arc<dyn LlmProvider> = Arc::new(FakeAnswerLlm {calls: calls.clone(),+ response,});server = server.with_llm(provider);Some(calls)@@ -351,6 +361,207 @@ async fn answer_true_without_provider_degrades_gracefully() {);}+#[tokio::test]+async fn answer_rejects_a_citation_not_in_the_request() {+ let h = harness_with_response(+ true,+ json!({+ "answer": "Invented answer must not escape.",+ "citations": ["notes/topic.md", "notes/fabricated.md"],+ }),+ )+ .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(), "unsupported answer: {resp}");+ assert!(+ resp.get("answer_unavailable").is_some(),+ "missing reason: {resp}"+ );+ assert!(!resp.to_string().contains("Invented answer"));+ assert!(!resp.to_string().contains("fabricated.md"));+ assert_eq!(h.calls.as_ref().unwrap().load(Ordering::SeqCst), 1);+}++#[tokio::test]+async fn answer_rejects_a_citation_from_an_unqueried_project() {+ let h = harness_with_response(+ true,+ json!({+ "answer": "Foreign answer must not escape.",+ "citations": ["notes/foreign.md"],+ }),+ )+ .await;+ seed_needle(&h).await;+ let foreign = h+ .store+ .writer+ .get_or_create_project(h.ws, "foreign", None)+ .await+ .unwrap();+ h.store+ .writer+ .upsert_page(page(+ h.ws,+ foreign,+ "notes/foreign.md",+ "needle foreign secret",+ ))+ .await+ .unwrap();+ 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(), "foreign citation: {resp}");+ assert!(resp.get("answer_unavailable").is_some());+ assert!(!resp.to_string().contains("foreign"));+ assert_eq!(h.calls.as_ref().unwrap().load(Ordering::SeqCst), 1);+}++#[tokio::test]+async fn answer_rejects_same_path_citations_across_scopes() {+ let h = harness(true).await;+ seed_needle(&h).await;+ let foreign_ws = h+ .store+ .writer+ .get_or_create_workspace("other")+ .await+ .unwrap();+ let foreign = h+ .store+ .writer+ .get_or_create_project(foreign_ws, PROJ, None)+ .await+ .unwrap();+ h.store+ .writer+ .upsert_page(page(+ foreign_ws,+ foreign,+ "notes/topic.md",+ "needle from another workspace",+ ))+ .await+ .unwrap();+ let resp = call(+ &h.router,+ "memory_query",+ json!({+ "query": "needle", "answer": true,+ "scopes": [{"workspace": WS, "project": PROJ}, {"workspace": "other", "project": PROJ}],+ }),+ )+ .await;+ assert_eq!(hit_paths(&resp).len(), 2, "both scopes must match: {resp}");+ assert!(resp.get("answer").is_none(), "ambiguous citation: {resp}");+ assert!(resp.get("answer_unavailable").is_some());+ assert_eq!(h.calls.as_ref().unwrap().load(Ordering::SeqCst), 1);+}++#[tokio::test]+async fn answer_deduplicates_citations_in_model_order_and_preserves_unicode() {+ let paths = ["notes/decisão.md", "notes/topic.md", "notes/決定.md"];+ let h = harness_with_response(+ true,+ json!({+ "answer": "All three snippets mention needle.",+ "citations": [paths[0], paths[1], paths[0], paths[2], paths[1]],+ }),+ )+ .await;+ for path in paths {+ h.store+ .writer+ .upsert_page(page(h.ws, h.proj, path, "needle appears here"))+ .await+ .unwrap();+ }+ let resp = call(+ &h.router,+ "memory_query",+ query_args("needle", json!({"answer": true})),+ )+ .await;+ assert_eq!(resp.pointer("/answer/citations"), Some(&json!(paths)));+ assert!(resp.get("answer_unavailable").is_none());+ assert_eq!(h.calls.as_ref().unwrap().load(Ordering::SeqCst), 1);+}++#[tokio::test]+async fn answer_global_preferences_accept_unique_paths_and_refuse_collisions() {+ for (path, accepted) in [("notes/global.md", true), ("notes/topic.md", false)] {+ let h = harness_with_response(+ true,+ json!({+ "answer": "The global preference mentions needle.",+ "citations": [path],+ }),+ )+ .await;+ seed_needle(&h).await;+ let global = ai_memory_store::create_global_scope(&h.store.writer)+ .await+ .unwrap();+ h.store+ .writer+ .upsert_page(page(+ global.workspace_id,+ global.project_id,+ path,+ "needle global preference",+ ))+ .await+ .unwrap();+ let resp = call(+ &h.router,+ "memory_query",+ query_args("needle", json!({"answer": true})),+ )+ .await;+ assert_eq!(resp["global_scope_hits"].as_array().unwrap().len(), 1);+ assert_eq!(resp.get("answer").is_some(), accepted, "{resp}");+ assert_eq!(+ resp.get("answer_unavailable").is_some(),+ !accepted,+ "{resp}"+ );+ assert_eq!(h.calls.as_ref().unwrap().load(Ordering::SeqCst), 1);+ }+}++#[tokio::test]+async fn answer_preserves_empty_citations_for_abstention() {+ let h = harness_with_response(+ true,+ json!({+ "answer": "The snippets do not contain enough information.",+ "citations": [],+ }),+ )+ .await;+ seed_needle(&h).await;+ let resp = call(+ &h.router,+ "memory_query",+ query_args("needle", json!({"answer": true})),+ )+ .await;+ assert_eq!(resp.pointer("/answer/citations"), Some(&json!([])));+ assert!(resp.get("answer_unavailable").is_none());+}+/// 4. Live smoke test: wire a real provider only when a key is in the/// environment, and assert a non-empty answer. Skips cleanly (and is/// `#[ignore]`d) so it never runs in CI or reads a key that isn't set. Rundiff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 7671424d..35ac64a8 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -729,7 +729,7 @@ does not need to ride on the public protocol change.| 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 }`; 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. 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 --git a/docs/security-boundaries.md b/docs/security-boundaries.mdindex ae475285..eaa13709 100644--- a/docs/security-boundaries.md+++ b/docs/security-boundaries.md@@ -34,6 +34,7 @@ means the boundary is not built yet.| 1h | The profile learns only from what it may: the user's own prompts and curated pages, from contributing projects, never another operator's words in a private profile and never a restricted project in a shared one; stored text stays data | `ai-memory-store/src/profile.rs` `profile_prompts_since` (only `user-prompt` observations), `auto_improve_decided_by` (the decider agent a page's `auto_improve_proposal_id` resolves to), `profile_harvest_projects` / `profile_candidates` (`profile_contribute = 0` excluded, including candidates recorded before the opt-out); `ai-memory-store/src/ops.rs` `move_session` (a moved session's `session:<id>` prompt candidates are re-stamped into the target project in the same transaction, so they answer to its contribute flag and access mode, #1265); `ai-memory-consolidate/src/profile.rs` `user_written` (shared with the verbatim-residue caller in row 25: a harness turn or Codex's injected instructions stored as a prompt is skipped whole, and ai-memory's routing and untrusted-history blocks, fenced by markers on their own lines, are cut out before any sentence is read), the auto-approved-proposal skip in `harvest_project` (a page the auto-improve scheduler auto-approved is model output nobody reviewed and never becomes a candidate; a human-approved page, or one whose proposal id has no row, stays curated, #1211), `convergence_targets` (a `user` target keeps only candidates whose `contributor` is that operator, from projects the per-project choke point lets them read; a `global`/`workspace` target on an operator-distinguishing server drops restricted projects), `min_contributors` / `converge` (a team profile admits a statement only on evidence from at least two distinct operators, so one operator cannot plant a default in everyone's session start) (never rewrites a page without its `generated_by` stamp or whose body changed; `profile_entry_ledger` keeps a forgotten entry out), `classify_batch` / `merge_entry` (sanitized, JSON-encoded input; the evidence quote is always the user's sentence) | consolidate `integration::profile_harvest` `tool_output_is_never_a_candidate`, `an_opted_out_project_is_never_harvested`, `a_private_profile_never_harvests_another_operator`, `a_team_profile_never_harvests_a_restricted_project`, `a_team_profile_needs_more_than_one_operator` (one operator in two open projects not admitted; a second operator admits it; fails with the threshold at one), `a_personal_profile_admits_one_operators_habit` (control), `a_hand_edited_entry_is_never_clobbered`, `a_forgotten_entry_is_not_recreated_until_said_again`, `injected_instructions_stay_data`, `injected_instructions_and_ai_memory_blocks_are_never_candidates`, `page_metadata_fields_are_never_candidates`, `auto_approved_auto_improve_pages_are_never_candidates` (an auto-approved page refused; human-approved and hand-written controls admitted; fails with the decider check removed), consolidate `profile::tests::a_stored_page_metadata_field_is_not_a_waiting_habit` (each with a legitimate control; each fails with its guard removed); mcp `integration::admin_profile_routes` `review_and_rebuild_are_root_only_on_a_multi_user_server`; store `integration::session_move` `a_moved_sessions_profile_candidate_follows_the_target_projects_governance` (a session moved into an opted-out project stops counting and one moved into a restricted project is marked restricted; an open-target control still counts, from the target; fails with the `move_session` re-stamp removed); residue control in row 25 | STRONG || 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 || 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 |