From 66b62acfd5072ce8dbfb46b07c495d4180545e4a Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 13:56:49 +0800
Subject: [PATCH 01/30] refactor: convert canvas.rs to canvas/mod.rs (prep for
 split)

Pure rename ahead of splitting canvas.rs into focused submodules.
No content changes.
---
 frontend/src-tauri/src/commands/{canvas.rs => canvas/mod.rs} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename frontend/src-tauri/src/commands/{canvas.rs => canvas/mod.rs} (100%)

diff --git a/frontend/src-tauri/src/commands/canvas.rs b/frontend/src-tauri/src/commands/canvas/mod.rs
similarity index 100%
rename from frontend/src-tauri/src/commands/canvas.rs
rename to frontend/src-tauri/src/commands/canvas/mod.rs

From 75cd4ebbd0f5f4147e600330a96940977aa07fd7 Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 14:01:28 +0800
Subject: [PATCH 02/30] refactor: extract canvas::shared
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move model-routing helpers (ModelRoute/ModelProviderRoute, resolve_model_route,
effective_model_ids, is_vault_context_prompt, source_tile_context_provider) and
append_canvas_trace into canvas::shared — used by streaming, debate, and session
command handlers alike. Pure move; tests moved verbatim with their code.
---
 frontend/src-tauri/src/commands/canvas/mod.rs | 191 +----------------
 .../src-tauri/src/commands/canvas/shared.rs   | 197 ++++++++++++++++++
 2 files changed, 203 insertions(+), 185 deletions(-)
 create mode 100644 frontend/src-tauri/src/commands/canvas/shared.rs

diff --git a/frontend/src-tauri/src/commands/canvas/mod.rs b/frontend/src-tauri/src/commands/canvas/mod.rs
index a9fa36e..d365069 100644
--- a/frontend/src-tauri/src/commands/canvas/mod.rs
+++ b/frontend/src-tauri/src/commands/canvas/mod.rs
@@ -26,6 +26,12 @@ use std::time::Duration;
 use tauri::State;
 use tokio::sync::RwLock;
 
+mod shared;
+use shared::{
+    append_canvas_trace, effective_model_ids, is_vault_context_prompt, resolve_model_route,
+    source_tile_context_provider, ModelProviderRoute, ModelRoute,
+};
+
 const COMPACT_HISTORY_RECENT_TURNS: usize = 2;
 const COMPACT_HISTORY_EXCERPT_CHARS: usize = 240;
 const EMPTY_MODEL_RESPONSE_ERROR: &str = "No response returned from model";
@@ -77,18 +83,6 @@ struct ResolvedPromptContext {
 
 type StreamedResponseUpdate = (String, String, ResponseStatus, Option<String>);
 
-#[derive(Debug, Clone, PartialEq, Eq)]
-struct ModelRoute {
-    provider: ModelProviderRoute,
-    model_ids: Vec<String>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-enum ModelProviderRoute {
-    OpenRouter,
-    Ollama,
-}
-
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 enum RetrievalDecisionReason {
     NoResults,
@@ -2129,94 +2123,6 @@ fn prompt_request_from_tile(
     }
 }
 
-fn resolve_model_route(
-    prompt_type: &PromptType,
-    context_mode: &ContextMode,
-    twin_provider_override: Option<&str>,
-    settings: &UserSettings,
-) -> Result<ModelRoute, String> {
-    let twin_provider = twin_provider_override
-        .map(|provider| provider.trim().to_ascii_lowercase())
-        .filter(|provider| provider == "ollama" || provider == "openrouter")
-        .unwrap_or_else(|| settings.twin_llm_provider.to_ascii_lowercase());
-
-    if is_vault_context_prompt(prompt_type, context_mode) && twin_provider == "ollama" {
-        let model = settings.ollama_model.trim();
-        if model.is_empty() {
-            return Err(
-                "Select an Ollama model for local vault/twin responses before sending vault context"
-                    .to_string(),
-            );
-        }
-
-        return Ok(ModelRoute {
-            provider: ModelProviderRoute::Ollama,
-            model_ids: vec![model.to_string()],
-        });
-    }
-
-    Ok(ModelRoute {
-        provider: ModelProviderRoute::OpenRouter,
-        model_ids: Vec::new(),
-    })
-}
-
-fn source_tile_context_provider(
-    session: &CanvasSession,
-    source_tile_ids: &[String],
-) -> (bool, Option<String>) {
-    for tile_id in source_tile_ids {
-        if let Some(tile) = session.prompt_tiles.iter().find(|tile| &tile.id == tile_id) {
-            if is_vault_context_prompt(&tile.prompt_type, &tile.context_mode) {
-                return (true, tile.twin_llm_provider.clone());
-            }
-        }
-    }
-
-    (false, None)
-}
-
-fn is_vault_context_prompt(prompt_type: &PromptType, context_mode: &ContextMode) -> bool {
-    prompt_type == &PromptType::Decision
-        || matches!(
-            context_mode,
-            ContextMode::KnowledgeSearch
-                | ContextMode::Semantic
-                | ContextMode::Twin
-                | ContextMode::FullHistory
-                | ContextMode::Compact
-        )
-}
-
-fn effective_model_ids(route: &ModelRoute, requested_model_ids: &[String]) -> Vec<String> {
-    match route.provider {
-        ModelProviderRoute::Ollama => {
-            if requested_model_ids.is_empty() {
-                route.model_ids.clone()
-            } else {
-                requested_model_ids.to_vec()
-            }
-        }
-        ModelProviderRoute::OpenRouter => requested_model_ids.to_vec(),
-    }
-}
-
-async fn append_canvas_trace(
-    twin_store_arc: Arc<RwLock<TwinStore>>,
-    session_id: &str,
-    event_type: TraceEventType,
-    payload: serde_json::Value,
-) {
-    let mut twin_store = twin_store_arc.write().await;
-    if let Err(error) = twin_store.append_trace_event(session_id, event_type, payload) {
-        log::error!(
-            "Failed to append twin trace for session '{}': {}",
-            session_id,
-            error
-        );
-    }
-}
-
 async fn append_model_result_traces(
     twin_store_arc: Arc<RwLock<TwinStore>>,
     session_id: &str,
@@ -4635,91 +4541,6 @@ mod tests {
         assert_eq!(request.twin_llm_provider.as_deref(), Some("ollama"));
     }
 
-    #[test]
-    fn model_route_uses_ollama_for_all_vault_context_when_configured() {
-        let mut settings = crate::models::settings::UserSettings::default();
-        settings.twin_llm_provider = "ollama".to_string();
-        settings.ollama_model = "llama3.1:8b".to_string();
-
-        let decision_route = resolve_model_route(
-            &PromptType::Decision,
-            &ContextMode::KnowledgeSearch,
-            None,
-            &settings,
-        )
-        .unwrap();
-        let twin_route =
-            resolve_model_route(&PromptType::Standard, &ContextMode::Twin, None, &settings)
-                .unwrap();
-        let normal_route =
-            resolve_model_route(&PromptType::Standard, &ContextMode::None, None, &settings)
-                .unwrap();
-
-        assert_eq!(decision_route.provider, ModelProviderRoute::Ollama);
-        assert_eq!(decision_route.model_ids, vec!["llama3.1:8b".to_string()]);
-        assert_eq!(twin_route.provider, ModelProviderRoute::Ollama);
-        assert_eq!(normal_route.provider, ModelProviderRoute::OpenRouter);
-        assert!(normal_route.model_ids.is_empty());
-    }
-
-    #[test]
-    fn effective_model_ids_honors_requested_ollama_models() {
-        let route = ModelRoute {
-            provider: ModelProviderRoute::Ollama,
-            model_ids: vec!["llama3.1:8b".to_string()],
-        };
-
-        let effective = effective_model_ids(&route, &["qwen3:14b".to_string()]);
-
-        assert_eq!(effective, vec!["qwen3:14b".to_string()]);
-    }
-
-    #[test]
-    fn effective_model_ids_falls_back_to_configured_ollama_model() {
-        let route = ModelRoute {
-            provider: ModelProviderRoute::Ollama,
-            model_ids: vec!["llama3.1:8b".to_string()],
-        };
-
-        let effective = effective_model_ids(&route, &[]);
-
-        assert_eq!(effective, vec!["llama3.1:8b".to_string()]);
-    }
-
-    #[test]
-    fn model_route_allows_openrouter_for_vault_context_override() {
-        let mut settings = crate::models::settings::UserSettings::default();
-        settings.twin_llm_provider = "ollama".to_string();
-        settings.ollama_model = "llama3.1:8b".to_string();
-
-        let route = resolve_model_route(
-            &PromptType::Decision,
-            &ContextMode::Twin,
-            Some("openrouter"),
-            &settings,
-        )
-        .unwrap();
-
-        assert_eq!(route.provider, ModelProviderRoute::OpenRouter);
-        assert!(route.model_ids.is_empty());
-    }
-
-    #[test]
-    fn model_route_fails_closed_when_local_twin_model_is_missing() {
-        let mut settings = crate::models::settings::UserSettings::default();
-        settings.twin_llm_provider = "ollama".to_string();
-
-        let error = resolve_model_route(
-            &PromptType::Decision,
-            &ContextMode::KnowledgeSearch,
-            None,
-            &settings,
-        )
-        .unwrap_err();
-
-        assert!(error.contains("Select an Ollama model"));
-    }
-
     #[test]
     fn test_classify_streamed_model_response_rejects_empty_content() {
         let update =
diff --git a/frontend/src-tauri/src/commands/canvas/shared.rs b/frontend/src-tauri/src/commands/canvas/shared.rs
new file mode 100644
index 0000000..da05237
--- /dev/null
+++ b/frontend/src-tauri/src/commands/canvas/shared.rs
@@ -0,0 +1,197 @@
+use crate::models::canvas::{CanvasSession, ContextMode, PromptType};
+use crate::models::settings::UserSettings;
+use crate::models::twin::TraceEventType;
+use crate::services::twin_store::TwinStore;
+use serde_json::json;
+use std::sync::Arc;
+use tokio::sync::RwLock;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(super) struct ModelRoute {
+    pub(super) provider: ModelProviderRoute,
+    pub(super) model_ids: Vec<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(super) enum ModelProviderRoute {
+    OpenRouter,
+    Ollama,
+}
+
+pub(super) fn resolve_model_route(
+    prompt_type: &PromptType,
+    context_mode: &ContextMode,
+    twin_provider_override: Option<&str>,
+    settings: &UserSettings,
+) -> Result<ModelRoute, String> {
+    let twin_provider = twin_provider_override
+        .map(|provider| provider.trim().to_ascii_lowercase())
+        .filter(|provider| provider == "ollama" || provider == "openrouter")
+        .unwrap_or_else(|| settings.twin_llm_provider.to_ascii_lowercase());
+
+    if is_vault_context_prompt(prompt_type, context_mode) && twin_provider == "ollama" {
+        let model = settings.ollama_model.trim();
+        if model.is_empty() {
+            return Err(
+                "Select an Ollama model for local vault/twin responses before sending vault context"
+                    .to_string(),
+            );
+        }
+
+        return Ok(ModelRoute {
+            provider: ModelProviderRoute::Ollama,
+            model_ids: vec![model.to_string()],
+        });
+    }
+
+    Ok(ModelRoute {
+        provider: ModelProviderRoute::OpenRouter,
+        model_ids: Vec::new(),
+    })
+}
+
+pub(super) fn source_tile_context_provider(
+    session: &CanvasSession,
+    source_tile_ids: &[String],
+) -> (bool, Option<String>) {
+    for tile_id in source_tile_ids {
+        if let Some(tile) = session.prompt_tiles.iter().find(|tile| &tile.id == tile_id) {
+            if is_vault_context_prompt(&tile.prompt_type, &tile.context_mode) {
+                return (true, tile.twin_llm_provider.clone());
+            }
+        }
+    }
+
+    (false, None)
+}
+
+pub(super) fn is_vault_context_prompt(prompt_type: &PromptType, context_mode: &ContextMode) -> bool {
+    prompt_type == &PromptType::Decision
+        || matches!(
+            context_mode,
+            ContextMode::KnowledgeSearch
+                | ContextMode::Semantic
+                | ContextMode::Twin
+                | ContextMode::FullHistory
+                | ContextMode::Compact
+        )
+}
+
+pub(super) fn effective_model_ids(route: &ModelRoute, requested_model_ids: &[String]) -> Vec<String> {
+    match route.provider {
+        ModelProviderRoute::Ollama => {
+            if requested_model_ids.is_empty() {
+                route.model_ids.clone()
+            } else {
+                requested_model_ids.to_vec()
+            }
+        }
+        ModelProviderRoute::OpenRouter => requested_model_ids.to_vec(),
+    }
+}
+
+pub(super) async fn append_canvas_trace(
+    twin_store_arc: Arc<RwLock<TwinStore>>,
+    session_id: &str,
+    event_type: TraceEventType,
+    payload: serde_json::Value,
+) {
+    let mut twin_store = twin_store_arc.write().await;
+    if let Err(error) = twin_store.append_trace_event(session_id, event_type, payload) {
+        log::error!(
+            "Failed to append twin trace for session '{}': {}",
+            session_id,
+            error
+        );
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn model_route_uses_ollama_for_all_vault_context_when_configured() {
+        let mut settings = crate::models::settings::UserSettings::default();
+        settings.twin_llm_provider = "ollama".to_string();
+        settings.ollama_model = "llama3.1:8b".to_string();
+
+        let decision_route = resolve_model_route(
+            &PromptType::Decision,
+            &ContextMode::KnowledgeSearch,
+            None,
+            &settings,
+        )
+        .unwrap();
+        let twin_route =
+            resolve_model_route(&PromptType::Standard, &ContextMode::Twin, None, &settings)
+                .unwrap();
+        let normal_route =
+            resolve_model_route(&PromptType::Standard, &ContextMode::None, None, &settings)
+                .unwrap();
+
+        assert_eq!(decision_route.provider, ModelProviderRoute::Ollama);
+        assert_eq!(decision_route.model_ids, vec!["llama3.1:8b".to_string()]);
+        assert_eq!(twin_route.provider, ModelProviderRoute::Ollama);
+        assert_eq!(normal_route.provider, ModelProviderRoute::OpenRouter);
+        assert!(normal_route.model_ids.is_empty());
+    }
+
+    #[test]
+    fn effective_model_ids_honors_requested_ollama_models() {
+        let route = ModelRoute {
+            provider: ModelProviderRoute::Ollama,
+            model_ids: vec!["llama3.1:8b".to_string()],
+        };
+
+        let effective = effective_model_ids(&route, &["qwen3:14b".to_string()]);
+
+        assert_eq!(effective, vec!["qwen3:14b".to_string()]);
+    }
+
+    #[test]
+    fn effective_model_ids_falls_back_to_configured_ollama_model() {
+        let route = ModelRoute {
+            provider: ModelProviderRoute::Ollama,
+            model_ids: vec!["llama3.1:8b".to_string()],
+        };
+
+        let effective = effective_model_ids(&route, &[]);
+
+        assert_eq!(effective, vec!["llama3.1:8b".to_string()]);
+    }
+
+    #[test]
+    fn model_route_allows_openrouter_for_vault_context_override() {
+        let mut settings = crate::models::settings::UserSettings::default();
+        settings.twin_llm_provider = "ollama".to_string();
+        settings.ollama_model = "llama3.1:8b".to_string();
+
+        let route = resolve_model_route(
+            &PromptType::Decision,
+            &ContextMode::Twin,
+            Some("openrouter"),
+            &settings,
+        )
+        .unwrap();
+
+        assert_eq!(route.provider, ModelProviderRoute::OpenRouter);
+        assert!(route.model_ids.is_empty());
+    }
+
+    #[test]
+    fn model_route_fails_closed_when_local_twin_model_is_missing() {
+        let mut settings = crate::models::settings::UserSettings::default();
+        settings.twin_llm_provider = "ollama".to_string();
+
+        let error = resolve_model_route(
+            &PromptType::Decision,
+            &ContextMode::KnowledgeSearch,
+            None,
+            &settings,
+        )
+        .unwrap_err();
+
+        assert!(error.contains("Select an Ollama model"));
+    }
+}

From 8458c89765a14e5b8060be10489fda92b5086cac Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 14:21:59 +0800
Subject: [PATCH 03/30] refactor: extract canvas::context

Move twin/context prompt-building (build_note_context_prompt,
build_chunk_context_prompt, build_twin_context_prompt,
resolve_twin_prompt_context, the twin Simulation identity gate, and the
conversation-history reconstruction helpers) into canvas::context. Pure
move; the twin gate logic and its tests move verbatim.

Shared test builders (build_response/build_tile) used by both context's
and streaming's test suites are factored into a small #[cfg(test)]
canvas::test_support module rather than duplicated.
---
 .../src-tauri/src/commands/canvas/context.rs  | 2279 ++++++++++++++++
 frontend/src-tauri/src/commands/canvas/mod.rs | 2424 +----------------
 .../src-tauri/src/commands/canvas/shared.rs   |   11 +-
 .../src/commands/canvas/test_support.rs       |   61 +
 4 files changed, 2410 insertions(+), 2365 deletions(-)
 create mode 100644 frontend/src-tauri/src/commands/canvas/context.rs
 create mode 100644 frontend/src-tauri/src/commands/canvas/test_support.rs

diff --git a/frontend/src-tauri/src/commands/canvas/context.rs b/frontend/src-tauri/src/commands/canvas/context.rs
new file mode 100644
index 0000000..04b104b
--- /dev/null
+++ b/frontend/src-tauri/src/commands/canvas/context.rs
@@ -0,0 +1,2279 @@
+use super::shared::ModelProviderRoute;
+use crate::commands::run_retrieval;
+use crate::models::canvas::{
+    CanvasSession, ContextMode, DecisionPromptMetadata, PromptRequest, PromptType, TileContextNote,
+    TwinAnswerMode,
+};
+use crate::models::note::ChunkResult;
+use crate::models::twin::{
+    ActionGap, ConstitutionItem, ConstitutionSetup, DecisionEpisode, TwinContextRecord,
+};
+use crate::services::ollama::OllamaService;
+use crate::services::openrouter::{ChatMessage, OpenRouterService};
+use crate::services::retrieval::RetrievalResult;
+use crate::services::twin_store::{parse_twin_prediction, TwinStore};
+use crate::AppState;
+use std::collections::{HashMap, HashSet};
+use std::sync::Arc;
+use tokio::sync::RwLock;
+
+const COMPACT_HISTORY_RECENT_TURNS: usize = 2;
+const COMPACT_HISTORY_EXCERPT_CHARS: usize = 240;
+const MIN_RETRIEVAL_SCORE_FOR_NOTES: f32 = 5.0;
+const MIN_CANVAS_QUERY_TOKEN_LEN: usize = 3;
+const CANVAS_RETRIEVAL_STOPWORDS: &[&str] = &[
+    "a", "an", "and", "are", "as", "at", "be", "but", "by", "can", "do", "for", "from", "how", "i",
+    "if", "in", "into", "is", "it", "its", "like", "make", "more", "my", "not", "of", "on", "or",
+    "our", "real", "so", "that", "the", "their", "them", "there", "these", "they", "this", "to",
+    "up", "use", "want", "was", "we", "what", "when", "where", "which", "who", "why", "with",
+    "works", "would", "you", "your",
+];
+
+// Twin context assembly
+pub(super) const TWIN_CONTEXT_VERSION: &str = "ctx-v2-cases-lexical";
+const TWIN_CONTEXT_TOKEN_BUDGET: usize = 4000;
+const MAX_TWIN_CASE_CONTEXT: usize = 5;
+const TWIN_CASE_FIELD_MAX_CHARS: usize = 800;
+const TWIN_CASE_CORRECTION_MAX_CHARS: usize = 500;
+
+#[derive(Debug, Clone)]
+struct ConversationTurn {
+    prompt: String,
+    response: String,
+    model_id: String,
+}
+
+#[derive(Debug, Clone)]
+pub(super) struct ResolvedPromptContext {
+    pub(super) messages: Vec<ChatMessage>,
+    pub(super) context_notes: Vec<TileContextNote>,
+    pub(super) approved_twin_records: Vec<TwinContextRecord>,
+    pub(super) candidate_twin_records: Vec<TwinContextRecord>,
+    pub(super) constitution_items: Vec<ConstitutionItem>,
+    pub(super) action_gaps: Vec<ActionGap>,
+    pub(super) system_prompt: Option<String>,
+    /// Raw twin system prompt before any user system prompt is merged in;
+    /// reused verbatim by the sealed-prediction call.
+    pub(super) twin_context_prompt: Option<String>,
+    pub(super) context_version: Option<String>,
+    pub(super) decision_case_ids: Vec<String>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum RetrievalDecisionReason {
+    NoResults,
+    WeakTopScore,
+    NoKeywordMatch,
+    NoSnippet,
+    NoLexicalOverlap,
+    UseRetrievedNotes,
+}
+
+fn truncate_note_context_content(content: &str, max_chars: usize) -> String {
+    let mut truncated = String::new();
+    let mut chars = content.chars();
+    for _ in 0..max_chars {
+        match chars.next() {
+            Some(ch) => truncated.push(ch),
+            None => return truncated,
+        }
+    }
+
+    if chars.next().is_some() {
+        truncated.push_str("...");
+    }
+
+    truncated
+}
+
+fn normalize_canvas_query_tokens(text: &str) -> Vec<String> {
+    let normalized: String = text
+        .chars()
+        .map(|ch| {
+            if ch.is_alphanumeric() {
+                ch.to_ascii_lowercase()
+            } else {
+                ' '
+            }
+        })
+        .collect();
+
+    normalized
+        .split_whitespace()
+        .filter(|token| token.len() >= MIN_CANVAS_QUERY_TOKEN_LEN)
+        .filter(|token| !CANVAS_RETRIEVAL_STOPWORDS.contains(token))
+        .map(str::to_string)
+        .collect()
+}
+
+fn matching_canvas_query_tokens(
+    query_tokens: &[String],
+    title: &str,
+    snippet: &str,
+) -> HashSet<String> {
+    let candidate_tokens: HashSet<String> =
+        normalize_canvas_query_tokens(&format!("{} {}", title, snippet))
+            .into_iter()
+            .collect();
+
+    query_tokens
+        .iter()
+        .filter(|token| candidate_tokens.contains(token.as_str()))
+        .cloned()
+        .collect()
+}
+
+fn should_use_retrieved_notes(
+    prompt: &str,
+    retrieval_results: &[RetrievalResult],
+) -> RetrievalDecisionReason {
+    let Some(top_result) = retrieval_results.first() else {
+        return RetrievalDecisionReason::NoResults;
+    };
+
+    if top_result.score < MIN_RETRIEVAL_SCORE_FOR_NOTES {
+        return RetrievalDecisionReason::WeakTopScore;
+    }
+
+    if !top_result
+        .relevance_reasons
+        .iter()
+        .any(|reason| reason == "keyword match")
+    {
+        return RetrievalDecisionReason::NoKeywordMatch;
+    }
+
+    let query_tokens = normalize_canvas_query_tokens(prompt);
+
+    let mut saw_snippet = false;
+    for result in retrieval_results {
+        if result.snippet.trim().is_empty() {
+            continue;
+        }
+
+        saw_snippet = true;
+        let matched_tokens =
+            matching_canvas_query_tokens(&query_tokens, &result.note.title, &result.snippet);
+        let has_long_match = matched_tokens.iter().any(|token| token.len() >= 6);
+
+        if matched_tokens.len() >= 2 || (has_long_match && !matched_tokens.is_empty()) {
+            return RetrievalDecisionReason::UseRetrievedNotes;
+        }
+    }
+
+    if !saw_snippet {
+        RetrievalDecisionReason::NoSnippet
+    } else {
+        RetrievalDecisionReason::NoLexicalOverlap
+    }
+}
+
+pub(super) async fn resolve_prompt_context(
+    state: &AppState,
+    session: &CanvasSession,
+    request: &PromptRequest,
+) -> Result<ResolvedPromptContext, String> {
+    let messages = build_canvas_messages(session, request)?;
+
+    if request.context_mode == ContextMode::Twin {
+        return resolve_twin_prompt_context(state, messages, session, request).await;
+    }
+
+    if matches!(
+        request.context_mode,
+        ContextMode::KnowledgeSearch | ContextMode::Semantic
+    ) {
+        let pinned_ids = session.pinned_note_ids.clone();
+
+        // Quality gate: note-level retrieval to check if vault has relevant content
+        let retrieval_results = run_retrieval(state, &request.prompt, 5, &pinned_ids)
+            .await
+            .unwrap_or_default();
+
+        let retrieval_decision = should_use_retrieved_notes(&request.prompt, &retrieval_results);
+        if retrieval_decision != RetrievalDecisionReason::UseRetrievedNotes {
+            log::info!(
+                "Canvas knowledge search fallback for prompt {:?}: {:?}",
+                request.prompt,
+                retrieval_decision
+            );
+            return Ok(ResolvedPromptContext {
+                messages,
+                context_notes: Vec::new(),
+                approved_twin_records: Vec::new(),
+                candidate_twin_records: Vec::new(),
+                constitution_items: Vec::new(),
+                action_gaps: Vec::new(),
+                system_prompt: request.system_prompt.clone(),
+                twin_context_prompt: None,
+                context_version: None,
+                decision_case_ids: Vec::new(),
+            });
+        }
+
+        // Check if chunk-level retrieval is enabled
+        let chunk_enabled = {
+            let retrieval = state.retrieval_service.read().await;
+            retrieval.get_config().chunk_retrieval_enabled
+        };
+
+        if chunk_enabled {
+            // Chunk-level context: retrieve relevant paragraphs within token budget
+            let chunks = {
+                let retrieval = state.retrieval_service.read().await;
+                let chunk_index = state.chunk_index.read().await;
+                let graph = state.graph_index.read().await;
+                let priority = state.priority_service.read().await;
+                let token_budget = retrieval.get_config().default_token_budget;
+                retrieval
+                    .retrieve_chunks(
+                        &chunk_index,
+                        &graph,
+                        &priority,
+                        &request.prompt,
+                        token_budget,
+                        &pinned_ids,
+                    )
+                    .unwrap_or_default()
+            };
+
+            if chunks.is_empty() {
+                log::info!("Chunk retrieval returned no results, falling back to note-level");
+                return resolve_note_level_context(
+                    state,
+                    messages,
+                    &retrieval_results,
+                    &pinned_ids,
+                    &request.system_prompt,
+                )
+                .await;
+            }
+
+            let total_tokens: usize = chunks.iter().map(|c| c.token_estimate).sum();
+            let parent_count = chunks
+                .iter()
+                .map(|c| &c.parent_note_id)
+                .collect::<HashSet<_>>()
+                .len();
+            log::info!(
+                "Canvas using chunk retrieval: {} chunks from {} notes (~{} tokens)",
+                chunks.len(),
+                parent_count,
+                total_tokens
+            );
+
+            // Build context notes from chunk parent notes (deduped)
+            let mut seen_notes: HashSet<String> = HashSet::new();
+            let context_notes: Vec<TileContextNote> = chunks
+                .iter()
+                .filter_map(|c| {
+                    if seen_notes.insert(c.parent_note_id.clone()) {
+                        Some(TileContextNote {
+                            id: c.parent_note_id.clone(),
+                            title: c.parent_title.clone(),
+                            snippet: truncate_note_context_content(&c.text, 200),
+                            score: c.search_score,
+                            pinned: pinned_ids.contains(&c.parent_note_id),
+                        })
+                    } else {
+                        None
+                    }
+                })
+                .collect();
+
+            let note_prompt = build_chunk_context_prompt(&chunks);
+            let system_prompt = match &request.system_prompt {
+                Some(user_sp) if !user_sp.is_empty() => format!("{}\n\n{}", note_prompt, user_sp),
+                _ => note_prompt,
+            };
+
+            Ok(ResolvedPromptContext {
+                messages,
+                context_notes,
+                approved_twin_records: Vec::new(),
+                candidate_twin_records: Vec::new(),
+                constitution_items: Vec::new(),
+                action_gaps: Vec::new(),
+                system_prompt: Some(system_prompt),
+                twin_context_prompt: None,
+                context_version: None,
+                decision_case_ids: Vec::new(),
+            })
+        } else {
+            log::info!("Canvas using note-level context (chunk retrieval disabled)");
+            resolve_note_level_context(
+                state,
+                messages,
+                &retrieval_results,
+                &pinned_ids,
+                &request.system_prompt,
+            )
+            .await
+        }
+    } else {
+        Ok(ResolvedPromptContext {
+            messages,
+            context_notes: Vec::new(),
+            approved_twin_records: Vec::new(),
+            candidate_twin_records: Vec::new(),
+            constitution_items: Vec::new(),
+            action_gaps: Vec::new(),
+            system_prompt: request.system_prompt.clone(),
+            twin_context_prompt: None,
+            context_version: None,
+            decision_case_ids: Vec::new(),
+        })
+    }
+}
+
+async fn resolve_twin_prompt_context(
+    state: &AppState,
+    messages: Vec<ChatMessage>,
+    session: &CanvasSession,
+    request: &PromptRequest,
+) -> Result<ResolvedPromptContext, String> {
+    let pinned_ids = session.pinned_note_ids.clone();
+    let retrieval_results = run_retrieval(state, &request.prompt, 5, &pinned_ids)
+        .await
+        .unwrap_or_default();
+
+    let should_use_notes = should_use_retrieved_notes(&request.prompt, &retrieval_results)
+        == RetrievalDecisionReason::UseRetrievedNotes;
+    let mut context_notes = Vec::new();
+    let mut note_contexts = Vec::new();
+
+    if should_use_notes {
+        let chunk_enabled = {
+            let retrieval = state.retrieval_service.read().await;
+            retrieval.get_config().chunk_retrieval_enabled
+        };
+
+        if chunk_enabled {
+            let chunks = {
+                let retrieval = state.retrieval_service.read().await;
+                let chunk_index = state.chunk_index.read().await;
+                let graph = state.graph_index.read().await;
+                let priority = state.priority_service.read().await;
+                let token_budget = retrieval.get_config().default_token_budget;
+                retrieval
+                    .retrieve_chunks(
+                        &chunk_index,
+                        &graph,
+                        &priority,
+                        &request.prompt,
+                        token_budget,
+                        &pinned_ids,
+                    )
+                    .unwrap_or_default()
+            };
+
+            if !chunks.is_empty() {
+                let mut seen_notes: HashSet<String> = HashSet::new();
+                for chunk in &chunks {
+                    note_contexts.push((
+                        chunk.parent_note_id.clone(),
+                        chunk.parent_title.clone(),
+                        chunk.text.clone(),
+                    ));
+                    if seen_notes.insert(chunk.parent_note_id.clone()) {
+                        context_notes.push(TileContextNote {
+                            id: chunk.parent_note_id.clone(),
+                            title: chunk.parent_title.clone(),
+                            snippet: truncate_note_context_content(&chunk.text, 200),
+                            score: chunk.search_score,
+                            pinned: pinned_ids.contains(&chunk.parent_note_id),
+                        });
+                    }
+                }
+            }
+        }
+
+        if note_contexts.is_empty() {
+            note_contexts = fetch_note_contexts(state, &retrieval_results).await;
+            let found_ids: HashSet<&str> =
+                note_contexts.iter().map(|(id, _, _)| id.as_str()).collect();
+            for r in &retrieval_results {
+                if found_ids.contains(r.note.id.as_str()) {
+                    context_notes.push(TileContextNote {
+                        id: r.note.id.clone(),
+                        title: r.note.title.clone(),
+                        snippet: r.snippet.clone(),
+                        score: r.score,
+                        pinned: pinned_ids.contains(&r.note.id),
+                    });
+                }
+            }
+        }
+    }
+
+    let constitution_query =
+        decision_context_query(&request.prompt, request.decision_metadata.as_ref());
+    let (
+        setup,
+        approved_twin_records,
+        candidate_twin_records,
+        constitution_items,
+        action_gaps,
+        decision_cases,
+    ) = {
+        let mut twin_store = state.twin_store.write().await;
+        let setup = twin_store
+            .get_constitution_setup()
+            .map_err(|error| error.to_string())?;
+        validate_twin_identity_for_answer_mode(&setup, &request.twin_answer_mode)?;
+        let (approved, candidate) = twin_store
+            .select_context_records(&request.prompt)
+            .map_err(|error| error.to_string())?;
+        let (constitution_items, action_gaps) = twin_store
+            .select_constitution_context(&constitution_query)
+            .map_err(|error| error.to_string())?;
+        let decision_cases = twin_store
+            .select_decision_cases(&constitution_query, None, MAX_TWIN_CASE_CONTEXT)
+            .map_err(|error| error.to_string())?;
+        (
+            setup,
+            approved,
+            candidate,
+            constitution_items,
+            action_gaps,
+            decision_cases,
+        )
+    };
+
+    let selection = apply_twin_context_budget(
+        decision_cases,
+        constitution_items,
+        approved_twin_records,
+        candidate_twin_records,
+        action_gaps,
+        note_contexts,
+        TWIN_CONTEXT_TOKEN_BUDGET,
+    );
+    let decision_case_ids = selection
+        .cases
+        .iter()
+        .map(|episode| episode.id.clone())
+        .collect::<Vec<_>>();
+
+    let twin_prompt = build_twin_context_prompt(
+        &setup,
+        &selection.cases,
+        &selection.notes,
+        &selection.approved,
+        &selection.candidates,
+        &selection.constitution_items,
+        &selection.action_gaps,
+        &request.twin_answer_mode,
+        &request.prompt_type,
+        request.decision_metadata.as_ref(),
+    );
+    let system_prompt = match &request.system_prompt {
+        Some(user_sp) if !user_sp.is_empty() => format!("{}\n\n{}", twin_prompt, user_sp),
+        _ => twin_prompt.clone(),
+    };
+
+    Ok(ResolvedPromptContext {
+        messages,
+        context_notes,
+        approved_twin_records: selection.approved,
+        candidate_twin_records: selection.candidates,
+        constitution_items: selection.constitution_items,
+        action_gaps: selection.action_gaps,
+        system_prompt: Some(system_prompt),
+        twin_context_prompt: Some(twin_prompt),
+        context_version: Some(TWIN_CONTEXT_VERSION.to_string()),
+        decision_case_ids,
+    })
+}
+
+/// Fetch full note content for retrieval results, returning (id, title, truncated_content) tuples.
+/// Skips notes that can't be read from the store. Called by both the semantic and twin note-level paths.
+async fn fetch_note_contexts(
+    state: &AppState,
+    results: &[RetrievalResult],
+) -> Vec<(String, String, String)> {
+    let store = state.knowledge_store.read().await;
+    results
+        .iter()
+        .filter_map(|r| {
+            store.get_note(&r.note.id).ok().map(|note| {
+                let truncated = truncate_note_context_content(&note.content, 1500);
+                (note.id.clone(), note.title.clone(), truncated)
+            })
+        })
+        .collect()
+}
+
+/// Fall back to note-level context when chunk retrieval is disabled or returns nothing.
+async fn resolve_note_level_context(
+    state: &AppState,
+    messages: Vec<ChatMessage>,
+    retrieval_results: &[RetrievalResult],
+    pinned_ids: &[String],
+    user_system_prompt: &Option<String>,
+) -> Result<ResolvedPromptContext, String> {
+    let note_contexts = fetch_note_contexts(state, retrieval_results).await;
+
+    let context_notes: Vec<TileContextNote> = retrieval_results
+        .iter()
+        .map(|r| TileContextNote {
+            id: r.note.id.clone(),
+            title: r.note.title.clone(),
+            snippet: r.snippet.clone(),
+            score: r.score,
+            pinned: pinned_ids.contains(&r.note.id),
+        })
+        .collect();
+
+    let note_prompt = build_note_context_prompt(&note_contexts);
+    let system_prompt = match user_system_prompt {
+        Some(user_sp) if !user_sp.is_empty() => format!("{}\n\n{}", note_prompt, user_sp),
+        _ => note_prompt,
+    };
+
+    Ok(ResolvedPromptContext {
+        messages,
+        context_notes,
+        approved_twin_records: Vec::new(),
+        candidate_twin_records: Vec::new(),
+        constitution_items: Vec::new(),
+        action_gaps: Vec::new(),
+        system_prompt: Some(system_prompt),
+        twin_context_prompt: None,
+        context_version: None,
+        decision_case_ids: Vec::new(),
+    })
+}
+
+fn build_canvas_messages(
+    session: &CanvasSession,
+    request: &PromptRequest,
+) -> Result<Vec<ChatMessage>, String> {
+    match request.context_mode {
+        ContextMode::FullHistory => build_full_history_messages(session, request),
+        ContextMode::Compact => build_compact_history_messages(session, request),
+        _ => Ok(vec![ChatMessage {
+            role: "user".to_string(),
+            content: request.prompt.clone(),
+        }]),
+    }
+}
+
+fn build_full_history_messages(
+    session: &CanvasSession,
+    request: &PromptRequest,
+) -> Result<Vec<ChatMessage>, String> {
+    let turns = build_selected_parent_chain(session, request)?;
+    let mut messages = Vec::with_capacity((turns.len() * 2) + 1);
+
+    for turn in turns {
+        messages.push(ChatMessage {
+            role: "user".to_string(),
+            content: turn.prompt,
+        });
+        messages.push(ChatMessage {
+            role: "assistant".to_string(),
+            content: turn.response,
+        });
+    }
+
+    messages.push(ChatMessage {
+        role: "user".to_string(),
+        content: request.prompt.clone(),
+    });
+
+    Ok(messages)
+}
+
+fn build_compact_history_messages(
+    session: &CanvasSession,
+    request: &PromptRequest,
+) -> Result<Vec<ChatMessage>, String> {
+    let turns = build_selected_parent_chain(session, request)?;
+    let mut messages = Vec::new();
+
+    if turns.len() > COMPACT_HISTORY_RECENT_TURNS {
+        let split_at = turns.len() - COMPACT_HISTORY_RECENT_TURNS;
+        let summary = build_compact_history_summary(&turns[..split_at]);
+        messages.push(ChatMessage {
+            role: "user".to_string(),
+            content: summary,
+        });
+
+        for turn in &turns[split_at..] {
+            messages.push(ChatMessage {
+                role: "user".to_string(),
+                content: turn.prompt.clone(),
+            });
+            messages.push(ChatMessage {
+                role: "assistant".to_string(),
+                content: turn.response.clone(),
+            });
+        }
+    } else {
+        for turn in turns {
+            messages.push(ChatMessage {
+                role: "user".to_string(),
+                content: turn.prompt,
+            });
+            messages.push(ChatMessage {
+                role: "assistant".to_string(),
+                content: turn.response,
+            });
+        }
+    }
+
+    messages.push(ChatMessage {
+        role: "user".to_string(),
+        content: request.prompt.clone(),
+    });
+
+    Ok(messages)
+}
+
+fn build_selected_parent_chain(
+    session: &CanvasSession,
+    request: &PromptRequest,
+) -> Result<Vec<ConversationTurn>, String> {
+    let mut tile_id = request
+        .parent_tile_id
+        .clone()
+        .ok_or_else(|| "Context mode requires a parent tile".to_string())?;
+    let mut model_id = request
+        .parent_model_id
+        .clone()
+        .ok_or_else(|| "Context mode requires a parent model".to_string())?;
+    let mut visited = HashSet::new();
+    let mut turns = Vec::new();
+
+    loop {
+        let visit_key = format!("{}::{}", tile_id, model_id);
+        if !visited.insert(visit_key) {
+            return Err("Detected a cycle while reconstructing canvas history".to_string());
+        }
+
+        let tile = session
+            .prompt_tiles
+            .iter()
+            .find(|t| t.id == tile_id)
+            .ok_or_else(|| format!("Parent tile not found in session: {}", tile_id))?;
+        let response = tile.responses.get(&model_id).ok_or_else(|| {
+            format!(
+                "Parent response not found for tile {} and model {}",
+                tile_id, model_id
+            )
+        })?;
+
+        turns.push(ConversationTurn {
+            prompt: tile.prompt.clone(),
+            response: response.content.clone(),
+            model_id: model_id.clone(),
+        });
+
+        match (&tile.parent_tile_id, &tile.parent_model_id) {
+            (Some(next_tile_id), Some(next_model_id)) => {
+                tile_id = next_tile_id.clone();
+                model_id = next_model_id.clone();
+            }
+            (None, None) => break,
+            _ => {
+                return Err(format!(
+                    "Incomplete parent linkage for tile {} while reconstructing history",
+                    tile.id
+                ))
+            }
+        }
+    }
+
+    turns.reverse();
+    Ok(turns)
+}
+
+fn build_compact_history_summary(turns: &[ConversationTurn]) -> String {
+    let mut summary = String::from("Conversation summary before the most recent turns:\n");
+
+    for (index, turn) in turns.iter().enumerate() {
+        summary.push_str(&format!(
+            "\nTurn {}:\nUser: {}\nAssistant ({}): {}\n",
+            index + 1,
+            truncate_for_compact_history(&turn.prompt),
+            turn.model_id,
+            truncate_for_compact_history(&turn.response),
+        ));
+    }
+
+    summary
+}
+
+fn truncate_for_compact_history(content: &str) -> String {
+    if content.chars().count() <= COMPACT_HISTORY_EXCERPT_CHARS {
+        return content.to_string();
+    }
+
+    let mut truncated = content
+        .chars()
+        .take(COMPACT_HISTORY_EXCERPT_CHARS)
+        .collect::<String>();
+    truncated.push_str("...");
+    truncated
+}
+
+/// Build a system prompt that includes retrieved note context.
+/// Used by send_prompt when context_mode is Semantic.
+fn build_chunk_context_prompt(chunks: &[ChunkResult]) -> String {
+    let mut prompt = String::from(
+        "You are a helpful knowledge assistant for the user's personal note-taking system (Grafyn). \
+         Answer questions using the context from the user's notes below. \
+         Reference specific notes by title when citing information. \
+         If the notes don't contain relevant information, say so honestly.\n\n",
+    );
+
+    if chunks.is_empty() {
+        prompt.push_str("No relevant notes were found for this query.\n");
+        return prompt;
+    }
+
+    // Group chunks by parent note, preserving insertion order
+    let mut note_order: Vec<String> = Vec::new();
+    let mut note_map: HashMap<String, (String, Vec<&str>)> = HashMap::new();
+
+    for chunk in chunks {
+        let entry = note_map
+            .entry(chunk.parent_note_id.clone())
+            .or_insert_with(|| {
+                note_order.push(chunk.parent_note_id.clone());
+                (chunk.parent_title.clone(), Vec::new())
+            });
+        entry.1.push(&chunk.text);
+    }
+
+    prompt.push_str("## Relevant Notes\n\n");
+    for note_id in &note_order {
+        if let Some((title, texts)) = note_map.get(note_id) {
+            prompt.push_str(&format!("### {} (id: {})\n", title, note_id));
+            for text in texts {
+                prompt.push_str(text);
+                prompt.push_str("\n\n");
+            }
+        }
+    }
+
+    prompt
+}
+
+fn build_note_context_prompt(notes: &[(String, String, String)]) -> String {
+    let mut prompt = String::from(
+        "You are a helpful knowledge assistant for the user's personal note-taking system (Grafyn). \
+         Answer questions using the context from the user's notes below. \
+         Reference specific notes by title when citing information. \
+         If the notes don't contain relevant information, say so honestly.\n\n",
+    );
+
+    if notes.is_empty() {
+        prompt.push_str("No relevant notes were found for this query.\n");
+    } else {
+        prompt.push_str("## Relevant Notes\n\n");
+        for (id, title, content) in notes {
+            prompt.push_str(&format!("### {} (id: {})\n{}\n\n", title, id, content));
+        }
+    }
+
+    prompt
+}
+
+/// Rough token estimate matching the chunk-index convention (words * 4/3).
+fn estimate_tokens(text: &str) -> usize {
+    text.split_whitespace().count() * 4 / 3 + 1
+}
+
+/// Render one past decision episode as a verbatim behavioral case.
+fn format_decision_case(episode: &DecisionEpisode) -> String {
+    let mut case = format!("### Past decision: {}\n", episode.decision.trim());
+    if !episode.options.is_empty() {
+        case.push_str(&format!("- Options: {}\n", episode.options.join(" | ")));
+    }
+    if let Some(chosen) = episode.chosen_option.as_deref() {
+        case.push_str(&format!("- Chose: {}\n", chosen.trim()));
+    }
+    if let Some(leaning) = episode.initial_leaning.as_deref() {
+        if !leaning.trim().is_empty() {
+            case.push_str(&format!("- Initial leaning: {}\n", leaning.trim()));
+        }
+    }
+    if let Some(outcome) = episode.outcome.as_deref() {
+        if !outcome.trim().is_empty() {
+            case.push_str(&format!(
+                "- Outcome: {}\n",
+                truncate_note_context_content(outcome.trim(), TWIN_CASE_FIELD_MAX_CHARS)
+            ));
+        }
+    }
+    if let Some(lesson) = episode.lesson.as_deref() {
+        if !lesson.trim().is_empty() {
+            case.push_str(&format!(
+                "- Lesson (verbatim): {}\n",
+                truncate_note_context_content(lesson.trim(), TWIN_CASE_FIELD_MAX_CHARS)
+            ));
+        }
+    }
+    if let Some(note) = episode.correction_note.as_deref() {
+        if !note.trim().is_empty() {
+            case.push_str(&format!(
+                "- Correction note (recorded when an earlier sealed twin guess missed): {}\n",
+                truncate_note_context_content(note.trim(), TWIN_CASE_CORRECTION_MAX_CHARS)
+            ));
+        }
+    }
+    case.push('\n');
+    case
+}
+
+struct TwinContextSelection {
+    cases: Vec<DecisionEpisode>,
+    constitution_items: Vec<ConstitutionItem>,
+    approved: Vec<TwinContextRecord>,
+    candidates: Vec<TwinContextRecord>,
+    action_gaps: Vec<ActionGap>,
+    notes: Vec<(String, String, String)>,
+}
+
+/// Greedy-fill the variable twin context sections into a hard token budget,
+/// in priority order: cases > constitution > approved records > candidate
+/// records > action gaps > evidence notes. Fixed scaffolding (operating
+/// contract, identity, answer instructions, decision metadata) sits outside
+/// the budget.
+#[allow(clippy::too_many_arguments)]
+fn apply_twin_context_budget(
+    cases: Vec<DecisionEpisode>,
+    constitution_items: Vec<ConstitutionItem>,
+    approved: Vec<TwinContextRecord>,
+    candidates: Vec<TwinContextRecord>,
+    action_gaps: Vec<ActionGap>,
+    notes: Vec<(String, String, String)>,
+    budget: usize,
+) -> TwinContextSelection {
+    let mut remaining = budget as isize;
+    let mut take_within_budget = move |cost: usize| -> bool {
+        if remaining - cost as isize >= 0 {
+            remaining -= cost as isize;
+            true
+        } else {
+            false
+        }
+    };
+
+    let cases = cases
+        .into_iter()
+        .filter(|episode| take_within_budget(estimate_tokens(&format_decision_case(episode))))
+        .collect();
+    let constitution_items = constitution_items
+        .into_iter()
+        .filter(|item| take_within_budget(estimate_tokens(&format_constitution_item(item))))
+        .collect();
+    let approved = approved
+        .into_iter()
+        .filter(|record| take_within_budget(estimate_tokens(&format_twin_record(record))))
+        .collect();
+    let candidates = candidates
+        .into_iter()
+        .filter(|record| take_within_budget(estimate_tokens(&format_twin_record(record))))
+        .collect();
+    let action_gaps = action_gaps
+        .into_iter()
+        .filter(|gap| take_within_budget(estimate_tokens(&format_action_gap(gap))))
+        .collect();
+    let notes = notes
+        .into_iter()
+        .filter(|(_, title, content)| {
+            take_within_budget(estimate_tokens(title) + estimate_tokens(content))
+        })
+        .collect();
+
+    TwinContextSelection {
+        cases,
+        constitution_items,
+        approved,
+        candidates,
+        action_gaps,
+        notes,
+    }
+}
+
+/// User message for the hidden sealed-prediction call. With a configured
+/// Twin Identity the framing is immersed first person; the fallback is a
+/// neutral decision-support instruction. Disclosure language lives in the
+/// app UI, never in model-facing prompts.
+fn build_twin_prediction_user_message(
+    setup: &ConstitutionSetup,
+    decision: &str,
+    options: &[String],
+    stakes: Option<&str>,
+) -> String {
+    let immersed = has_twin_identity(setup);
+    let mut message = String::new();
+    if immersed {
+        let name = setup
+            .twin_name
+            .as_deref()
+            .unwrap_or_default()
+            .trim()
+            .to_string();
+        message.push_str(&format!(
+            "I am {}. The decision in front of me: {}\n",
+            name,
+            decision.trim()
+        ));
+    } else {
+        message.push_str(&format!(
+            "Decision under consideration: {}\n",
+            decision.trim()
+        ));
+    }
+    if let Some(stakes) = stakes {
+        if !stakes.trim().is_empty() {
+            message.push_str(&format!("Stakes: {}\n", stakes.trim()));
+        }
+    }
+    message.push_str("My options:\n");
+    for (index, option) in options.iter().enumerate() {
+        message.push_str(&format!("{}. {}\n", index + 1, option));
+    }
+    if immersed {
+        message.push_str(
+            "\nWhich option do I choose? I answer with only this JSON object and nothing else:\n",
+        );
+    } else {
+        message.push_str(
+            "\nGiven the context above, determine which option best fits this decision-maker's \
+             documented values, constitution, and past decisions. Respond with only this JSON \
+             object and nothing else:\n",
+        );
+    }
+    message.push_str(
+        "{\"predicted_option\": \"<option text>\", \"option_index\": <option number from the list above>, \
+         \"confidence\": <0.0 to 1.0>, \"rationale\": \"<one or two sentences>\"}",
+    );
+    message
+}
+
+/// The hidden sealed-prediction call. Runs in its own spawned task, never
+/// touches the window, and never blocks the visible streaming flow. Lock
+/// discipline: collect owned data under the store lock, drop it, await the
+/// provider, then re-lock to attach.
+#[allow(clippy::too_many_arguments)]
+pub(super) async fn run_sealed_twin_prediction(
+    twin_store: Arc<RwLock<TwinStore>>,
+    openrouter: Arc<RwLock<OpenRouterService>>,
+    ollama: Arc<RwLock<OllamaService>>,
+    provider_route: ModelProviderRoute,
+    prediction_model: String,
+    episode_id: String,
+    prompt: String,
+    decision: String,
+    options: Vec<String>,
+    stakes: Option<String>,
+    twin_context_prompt: Option<String>,
+    context_version: String,
+    decision_metadata: Option<DecisionPromptMetadata>,
+) {
+    let built = {
+        let mut store = twin_store.write().await;
+        let setup = match store.get_constitution_setup() {
+            Ok(setup) => setup,
+            Err(error) => {
+                log::warn!("Sealed prediction setup load failed for {episode_id}: {error}");
+                let _ = store.mark_twin_prediction_failed(&episode_id);
+                return;
+            }
+        };
+
+        let system_prompt = if let Some(prompt) = twin_context_prompt {
+            prompt
+        } else {
+            // Non-Twin-context decision tile: build a twin-only context on
+            // the spot so predictions cover every decision, not just
+            // Twin-mode ones (skipping them would bias the eval sample).
+            let query = decision_context_query(&prompt, decision_metadata.as_ref());
+            let selections =
+                store
+                    .select_context_records(&prompt)
+                    .and_then(|(approved, candidates)| {
+                        let (constitution_items, action_gaps) =
+                            store.select_constitution_context(&query)?;
+                        let cases = store.select_decision_cases(
+                            &query,
+                            Some(&episode_id),
+                            MAX_TWIN_CASE_CONTEXT,
+                        )?;
+                        Ok((approved, candidates, constitution_items, action_gaps, cases))
+                    });
+            match selections {
+                Ok((approved, candidates, constitution_items, action_gaps, cases)) => {
+                    let selection = apply_twin_context_budget(
+                        cases,
+                        constitution_items,
+                        approved,
+                        candidates,
+                        action_gaps,
+                        Vec::new(),
+                        TWIN_CONTEXT_TOKEN_BUDGET,
+                    );
+                    let answer_mode = if has_twin_identity(&setup) {
+                        TwinAnswerMode::Simulation
+                    } else {
+                        TwinAnswerMode::Advisor
+                    };
+                    build_twin_context_prompt(
+                        &setup,
+                        &selection.cases,
+                        &selection.notes,
+                        &selection.approved,
+                        &selection.candidates,
+                        &selection.constitution_items,
+                        &selection.action_gaps,
+                        &answer_mode,
+                        &PromptType::Decision,
+                        decision_metadata.as_ref(),
+                    )
+                }
+                Err(error) => {
+                    log::warn!("Sealed prediction context build failed for {episode_id}: {error}");
+                    let _ = store.mark_twin_prediction_failed(&episode_id);
+                    return;
+                }
+            }
+        };
+
+        let user_message =
+            build_twin_prediction_user_message(&setup, &decision, &options, stakes.as_deref());
+        (system_prompt, user_message)
+    };
+    let (system_prompt, user_message) = built;
+
+    let messages = vec![ChatMessage {
+        role: "user".to_string(),
+        content: user_message,
+    }];
+    let result = match provider_route {
+        ModelProviderRoute::Ollama => {
+            let ollama = ollama.read().await;
+            ollama
+                .chat(&prediction_model, messages, Some(&system_prompt), Some(0.2))
+                .await
+        }
+        ModelProviderRoute::OpenRouter => {
+            let openrouter = openrouter.read().await;
+            openrouter
+                .chat(
+                    &prediction_model,
+                    messages,
+                    Some(&system_prompt),
+                    Some(0.2),
+                    Some(600),
+                    Some("none"),
+                    false,
+                    0,
+                )
+                .await
+        }
+    };
+
+    match result {
+        Ok(raw) => {
+            let draft = parse_twin_prediction(&raw, &options);
+            let mut store = twin_store.write().await;
+            if let Err(error) = store.attach_twin_prediction(
+                &episode_id,
+                draft,
+                &prediction_model,
+                &context_version,
+            ) {
+                log::warn!("Failed to seal twin prediction for {episode_id}: {error}");
+            }
+        }
+        Err(error) => {
+            log::warn!("Sealed twin prediction call failed for {episode_id}: {error}");
+            let mut store = twin_store.write().await;
+            let _ = store.mark_twin_prediction_failed(&episode_id);
+        }
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+fn build_twin_context_prompt(
+    setup: &ConstitutionSetup,
+    decision_cases: &[DecisionEpisode],
+    notes: &[(String, String, String)],
+    approved_records: &[TwinContextRecord],
+    candidate_records: &[TwinContextRecord],
+    constitution_items: &[ConstitutionItem],
+    action_gaps: &[ActionGap],
+    answer_mode: &TwinAnswerMode,
+    prompt_type: &PromptType,
+    decision_metadata: Option<&DecisionPromptMetadata>,
+) -> String {
+    let mut prompt = String::from(
+        "## Twin Operating Contract\n\n\
+         You are Grafyn's native RAG twin mode. Use only the provided Constitution, action gaps, vault evidence, and user-reviewed twin records as context. \
+         Keep uncertainty visible. Do not use evidence to justify a preselected answer; use evidence to constrain the answer before choosing. \
+         Use interviewee answers as evidence about the interviewee, institution, product, or research context. \
+         Use interviewer questions and follow-ups as evidence about the user's reasoning pattern. \
+         Keep these roles separate.\n\n",
+    );
+
+    prompt.push_str(&format_twin_identity_section(setup, answer_mode));
+
+    prompt.push_str("## Past Decision Cases\n\n");
+    if decision_cases.is_empty() {
+        prompt.push_str("No similar past decisions were selected for this prompt.\n\n");
+    } else {
+        prompt.push_str(
+            "These are this person's actual past decisions, verbatim. \
+             Weight them above abstracted records: they show how tradeoffs were really made.\n",
+        );
+        for episode in decision_cases {
+            prompt.push_str(&format_decision_case(episode));
+        }
+    }
+
+    let reviewed_constitution = constitution_items
+        .iter()
+        .filter(|item| {
+            matches!(
+                item.status,
+                crate::models::twin::ConstitutionStatus::Active
+                    | crate::models::twin::ConstitutionStatus::Softened
+            )
+        })
+        .collect::<Vec<_>>();
+    let candidate_constitution = constitution_items
+        .iter()
+        .filter(|item| item.status == crate::models::twin::ConstitutionStatus::Candidate)
+        .collect::<Vec<_>>();
+
+    prompt.push_str("## Reviewed Constitution\n\n");
+    if reviewed_constitution.is_empty() {
+        prompt.push_str("No reviewed Constitution items were selected for this prompt.\n\n");
+    } else {
+        prompt.push_str("These are the governing principles for the answer. Apply them before weighing evidence.\n");
+        for item in reviewed_constitution {
+            prompt.push_str(&format_constitution_item(item));
+        }
+        prompt.push('\n');
+    }
+
+    prompt.push_str("## Action Gap Risks\n\n");
+    if action_gaps.is_empty() {
+        prompt
+            .push_str("No relevant stated-intention vs revealed-behavior gaps were selected.\n\n");
+    } else {
+        prompt.push_str("Use these as risk checks, not accusations. Ask whether the same gap could affect this answer.\n");
+        for gap in action_gaps {
+            prompt.push_str(&format_action_gap(gap));
+        }
+        prompt.push('\n');
+    }
+
+    prompt.push_str("## Relevant Evidence\n\n");
+    if notes.is_empty() {
+        prompt.push_str(
+            "No relevant vault notes or graph evidence were selected for this prompt.\n\n",
+        );
+    } else {
+        for (id, title, content) in notes {
+            prompt.push_str(&format!("### {} (id: {})\n{}\n\n", title, id, content));
+        }
+    }
+
+    prompt.push_str("## Approved User Records\n\n");
+    if approved_records.is_empty() {
+        prompt.push_str("No endorsed or auto-promoted user records were selected.\n\n");
+    } else {
+        for record in approved_records {
+            prompt.push_str(&format_twin_record(record));
+        }
+        prompt.push('\n');
+    }
+
+    prompt.push_str("## Tentative Candidate Records\n\n");
+    if candidate_records.is_empty() {
+        prompt.push_str("No relevant candidate records were selected.\n\n");
+    } else {
+        prompt.push_str("These are unreviewed hypotheses. Use them lightly and disclose when they affect the answer.\n");
+        for record in candidate_records {
+            prompt.push_str(&format_twin_record(record));
+        }
+        prompt.push('\n');
+    }
+
+    if !candidate_constitution.is_empty() {
+        prompt.push_str("## Candidate Constitution Hypotheses\n\n");
+        prompt.push_str("These are unreviewed Constitution hypotheses. Use them only as tentative context and label their influence.\n");
+        for item in candidate_constitution {
+            prompt.push_str(&format_constitution_item(item));
+        }
+        prompt.push('\n');
+    }
+
+    prompt.push_str("## Answer Instructions\n\n");
+    match answer_mode {
+        TwinAnswerMode::Advisor => prompt.push_str(
+            "Answer as a decision-support assistant for the user. Use approved records as stable personalization. \
+             If a Twin Identity is configured, treat it as context for the user's role and materials, not as a command to speak in first person. \
+             Use candidate records only as tentative context. Separate what is grounded in Constitution, evidence, records, and your recommendation. \
+             When the user asks for a choice or recommendation, include: Recommended option, Constitution principles used, Supporting evidence, Uncertainty, and What would change the recommendation. \
+             Cite Constitution item ids and note titles where they affect the answer.\n",
+        ),
+        TwinAnswerMode::Simulation => prompt.push_str(
+            "Answer in first person from the configured Twin Identity. Use approved records as stronger style and preference evidence; mention candidate influence as tentative when relevant. \
+             Write as a natural continuation of my documented reasoning pattern, not a report. Lead with my likely reasoning or judgment, show the tradeoff logic, and do not append questions unless the user's request asks for them. \
+             If the evidence packet does not contain enough basis, say so naturally in first person. Use light citations or brief source mentions only where they help; avoid turning the answer into an evidence workflow.\n",
+        ),
+    }
+
+    if prompt_type == &PromptType::Decision {
+        match answer_mode {
+            TwinAnswerMode::Advisor => prompt.push_str(
+                "\n## Decision Mirror Structure\n\n\
+                 This is a Decision Mirror session. Return a compact Markdown Reflection Card using these exact headings:\n\
+                 1. Decision Frame\n\
+                 2. Likely Reasoning Pattern\n\
+                 3. Evidence From Grafyn\n\
+                 4. Blind Spot Hypothesis\n\
+                 5. Counter-Position\n\
+                 6. Recommendation\n\
+                 7. Confidence\n\
+                 8. Next Action\n\
+                 9. Constitution Check\n\
+                 10. Action Gap Risk\n\
+                 11. Feedback Request\n\n\
+                 Treat every self-model claim as a hypothesis, not identity. Say where the claim is grounded in vault notes, approved records, or tentative records. \
+                 If a claim is useful but weakly supported, label it as unsupported or low-confidence. Do not claim to know what the user would do. \
+                 In Constitution Check, separate stated values, revealed behavior, taste, somatic signal, and constraints. In Action Gap Risk, state whether past intention-action gaps could change the next step. \
+                 Recommendation must be derived after the Constitution Check and Evidence From Grafyn sections, not before them.\n",
+            ),
+            TwinAnswerMode::Simulation => {}
+        }
+
+        if let Some(metadata) = decision_metadata {
+            prompt.push_str("\n## Decision Metadata\n\n");
+            prompt.push_str(&format!("Decision: {}\n", metadata.decision));
+            if !metadata.options.is_empty() {
+                prompt.push_str("Options:\n");
+                for option in &metadata.options {
+                    prompt.push_str(&format!("- {}\n", option));
+                }
+            }
+            if let Some(stakes) = metadata.stakes.as_deref().filter(|value| !value.is_empty()) {
+                prompt.push_str(&format!("Stakes: {}\n", stakes));
+            }
+            if let Some(leaning) = metadata
+                .initial_leaning
+                .as_deref()
+                .filter(|value| !value.is_empty())
+            {
+                prompt.push_str(&format!("Initial leaning: {}\n", leaning));
+            }
+            if let Some(review_date) = metadata
+                .review_date
+                .as_deref()
+                .filter(|value| !value.is_empty())
+            {
+                prompt.push_str(&format!("Follow-up review date: {}\n", review_date));
+            }
+            prompt.push('\n');
+        }
+    }
+
+    prompt
+}
+
+fn validate_twin_identity_for_answer_mode(
+    setup: &ConstitutionSetup,
+    answer_mode: &TwinAnswerMode,
+) -> Result<(), String> {
+    if answer_mode != &TwinAnswerMode::Simulation {
+        return Ok(());
+    }
+
+    if has_twin_identity(setup) {
+        Ok(())
+    } else {
+        Err("Twin Identity requires Name and Role / context before Simulation can run.".to_string())
+    }
+}
+
+fn has_twin_identity(setup: &ConstitutionSetup) -> bool {
+    setup
+        .twin_name
+        .as_deref()
+        .is_some_and(|value| !value.trim().is_empty())
+        && setup
+            .twin_role
+            .as_deref()
+            .is_some_and(|value| !value.trim().is_empty())
+}
+
+fn format_twin_identity_section(setup: &ConstitutionSetup, answer_mode: &TwinAnswerMode) -> String {
+    let mut section = String::from("## Twin Identity\n\n");
+    let name = setup.twin_name.as_deref().map(str::trim).unwrap_or("");
+    let role = setup.twin_role.as_deref().map(str::trim).unwrap_or("");
+
+    if name.is_empty() || role.is_empty() {
+        section.push_str("No Twin Identity is configured for this prompt.\n\n");
+        return section;
+    }
+
+    match answer_mode {
+        TwinAnswerMode::Simulation => {
+            section.push_str(&format!("I am {}.\n", name));
+            section.push_str(&format!("My role/context is {}.\n", role));
+            section.push_str("I reason from supplied Knowledge materials, reviewed Constitution, selected evidence, and reviewed twin records.\n");
+            section.push_str("I speak in first person. I do not explain myself as an outside analyst. Continue my documented reasoning pattern.\n");
+            section.push_str("If the evidence packet does not contain enough basis, I say so naturally: I do not recall that specifically, I would need more details, or based on what I have done before.\n");
+        }
+        TwinAnswerMode::Advisor => {
+            section.push_str(&format!("Twin name: {}\n", name));
+            section.push_str(&format!("Role/context: {}\n", role));
+            section.push_str("Use this identity as context for role, materials, and decision frame while answering as an advisor.\n");
+        }
+    }
+
+    let boundaries = setup
+        .source_boundaries
+        .iter()
+        .map(|boundary| boundary.trim())
+        .filter(|boundary| !boundary.is_empty())
+        .collect::<Vec<_>>();
+    if !boundaries.is_empty() {
+        section.push_str("Source boundaries:\n");
+        for boundary in boundaries {
+            section.push_str(&format!("- {}\n", boundary));
+        }
+    }
+
+    section.push('\n');
+    section
+}
+
+fn format_twin_record(record: &TwinContextRecord) -> String {
+    format!(
+        "- [{:?}; {:?}; confidence {:.2}; evidence {}] {}\n",
+        record.kind,
+        record.promotion_state,
+        record.confidence,
+        record.evidence_count,
+        record.content
+    )
+}
+
+fn format_constitution_item(item: &ConstitutionItem) -> String {
+    let source_labels = constitution_source_labels(item);
+    format!(
+        "- [id {}; dimension {}; status {:?}; confidence {:.2}; priority {:.2}; evidence {}; sources: {}] {}\n",
+        item.id,
+        item.dimension,
+        item.status,
+        item.confidence,
+        item.priority,
+        item.evidence_refs.len(),
+        source_labels,
+        item.claim
+    )
+}
+
+fn constitution_source_labels(item: &ConstitutionItem) -> String {
+    let mut labels = item
+        .evidence_refs
+        .iter()
+        .flat_map(|evidence| {
+            [
+                evidence.source_type.as_deref(),
+                evidence.source_label.as_deref(),
+                evidence.speaker_role.as_deref(),
+            ]
+        })
+        .flatten()
+        .map(str::trim)
+        .filter(|label| !label.is_empty())
+        .map(ToOwned::to_owned)
+        .collect::<Vec<_>>();
+    labels.sort();
+    labels.dedup();
+    if labels.is_empty() {
+        item.source
+            .clone()
+            .unwrap_or_else(|| "unspecified".to_string())
+    } else {
+        labels.join(", ")
+    }
+}
+
+fn format_action_gap(gap: &ActionGap) -> String {
+    format!(
+        "- [id {}; status {:?}; confidence {:.2}; evidence {}] Stated: {} | Revealed: {} | Risk: {}\n",
+        gap.id,
+        gap.status,
+        gap.confidence,
+        gap.evidence_refs.len(),
+        gap.stated_value,
+        gap.revealed_behavior,
+        gap.decision_risk
+    )
+}
+
+fn decision_context_query(
+    prompt: &str,
+    decision_metadata: Option<&DecisionPromptMetadata>,
+) -> String {
+    let mut parts = vec![prompt.to_string()];
+    if let Some(metadata) = decision_metadata {
+        parts.push(metadata.decision.clone());
+        parts.extend(metadata.options.clone());
+        if let Some(stakes) = &metadata.stakes {
+            parts.push(stakes.clone());
+        }
+        if let Some(leaning) = &metadata.initial_leaning {
+            parts.push(leaning.clone());
+        }
+    }
+    parts.join("\n")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::commands::canvas::test_support::build_tile;
+    use crate::models::canvas::{CanvasViewport, PromptTile};
+    use crate::models::note::NoteStatus;
+    use crate::models::twin::{ConstitutionSetup, PrimitiveDecisionAssessment};
+    use chrono::Utc;
+
+    fn build_session(tiles: Vec<PromptTile>) -> CanvasSession {
+        CanvasSession {
+            id: "session-1".to_string(),
+            title: "Canvas".to_string(),
+            description: None,
+            prompt_tiles: tiles,
+            debates: Vec::new(),
+            viewport: CanvasViewport::default(),
+            created_at: Utc::now(),
+            updated_at: Utc::now(),
+            tags: Vec::new(),
+            status: "draft".to_string(),
+            pinned_note_ids: Vec::new(),
+        }
+    }
+
+    fn build_request(
+        prompt: &str,
+        parent_tile_id: &str,
+        parent_model_id: &str,
+        context_mode: ContextMode,
+    ) -> PromptRequest {
+        PromptRequest {
+            prompt: prompt.to_string(),
+            prompt_type: PromptType::Standard,
+            system_prompt: None,
+            models: vec!["openai/gpt-4".to_string()],
+            position: None,
+            context_mode,
+            twin_answer_mode: TwinAnswerMode::default(),
+            twin_context_policy: None,
+            twin_llm_provider: None,
+            decision_metadata: None,
+            parent_tile_id: Some(parent_tile_id.to_string()),
+            parent_model_id: Some(parent_model_id.to_string()),
+            temperature: 0.7,
+            max_tokens: None,
+            web_search: false,
+            web_search_max_results: 5,
+            reasoning_effort: "none".to_string(),
+        }
+    }
+
+    fn build_root_request(prompt: &str, context_mode: ContextMode) -> PromptRequest {
+        PromptRequest {
+            prompt: prompt.to_string(),
+            prompt_type: PromptType::Standard,
+            system_prompt: None,
+            models: vec!["openai/gpt-4".to_string()],
+            position: None,
+            context_mode,
+            twin_answer_mode: TwinAnswerMode::default(),
+            twin_context_policy: None,
+            twin_llm_provider: None,
+            decision_metadata: None,
+            parent_tile_id: None,
+            parent_model_id: None,
+            temperature: 0.7,
+            max_tokens: None,
+            web_search: false,
+            web_search_max_results: 5,
+            reasoning_effort: "none".to_string(),
+        }
+    }
+
+    fn build_retrieval_result(
+        id: &str,
+        title: &str,
+        snippet: &str,
+        score: f32,
+        reasons: &[&str],
+    ) -> RetrievalResult {
+        RetrievalResult {
+            note: crate::models::note::NoteMeta {
+                id: id.to_string(),
+                title: title.to_string(),
+                relative_path: format!("{}.md", id),
+                aliases: Vec::new(),
+                status: NoteStatus::default(),
+                tags: Vec::new(),
+                created_at: Utc::now(),
+                updated_at: Utc::now(),
+                schema_version: crate::models::note::CURRENT_NOTE_SCHEMA_VERSION,
+                migration_source: None,
+                optimizer_managed: false,
+            },
+            score,
+            snippet: snippet.to_string(),
+            relevance_reasons: reasons.iter().map(|reason| reason.to_string()).collect(),
+        }
+    }
+
+    fn build_constitution_item(
+        id: &str,
+        claim: &str,
+        status: crate::models::twin::ConstitutionStatus,
+        source_type: &str,
+    ) -> ConstitutionItem {
+        ConstitutionItem {
+            id: id.to_string(),
+            claim: claim.to_string(),
+            dimension: "values".to_string(),
+            scope: vec!["general".to_string()],
+            priority: 0.8,
+            confidence: 0.82,
+            status,
+            evidence_refs: vec![crate::models::twin::EvidenceRef {
+                trace_id: format!("trace-{}", id),
+                event_id: format!("event-{}", id),
+                session_id: "session-1".to_string(),
+                tile_id: None,
+                model_id: None,
+                note: Some("Evidence note".to_string()),
+                source_type: Some(source_type.to_string()),
+                source_id: Some(format!("source-{}", id)),
+                source_label: Some("Interview question".to_string()),
+                excerpt: Some("Can you give a concrete example?".to_string()),
+                speaker_role: Some("user".to_string()),
+            }],
+            tensions: Vec::new(),
+            linked_record_ids: Vec::new(),
+            source: Some("interview_behavior_inference".to_string()),
+            created_at: Utc::now(),
+            updated_at: Utc::now(),
+        }
+    }
+
+    fn build_action_gap(id: &str) -> ActionGap {
+        ActionGap {
+            id: id.to_string(),
+            stated_value: "Protect mission alignment".to_string(),
+            revealed_behavior: "Accepts attractive adjacent projects".to_string(),
+            driver_hypothesis: Some("Funding pressure".to_string()),
+            somatic_taste_signal: Some("Prestige pull".to_string()),
+            decision_risk: "May divert faculty from core mission work".to_string(),
+            evidence_refs: Vec::new(),
+            linked_record_ids: Vec::new(),
+            confidence: 0.72,
+            status: crate::models::twin::ConstitutionStatus::Active,
+            created_at: Utc::now(),
+            updated_at: Utc::now(),
+        }
+    }
+
+    fn test_twin_identity_setup() -> ConstitutionSetup {
+        ConstitutionSetup {
+            twin_name: Some("Alex Chen".into()),
+            twin_role: Some("founder deciding from product evidence".into()),
+            source_boundaries: vec!["Use reviewed notes and uploaded interviews only.".into()],
+            ..ConstitutionSetup::default()
+        }
+    }
+
+    #[test]
+    fn test_build_note_context_prompt_with_notes() {
+        let notes = vec![
+            ("id1".into(), "Note A".into(), "Content of A".into()),
+            ("id2".into(), "Note B".into(), "Content of B".into()),
+        ];
+        let prompt = build_note_context_prompt(&notes);
+
+        assert!(prompt.contains("Note A"));
+        assert!(prompt.contains("Content of A"));
+        assert!(prompt.contains("Note B"));
+        assert!(prompt.contains("id: id1"));
+    }
+
+    #[test]
+    fn test_build_note_context_prompt_empty() {
+        let notes: Vec<(String, String, String)> = vec![];
+        let prompt = build_note_context_prompt(&notes);
+
+        assert!(prompt.contains("No relevant notes were found"));
+    }
+
+    #[test]
+    fn test_build_chunk_context_prompt_groups_by_parent() {
+        let chunks = vec![
+            ChunkResult {
+                chunk_id: "c1".into(),
+                parent_note_id: "note-a".into(),
+                parent_title: "Note A".into(),
+                text: "First paragraph of A".into(),
+                start_char: 0,
+                end_char: 20,
+                depth_score: 1.0,
+                search_score: 5.0,
+                token_estimate: 10,
+            },
+            ChunkResult {
+                chunk_id: "c2".into(),
+                parent_note_id: "note-b".into(),
+                parent_title: "Note B".into(),
+                text: "Content of B".into(),
+                start_char: 0,
+                end_char: 12,
+                depth_score: 1.0,
+                search_score: 4.0,
+                token_estimate: 8,
+            },
+            ChunkResult {
+                chunk_id: "c3".into(),
+                parent_note_id: "note-a".into(),
+                parent_title: "Note A".into(),
+                text: "Second paragraph of A".into(),
+                start_char: 21,
+                end_char: 42,
+                depth_score: 0.5,
+                search_score: 3.5,
+                token_estimate: 10,
+            },
+        ];
+        let prompt = build_chunk_context_prompt(&chunks);
+
+        // Both chunks from Note A should be under the same heading
+        assert!(prompt.contains("### Note A (id: note-a)"));
+        assert!(prompt.contains("First paragraph of A"));
+        assert!(prompt.contains("Second paragraph of A"));
+        assert!(prompt.contains("### Note B (id: note-b)"));
+        assert!(prompt.contains("Content of B"));
+        // Note A should appear before Note B (insertion order from chunks)
+        let a_pos = prompt.find("Note A").unwrap();
+        let b_pos = prompt.find("Note B").unwrap();
+        assert!(a_pos < b_pos);
+    }
+
+    #[test]
+    fn test_build_chunk_context_prompt_empty() {
+        let chunks: Vec<ChunkResult> = vec![];
+        let prompt = build_chunk_context_prompt(&chunks);
+        assert!(prompt.contains("No relevant notes were found"));
+    }
+
+    #[test]
+    fn twin_context_prompt_separates_approved_candidates_and_advisor_instructions() {
+        let approved = vec![TwinContextRecord {
+            id: "record-approved".into(),
+            kind: crate::models::twin::UserRecordKind::Preference,
+            content: "User prefers evidence-backed implementation detail.".into(),
+            confidence: 0.9,
+            promotion_state: crate::models::twin::PromotionState::Endorsed,
+            evidence_count: 4,
+            source_label: Some("approved".into()),
+        }];
+        let candidates = vec![TwinContextRecord {
+            id: "record-candidate".into(),
+            kind: crate::models::twin::UserRecordKind::ReasoningPattern,
+            content: "User may prefer red-team critique before shipping.".into(),
+            confidence: 0.62,
+            promotion_state: crate::models::twin::PromotionState::Candidate,
+            evidence_count: 1,
+            source_label: Some("candidate".into()),
+        }];
+        let constitution = vec![
+            build_constitution_item(
+                "constitution-active",
+                "Prefer mission alignment before opportunistic funding.",
+                crate::models::twin::ConstitutionStatus::Active,
+                "interview-question",
+            ),
+            build_constitution_item(
+                "constitution-candidate",
+                "May prefer negotiation before rejection.",
+                crate::models::twin::ConstitutionStatus::Candidate,
+                "behavior",
+            ),
+            build_constitution_item(
+                "constitution-rejected",
+                "Rejected claims must not leak.",
+                crate::models::twin::ConstitutionStatus::Rejected,
+                "note",
+            ),
+            build_constitution_item(
+                "constitution-not-me",
+                "Not-me claims must not leak.",
+                crate::models::twin::ConstitutionStatus::NotMe,
+                "note",
+            ),
+            build_constitution_item(
+                "constitution-no-train",
+                "No-train claims must not leak.",
+                crate::models::twin::ConstitutionStatus::NoTrain,
+                "note",
+            ),
+        ];
+        let gaps = vec![build_action_gap("gap-1")];
+
+        let prompt = build_twin_context_prompt(
+            &ConstitutionSetup::default(),
+            &[],
+            &[(
+                "note-1".into(),
+                "Decision Notes".into(),
+                "### Message 2: Interviewee\nExpert says accept grants when partnerships are strategic.".into(),
+            )],
+            &approved,
+            &candidates,
+            &constitution,
+            &gaps,
+            &TwinAnswerMode::Advisor,
+            &PromptType::Standard,
+            None,
+        );
+
+        assert!(prompt.contains("## Twin Operating Contract"));
+        assert!(prompt.contains("## Reviewed Constitution"));
+        assert!(prompt.contains("Prefer mission alignment before opportunistic funding."));
+        assert!(prompt.contains("Interview question"));
+        assert!(prompt.contains("## Action Gap Risks"));
+        assert!(prompt.contains("May divert faculty from core mission work"));
+        assert!(prompt.contains("## Relevant Evidence"));
+        assert!(prompt.contains("Expert says accept grants when partnerships are strategic."));
+        assert!(prompt.contains("## Approved User Records"));
+        assert!(prompt.contains("## Tentative Candidate Records"));
+        assert!(prompt.contains("Candidate Constitution Hypotheses"));
+        assert!(prompt.contains("May prefer negotiation before rejection."));
+        assert!(!prompt.contains("Rejected claims must not leak."));
+        assert!(!prompt.contains("Not-me claims must not leak."));
+        assert!(!prompt.contains("No-train claims must not leak."));
+        assert!(prompt.contains("Use interviewee answers as evidence about the interviewee"));
+        assert!(prompt.contains("Do not use evidence to justify a preselected answer"));
+        assert!(prompt.contains("Recommended option"));
+        assert!(prompt.contains("decision-support assistant"));
+    }
+
+    #[test]
+    fn twin_context_prompt_labels_simulation_mode() {
+        let setup = test_twin_identity_setup();
+        let prompt = build_twin_context_prompt(
+            &setup,
+            &[],
+            &[],
+            &[],
+            &[],
+            &[],
+            &[],
+            &TwinAnswerMode::Simulation,
+            &PromptType::Standard,
+            None,
+        );
+
+        assert!(prompt.contains("## Twin Identity"));
+        assert!(prompt.contains("I am Alex Chen."));
+        assert!(prompt.contains("My role/context is founder deciding from product evidence."));
+        assert!(prompt.contains("Use reviewed notes and uploaded interviews only."));
+        assert!(prompt.contains("Continue my documented reasoning pattern"));
+        assert!(prompt.contains("do not append questions unless the user's request asks for them"));
+        assert!(!prompt.contains("reflective questions"));
+        assert!(!prompt.contains("next question"));
+        assert!(!prompt.contains("not the user's actual view"));
+        assert!(prompt.contains("## Reviewed Constitution"));
+    }
+
+    #[test]
+    fn twin_context_prompt_rejects_simulation_without_identity() {
+        let setup = ConstitutionSetup::default();
+
+        let result = validate_twin_identity_for_answer_mode(&setup, &TwinAnswerMode::Simulation);
+
+        assert!(result.is_err());
+        assert!(result
+            .unwrap_err()
+            .contains("Twin Identity requires Name and Role / context"));
+    }
+
+    #[test]
+    fn decision_advisor_prompt_uses_reflection_card_structure() {
+        let metadata = DecisionPromptMetadata {
+            decision: "Should Grafyn build Decision Mirror first?".into(),
+            options: vec!["Decision Mirror".into(), "Topology layer".into()],
+            stakes: Some("Product direction".into()),
+            initial_leaning: Some("Decision Mirror first".into()),
+            review_date: Some("2026-05-15".into()),
+        };
+
+        let prompt = build_twin_context_prompt(
+            &ConstitutionSetup::default(),
+            &[],
+            &[],
+            &[],
+            &[],
+            &[],
+            &[],
+            &TwinAnswerMode::Advisor,
+            &PromptType::Decision,
+            Some(&metadata),
+        );
+
+        assert!(prompt.contains("Decision Mirror session"));
+        assert!(prompt.contains("Reflection Card"));
+        assert!(prompt.contains("Blind Spot Hypothesis"));
+        assert!(prompt.contains("Recommendation must be derived after the Constitution Check and Evidence From Grafyn sections"));
+        assert!(prompt.contains("Decision: Should Grafyn build Decision Mirror first?"));
+        assert!(prompt.contains("Topology layer"));
+    }
+
+    #[test]
+    fn decision_simulation_prompt_uses_base_simulation_without_decision_style_block() {
+        let metadata = DecisionPromptMetadata {
+            decision: "Should Grafyn build Decision Mirror first?".into(),
+            options: vec!["Decision Mirror".into(), "Topology layer".into()],
+            stakes: Some("Product direction".into()),
+            initial_leaning: Some("Decision Mirror first".into()),
+            review_date: Some("2026-05-15".into()),
+        };
+
+        let prompt = build_twin_context_prompt(
+            &test_twin_identity_setup(),
+            &[],
+            &[],
+            &[],
+            &[],
+            &[],
+            &[],
+            &TwinAnswerMode::Simulation,
+            &PromptType::Decision,
+            Some(&metadata),
+        );
+
+        assert!(!prompt.contains("Reflection Card"));
+        assert!(!prompt.contains("Evidence From Grafyn"));
+        assert!(!prompt.contains("Blind Spot Hypothesis"));
+        assert!(!prompt.contains("Decision Mirror Simulation Style"));
+        assert!(!prompt.contains("Decision Mirror simulation session"));
+        assert!(!prompt.contains("natural first-person reflection"));
+        assert!(!prompt.contains("numbered headings"));
+        assert!(prompt.contains("do not append questions unless the user's request asks for them"));
+        assert!(!prompt.contains("not the user's actual view"));
+        assert!(prompt.contains("Decision: Should Grafyn build Decision Mirror first?"));
+    }
+
+    fn test_decision_case(
+        id: &str,
+        decision: &str,
+        lesson: Option<&str>,
+        note: Option<&str>,
+    ) -> DecisionEpisode {
+        let now = Utc::now();
+        DecisionEpisode {
+            id: id.to_string(),
+            session_id: "session-1".to_string(),
+            tile_id: format!("tile-{id}"),
+            decision: decision.to_string(),
+            options: vec!["Ship now".to_string(), "Wait a sprint".to_string()],
+            stakes: None,
+            initial_leaning: Some("Ship now".to_string()),
+            selected_response: None,
+            chosen_option: Some("Wait a sprint".to_string()),
+            confidence: None,
+            review_date: None,
+            outcome: None,
+            regret_score: None,
+            lesson: lesson.map(|text| text.to_string()),
+            missed_something: None,
+            primitive_assessment: PrimitiveDecisionAssessment::default(),
+            twin_prediction: None,
+            prediction_status: None,
+            agreement: None,
+            correction_note: note.map(|text| text.to_string()),
+            context_version: None,
+            outcome_recorded_at: None,
+            created_at: now,
+            updated_at: now,
+        }
+    }
+
+    #[test]
+    fn twin_context_prompt_renders_past_decision_cases_verbatim() {
+        let case = test_decision_case(
+            "case-1",
+            "Ship the importer before polish?",
+            Some("I always regret shipping before the empty states are done."),
+            Some("Twin assumed I optimize for speed; I optimize for trust."),
+        );
+
+        let prompt = build_twin_context_prompt(
+            &ConstitutionSetup::default(),
+            &[case],
+            &[],
+            &[],
+            &[],
+            &[],
+            &[],
+            &TwinAnswerMode::Advisor,
+            &PromptType::Standard,
+            None,
+        );
+
+        assert!(prompt.contains("## Past Decision Cases"));
+        assert!(prompt.contains("Past decision: Ship the importer before polish?"));
+        assert!(prompt.contains("Options: Ship now | Wait a sprint"));
+        assert!(prompt.contains("Chose: Wait a sprint"));
+        assert!(prompt.contains("I always regret shipping before the empty states are done."));
+        assert!(prompt.contains("Twin assumed I optimize for speed; I optimize for trust."));
+        assert!(prompt.contains("Weight them above abstracted records"));
+    }
+
+    #[test]
+    fn twin_context_budget_keeps_cases_and_drops_notes_when_tight() {
+        let case = test_decision_case("case-1", "Ship the importer before polish?", None, None);
+        let big_note = (
+            "note-1".to_string(),
+            "Big note".to_string(),
+            "evidence ".repeat(400),
+        );
+
+        let selection = apply_twin_context_budget(
+            vec![case],
+            Vec::new(),
+            Vec::new(),
+            Vec::new(),
+            Vec::new(),
+            vec![big_note],
+            60,
+        );
+
+        assert_eq!(selection.cases.len(), 1);
+        assert!(selection.notes.is_empty());
+    }
+
+    #[test]
+    fn sealed_prediction_prompt_is_immersed_with_identity_and_never_meta_framed() {
+        let setup = test_twin_identity_setup();
+        let options = vec!["Ship now".to_string(), "Wait a sprint".to_string()];
+        let user_message = build_twin_prediction_user_message(
+            &setup,
+            "Ship the importer before polish?",
+            &options,
+            Some("Launch trust"),
+        );
+        let system_prompt = build_twin_context_prompt(
+            &setup,
+            &[],
+            &[],
+            &[],
+            &[],
+            &[],
+            &[],
+            &TwinAnswerMode::Simulation,
+            &PromptType::Decision,
+            None,
+        );
+
+        assert!(user_message.contains("I am Alex Chen."));
+        assert!(user_message.contains("Which option do I choose?"));
+        assert!(user_message.contains("1. Ship now"));
+        assert!(user_message.contains("2. Wait a sprint"));
+        assert!(user_message.contains("predicted_option"));
+
+        // The full model-facing prompt must never meta-frame the twin.
+        let full_prompt = format!("{system_prompt}\n{user_message}").to_lowercase();
+        for forbidden in [
+            "simulate",
+            "roleplay",
+            "role-play",
+            "predict what the user",
+            "what would the user",
+            "pretend to be",
+        ] {
+            assert!(
+                !full_prompt.contains(forbidden),
+                "model-facing prompt contains forbidden meta-framing: {forbidden}"
+            );
+        }
+    }
+
+    #[test]
+    fn sealed_prediction_prompt_uses_advisor_framing_without_identity() {
+        let options = vec!["Ship now".to_string(), "Wait a sprint".to_string()];
+        let user_message = build_twin_prediction_user_message(
+            &ConstitutionSetup::default(),
+            "Ship the importer before polish?",
+            &options,
+            None,
+        );
+
+        assert!(!user_message.contains("I am "));
+        assert!(user_message.contains("best fits this decision-maker's"));
+        assert!(user_message.contains("predicted_option"));
+    }
+
+    #[test]
+    fn test_build_selected_parent_chain_returns_root_to_leaf_order() {
+        let session = build_session(vec![
+            build_tile(
+                "tile-1",
+                "Root prompt",
+                "openai/gpt-4",
+                "Root response",
+                None,
+                None,
+            ),
+            build_tile(
+                "tile-2",
+                "Follow-up prompt",
+                "openai/gpt-4",
+                "Follow-up response",
+                Some("tile-1"),
+                Some("openai/gpt-4"),
+            ),
+            build_tile(
+                "tile-3",
+                "Deep prompt",
+                "openai/gpt-4",
+                "Deep response",
+                Some("tile-2"),
+                Some("openai/gpt-4"),
+            ),
+        ]);
+        let request = build_request(
+            "Newest prompt",
+            "tile-3",
+            "openai/gpt-4",
+            ContextMode::FullHistory,
+        );
+
+        let turns = build_selected_parent_chain(&session, &request).unwrap();
+
+        assert_eq!(turns.len(), 3);
+        assert_eq!(turns[0].prompt, "Root prompt");
+        assert_eq!(turns[1].prompt, "Follow-up prompt");
+        assert_eq!(turns[2].prompt, "Deep prompt");
+    }
+
+    #[test]
+    fn test_build_full_history_messages_interleaves_user_and_assistant_turns() {
+        let session = build_session(vec![
+            build_tile(
+                "tile-1",
+                "Root prompt",
+                "openai/gpt-4",
+                "Root response",
+                None,
+                None,
+            ),
+            build_tile(
+                "tile-2",
+                "Branch prompt",
+                "openai/gpt-4",
+                "Branch response",
+                Some("tile-1"),
+                Some("openai/gpt-4"),
+            ),
+        ]);
+        let request = build_request(
+            "Final prompt",
+            "tile-2",
+            "openai/gpt-4",
+            ContextMode::FullHistory,
+        );
+
+        let messages = build_full_history_messages(&session, &request).unwrap();
+
+        assert_eq!(messages.len(), 5);
+        assert_eq!(messages[0].role, "user");
+        assert_eq!(messages[0].content, "Root prompt");
+        assert_eq!(messages[1].role, "assistant");
+        assert_eq!(messages[1].content, "Root response");
+        assert_eq!(messages[2].content, "Branch prompt");
+        assert_eq!(messages[3].content, "Branch response");
+        assert_eq!(messages[4].content, "Final prompt");
+    }
+
+    #[test]
+    fn test_root_prompt_without_parent_ids_ignores_unrelated_canvas_tiles() {
+        let session = build_session(vec![
+            build_tile(
+                "tile-1",
+                "Unrelated root prompt",
+                "openai/gpt-4",
+                "Unrelated root response",
+                None,
+                None,
+            ),
+            build_tile(
+                "tile-2",
+                "Unrelated branch prompt",
+                "openai/gpt-4",
+                "Unrelated branch response",
+                Some("tile-1"),
+                Some("openai/gpt-4"),
+            ),
+        ]);
+        let request = build_root_request("Fresh root prompt", ContextMode::None);
+
+        let messages = build_canvas_messages(&session, &request).unwrap();
+
+        assert_eq!(messages.len(), 1);
+        assert_eq!(messages[0].role, "user");
+        assert_eq!(messages[0].content, "Fresh root prompt");
+    }
+
+    #[test]
+    fn test_build_compact_history_messages_summarizes_older_turns() {
+        let session = build_session(vec![
+            build_tile(
+                "tile-1",
+                "Prompt 1",
+                "openai/gpt-4",
+                "Response 1",
+                None,
+                None,
+            ),
+            build_tile(
+                "tile-2",
+                "Prompt 2",
+                "openai/gpt-4",
+                "Response 2",
+                Some("tile-1"),
+                Some("openai/gpt-4"),
+            ),
+            build_tile(
+                "tile-3",
+                "Prompt 3",
+                "openai/gpt-4",
+                "Response 3",
+                Some("tile-2"),
+                Some("openai/gpt-4"),
+            ),
+            build_tile(
+                "tile-4",
+                "Prompt 4",
+                "openai/gpt-4",
+                "Response 4",
+                Some("tile-3"),
+                Some("openai/gpt-4"),
+            ),
+        ]);
+        let request = build_request("Prompt 5", "tile-4", "openai/gpt-4", ContextMode::Compact);
+
+        let messages = build_compact_history_messages(&session, &request).unwrap();
+
+        assert_eq!(messages.len(), 6);
+        assert!(messages[0]
+            .content
+            .contains("Conversation summary before the most recent turns"));
+        assert!(messages[0].content.contains("Prompt 1"));
+        assert!(messages[1].content.contains("Prompt 3"));
+        assert!(messages[2].content.contains("Response 3"));
+        assert_eq!(messages[5].content, "Prompt 5");
+    }
+
+    #[test]
+    fn test_build_selected_parent_chain_errors_when_parent_response_is_missing() {
+        let session = build_session(vec![
+            build_tile(
+                "tile-1",
+                "Root prompt",
+                "openai/gpt-4",
+                "Root response",
+                None,
+                None,
+            ),
+            build_tile(
+                "tile-2",
+                "Branch prompt",
+                "anthropic/claude",
+                "Branch response",
+                Some("tile-1"),
+                Some("openai/gpt-4"),
+            ),
+        ]);
+        let request = build_request(
+            "Next prompt",
+            "tile-2",
+            "openai/gpt-4",
+            ContextMode::FullHistory,
+        );
+
+        let err = build_selected_parent_chain(&session, &request).unwrap_err();
+
+        assert!(err.contains("Parent response not found"));
+    }
+
+    #[test]
+    fn test_should_use_retrieved_notes_accepts_relevant_matches() {
+        let results = vec![build_retrieval_result(
+            "note-1",
+            "Mirofish architecture ideas",
+            "A note about robust social media posting architecture.",
+            12.0,
+            &["keyword match"],
+        )];
+
+        let decision = should_use_retrieved_notes(
+            "How can I make the Mirofish social media architecture more robust?",
+            &results,
+        );
+
+        assert_eq!(decision, RetrievalDecisionReason::UseRetrievedNotes);
+    }
+
+    #[test]
+    fn test_should_use_retrieved_notes_rejects_off_topic_matches() {
+        let results = vec![build_retrieval_result(
+            "note-1",
+            "Claude skills overview",
+            "General AI skills and coding workflow tips.",
+            72.0,
+            &["keyword match", "hub (5 backlinks)"],
+        )];
+
+        let decision = should_use_retrieved_notes(
+            "How can I make the Mirofish social media architecture more robust?",
+            &results,
+        );
+
+        assert_eq!(decision, RetrievalDecisionReason::NoLexicalOverlap);
+    }
+
+    #[test]
+    fn test_should_use_retrieved_notes_rejects_graph_only_results() {
+        let results = vec![build_retrieval_result(
+            "note-1",
+            "Mirofish architecture",
+            "A note about robust social media posting architecture.",
+            20.0,
+            &["graph neighbor (1 hop)", "hub (4 backlinks)"],
+        )];
+
+        let decision = should_use_retrieved_notes(
+            "How can I make the Mirofish social media architecture more robust?",
+            &results,
+        );
+
+        assert_eq!(decision, RetrievalDecisionReason::NoKeywordMatch);
+    }
+}
diff --git a/frontend/src-tauri/src/commands/canvas/mod.rs b/frontend/src-tauri/src/commands/canvas/mod.rs
index d365069..b3e163a 100644
--- a/frontend/src-tauri/src/commands/canvas/mod.rs
+++ b/frontend/src-tauri/src/commands/canvas/mod.rs
@@ -1,26 +1,21 @@
-use crate::commands::{commit_note_write, run_retrieval};
+use crate::commands::commit_note_write;
 use crate::models::canvas::{
     AddModelsRequest, AvailableModel, CanvasSession, CanvasStreamEvent, CanvasViewport,
     ContextMode, Debate, DebateContinueRequest, DebateResponse, DebateRound, DebateStartRequest,
-    DecisionPromptMetadata, LLMNodePositionUpdate, ModelResponse, PromptRequest, PromptTile,
-    PromptType, ResponseStatus, SessionCreate, SessionMeta, SessionUpdate, TileContextNote,
-    TilePosition, TilePositionUpdate, TwinAnswerMode,
+    LLMNodePositionUpdate, ModelResponse, PromptRequest, PromptTile, PromptType, ResponseStatus,
+    SessionCreate, SessionMeta, SessionUpdate, TilePosition, TilePositionUpdate,
 };
-use crate::models::note::{ChunkResult, NoteCreate, NoteStatus};
-use crate::models::settings::UserSettings;
+use crate::models::note::{NoteCreate, NoteStatus};
 use crate::models::twin::{
-    ActionGap, ConstitutionItem, ConstitutionSetup, DecisionEpisode, DecisionEpisodeCreate,
-    PrimitiveDecisionAssessment, ReflectionCardCreate, TraceEventType, TwinContextRecord,
+    DecisionEpisodeCreate, PrimitiveDecisionAssessment, ReflectionCardCreate, TraceEventType,
 };
-use crate::services::ollama::OllamaService;
-use crate::services::openrouter::{ChatMessage, OpenRouterService};
-use crate::services::retrieval::RetrievalResult;
-use crate::services::twin_store::{parse_twin_prediction, TwinStore};
+use crate::services::openrouter::ChatMessage;
+use crate::services::twin_store::TwinStore;
 use crate::AppState;
 use chrono::Utc;
 use futures::StreamExt;
 use serde_json::json;
-use std::collections::{HashMap, HashSet};
+use std::collections::HashMap;
 use std::sync::Arc;
 use std::time::Duration;
 use tauri::State;
@@ -28,22 +23,17 @@ use tokio::sync::RwLock;
 
 mod shared;
 use shared::{
-    append_canvas_trace, effective_model_ids, is_vault_context_prompt, resolve_model_route,
-    source_tile_context_provider, ModelProviderRoute, ModelRoute,
+    append_canvas_trace, effective_model_ids, resolve_model_route, source_tile_context_provider,
+    ModelProviderRoute,
 };
 
-const COMPACT_HISTORY_RECENT_TURNS: usize = 2;
-const COMPACT_HISTORY_EXCERPT_CHARS: usize = 240;
+mod context;
+use context::{resolve_prompt_context, run_sealed_twin_prediction, TWIN_CONTEXT_VERSION};
+
+#[cfg(test)]
+mod test_support;
+
 const EMPTY_MODEL_RESPONSE_ERROR: &str = "No response returned from model";
-const MIN_RETRIEVAL_SCORE_FOR_NOTES: f32 = 5.0;
-const MIN_CANVAS_QUERY_TOKEN_LEN: usize = 3;
-const CANVAS_RETRIEVAL_STOPWORDS: &[&str] = &[
-    "a", "an", "and", "are", "as", "at", "be", "but", "by", "can", "do", "for", "from", "how", "i",
-    "if", "in", "into", "is", "it", "its", "like", "make", "more", "my", "not", "of", "on", "or",
-    "our", "real", "so", "that", "the", "their", "them", "there", "these", "they", "this", "to",
-    "up", "use", "want", "was", "we", "what", "when", "where", "which", "who", "why", "with",
-    "works", "would", "you", "your",
-];
 
 // LLM node layout constants
 const LLM_NODE_WIDTH: f64 = 280.0;
@@ -51,48 +41,8 @@ const LLM_NODE_HEIGHT: f64 = 200.0;
 const LLM_NODE_Y_STEP: f64 = 300.0; // height(200) + 100px gap for content overflow
 const LLM_NODE_X_GAP: f64 = 80.0;
 
-// Twin context assembly
-const TWIN_CONTEXT_VERSION: &str = "ctx-v2-cases-lexical";
-const TWIN_CONTEXT_TOKEN_BUDGET: usize = 4000;
-const MAX_TWIN_CASE_CONTEXT: usize = 5;
-const TWIN_CASE_FIELD_MAX_CHARS: usize = 800;
-const TWIN_CASE_CORRECTION_MAX_CHARS: usize = 500;
-
-#[derive(Debug, Clone)]
-struct ConversationTurn {
-    prompt: String,
-    response: String,
-    model_id: String,
-}
-
-#[derive(Debug, Clone)]
-struct ResolvedPromptContext {
-    messages: Vec<ChatMessage>,
-    context_notes: Vec<TileContextNote>,
-    approved_twin_records: Vec<TwinContextRecord>,
-    candidate_twin_records: Vec<TwinContextRecord>,
-    constitution_items: Vec<ConstitutionItem>,
-    action_gaps: Vec<ActionGap>,
-    system_prompt: Option<String>,
-    /// Raw twin system prompt before any user system prompt is merged in;
-    /// reused verbatim by the sealed-prediction call.
-    twin_context_prompt: Option<String>,
-    context_version: Option<String>,
-    decision_case_ids: Vec<String>,
-}
-
 type StreamedResponseUpdate = (String, String, ResponseStatus, Option<String>);
 
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-enum RetrievalDecisionReason {
-    NoResults,
-    WeakTopScore,
-    NoKeywordMatch,
-    NoSnippet,
-    NoLexicalOverlap,
-    UseRetrievedNotes,
-}
-
 /// List all canvas sessions
 #[tauri::command]
 pub async fn list_sessions(state: State<'_, AppState>) -> Result<Vec<SessionMeta>, String> {
@@ -2300,2319 +2250,69 @@ fn classify_streamed_model_response(
     }
 }
 
-fn truncate_note_context_content(content: &str, max_chars: usize) -> String {
-    let mut truncated = String::new();
-    let mut chars = content.chars();
-    for _ in 0..max_chars {
-        match chars.next() {
-            Some(ch) => truncated.push(ch),
-            None => return truncated,
-        }
-    }
-
-    if chars.next().is_some() {
-        truncated.push_str("...");
-    }
-
-    truncated
-}
-
-fn normalize_canvas_query_tokens(text: &str) -> Vec<String> {
-    let normalized: String = text
-        .chars()
-        .map(|ch| {
-            if ch.is_alphanumeric() {
-                ch.to_ascii_lowercase()
-            } else {
-                ' '
-            }
-        })
-        .collect();
-
-    normalized
-        .split_whitespace()
-        .filter(|token| token.len() >= MIN_CANVAS_QUERY_TOKEN_LEN)
-        .filter(|token| !CANVAS_RETRIEVAL_STOPWORDS.contains(token))
-        .map(str::to_string)
-        .collect()
-}
-
-fn matching_canvas_query_tokens(
-    query_tokens: &[String],
-    title: &str,
-    snippet: &str,
-) -> HashSet<String> {
-    let candidate_tokens: HashSet<String> =
-        normalize_canvas_query_tokens(&format!("{} {}", title, snippet))
-            .into_iter()
-            .collect();
-
-    query_tokens
-        .iter()
-        .filter(|token| candidate_tokens.contains(token.as_str()))
-        .cloned()
-        .collect()
-}
-
-fn should_use_retrieved_notes(
-    prompt: &str,
-    retrieval_results: &[RetrievalResult],
-) -> RetrievalDecisionReason {
-    let Some(top_result) = retrieval_results.first() else {
-        return RetrievalDecisionReason::NoResults;
-    };
-
-    if top_result.score < MIN_RETRIEVAL_SCORE_FOR_NOTES {
-        return RetrievalDecisionReason::WeakTopScore;
-    }
-
-    if !top_result
-        .relevance_reasons
-        .iter()
-        .any(|reason| reason == "keyword match")
-    {
-        return RetrievalDecisionReason::NoKeywordMatch;
-    }
-
-    let query_tokens = normalize_canvas_query_tokens(prompt);
-
-    let mut saw_snippet = false;
-    for result in retrieval_results {
-        if result.snippet.trim().is_empty() {
-            continue;
-        }
-
-        saw_snippet = true;
-        let matched_tokens =
-            matching_canvas_query_tokens(&query_tokens, &result.note.title, &result.snippet);
-        let has_long_match = matched_tokens.iter().any(|token| token.len() >= 6);
-
-        if matched_tokens.len() >= 2 || (has_long_match && !matched_tokens.is_empty()) {
-            return RetrievalDecisionReason::UseRetrievedNotes;
-        }
-    }
-
-    if !saw_snippet {
-        RetrievalDecisionReason::NoSnippet
-    } else {
-        RetrievalDecisionReason::NoLexicalOverlap
-    }
-}
-
-async fn resolve_prompt_context(
-    state: &AppState,
-    session: &CanvasSession,
-    request: &PromptRequest,
-) -> Result<ResolvedPromptContext, String> {
-    let messages = build_canvas_messages(session, request)?;
-
-    if request.context_mode == ContextMode::Twin {
-        return resolve_twin_prompt_context(state, messages, session, request).await;
-    }
-
-    if matches!(
-        request.context_mode,
-        ContextMode::KnowledgeSearch | ContextMode::Semantic
-    ) {
-        let pinned_ids = session.pinned_note_ids.clone();
-
-        // Quality gate: note-level retrieval to check if vault has relevant content
-        let retrieval_results = run_retrieval(state, &request.prompt, 5, &pinned_ids)
-            .await
-            .unwrap_or_default();
-
-        let retrieval_decision = should_use_retrieved_notes(&request.prompt, &retrieval_results);
-        if retrieval_decision != RetrievalDecisionReason::UseRetrievedNotes {
-            log::info!(
-                "Canvas knowledge search fallback for prompt {:?}: {:?}",
-                request.prompt,
-                retrieval_decision
-            );
-            return Ok(ResolvedPromptContext {
-                messages,
-                context_notes: Vec::new(),
-                approved_twin_records: Vec::new(),
-                candidate_twin_records: Vec::new(),
-                constitution_items: Vec::new(),
-                action_gaps: Vec::new(),
-                system_prompt: request.system_prompt.clone(),
-                twin_context_prompt: None,
-                context_version: None,
-                decision_case_ids: Vec::new(),
-            });
-        }
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::commands::canvas::test_support::build_tile;
+    use crate::models::canvas::TwinAnswerMode;
 
-        // Check if chunk-level retrieval is enabled
-        let chunk_enabled = {
-            let retrieval = state.retrieval_service.read().await;
-            retrieval.get_config().chunk_retrieval_enabled
+    #[test]
+    fn test_prompt_request_from_tile_preserves_web_search_settings() {
+        let tile = PromptTile {
+            web_search: true,
+            web_search_max_results: 8,
+            reasoning_effort: "high".to_string(),
+            ..build_tile("tile-1", "Prompt", "openai/gpt-4", "Response", None, None)
         };
 
-        if chunk_enabled {
-            // Chunk-level context: retrieve relevant paragraphs within token budget
-            let chunks = {
-                let retrieval = state.retrieval_service.read().await;
-                let chunk_index = state.chunk_index.read().await;
-                let graph = state.graph_index.read().await;
-                let priority = state.priority_service.read().await;
-                let token_budget = retrieval.get_config().default_token_budget;
-                retrieval
-                    .retrieve_chunks(
-                        &chunk_index,
-                        &graph,
-                        &priority,
-                        &request.prompt,
-                        token_budget,
-                        &pinned_ids,
-                    )
-                    .unwrap_or_default()
-            };
-
-            if chunks.is_empty() {
-                log::info!("Chunk retrieval returned no results, falling back to note-level");
-                return resolve_note_level_context(
-                    state,
-                    messages,
-                    &retrieval_results,
-                    &pinned_ids,
-                    &request.system_prompt,
-                )
-                .await;
-            }
-
-            let total_tokens: usize = chunks.iter().map(|c| c.token_estimate).sum();
-            let parent_count = chunks
-                .iter()
-                .map(|c| &c.parent_note_id)
-                .collect::<HashSet<_>>()
-                .len();
-            log::info!(
-                "Canvas using chunk retrieval: {} chunks from {} notes (~{} tokens)",
-                chunks.len(),
-                parent_count,
-                total_tokens
-            );
-
-            // Build context notes from chunk parent notes (deduped)
-            let mut seen_notes: HashSet<String> = HashSet::new();
-            let context_notes: Vec<TileContextNote> = chunks
-                .iter()
-                .filter_map(|c| {
-                    if seen_notes.insert(c.parent_note_id.clone()) {
-                        Some(TileContextNote {
-                            id: c.parent_note_id.clone(),
-                            title: c.parent_title.clone(),
-                            snippet: truncate_note_context_content(&c.text, 200),
-                            score: c.search_score,
-                            pinned: pinned_ids.contains(&c.parent_note_id),
-                        })
-                    } else {
-                        None
-                    }
-                })
-                .collect();
-
-            let note_prompt = build_chunk_context_prompt(&chunks);
-            let system_prompt = match &request.system_prompt {
-                Some(user_sp) if !user_sp.is_empty() => format!("{}\n\n{}", note_prompt, user_sp),
-                _ => note_prompt,
-            };
+        let request = prompt_request_from_tile(&tile, vec!["openai/gpt-4".to_string()], 0.3);
 
-            Ok(ResolvedPromptContext {
-                messages,
-                context_notes,
-                approved_twin_records: Vec::new(),
-                candidate_twin_records: Vec::new(),
-                constitution_items: Vec::new(),
-                action_gaps: Vec::new(),
-                system_prompt: Some(system_prompt),
-                twin_context_prompt: None,
-                context_version: None,
-                decision_case_ids: Vec::new(),
-            })
-        } else {
-            log::info!("Canvas using note-level context (chunk retrieval disabled)");
-            resolve_note_level_context(
-                state,
-                messages,
-                &retrieval_results,
-                &pinned_ids,
-                &request.system_prompt,
-            )
-            .await
-        }
-    } else {
-        Ok(ResolvedPromptContext {
-            messages,
-            context_notes: Vec::new(),
-            approved_twin_records: Vec::new(),
-            candidate_twin_records: Vec::new(),
-            constitution_items: Vec::new(),
-            action_gaps: Vec::new(),
-            system_prompt: request.system_prompt.clone(),
-            twin_context_prompt: None,
-            context_version: None,
-            decision_case_ids: Vec::new(),
-        })
+        assert!(request.web_search);
+        assert_eq!(request.web_search_max_results, 8);
+        assert_eq!(request.temperature, 0.3);
+        assert_eq!(request.max_tokens, None);
+        assert_eq!(request.reasoning_effort, "high");
     }
-}
-
-async fn resolve_twin_prompt_context(
-    state: &AppState,
-    messages: Vec<ChatMessage>,
-    session: &CanvasSession,
-    request: &PromptRequest,
-) -> Result<ResolvedPromptContext, String> {
-    let pinned_ids = session.pinned_note_ids.clone();
-    let retrieval_results = run_retrieval(state, &request.prompt, 5, &pinned_ids)
-        .await
-        .unwrap_or_default();
 
-    let should_use_notes = should_use_retrieved_notes(&request.prompt, &retrieval_results)
-        == RetrievalDecisionReason::UseRetrievedNotes;
-    let mut context_notes = Vec::new();
-    let mut note_contexts = Vec::new();
-
-    if should_use_notes {
-        let chunk_enabled = {
-            let retrieval = state.retrieval_service.read().await;
-            retrieval.get_config().chunk_retrieval_enabled
+    #[test]
+    fn test_prompt_request_from_tile_preserves_twin_settings() {
+        let tile = PromptTile {
+            context_mode: ContextMode::Twin,
+            twin_answer_mode: TwinAnswerMode::Simulation,
+            twin_context_policy: Some("approved_plus_relevant_candidates".to_string()),
+            twin_llm_provider: Some("ollama".to_string()),
+            ..build_tile("tile-1", "Prompt", "openai/gpt-4", "Response", None, None)
         };
 
-        if chunk_enabled {
-            let chunks = {
-                let retrieval = state.retrieval_service.read().await;
-                let chunk_index = state.chunk_index.read().await;
-                let graph = state.graph_index.read().await;
-                let priority = state.priority_service.read().await;
-                let token_budget = retrieval.get_config().default_token_budget;
-                retrieval
-                    .retrieve_chunks(
-                        &chunk_index,
-                        &graph,
-                        &priority,
-                        &request.prompt,
-                        token_budget,
-                        &pinned_ids,
-                    )
-                    .unwrap_or_default()
-            };
-
-            if !chunks.is_empty() {
-                let mut seen_notes: HashSet<String> = HashSet::new();
-                for chunk in &chunks {
-                    note_contexts.push((
-                        chunk.parent_note_id.clone(),
-                        chunk.parent_title.clone(),
-                        chunk.text.clone(),
-                    ));
-                    if seen_notes.insert(chunk.parent_note_id.clone()) {
-                        context_notes.push(TileContextNote {
-                            id: chunk.parent_note_id.clone(),
-                            title: chunk.parent_title.clone(),
-                            snippet: truncate_note_context_content(&chunk.text, 200),
-                            score: chunk.search_score,
-                            pinned: pinned_ids.contains(&chunk.parent_note_id),
-                        });
-                    }
-                }
-            }
-        }
-
-        if note_contexts.is_empty() {
-            note_contexts = fetch_note_contexts(state, &retrieval_results).await;
-            let found_ids: HashSet<&str> =
-                note_contexts.iter().map(|(id, _, _)| id.as_str()).collect();
-            for r in &retrieval_results {
-                if found_ids.contains(r.note.id.as_str()) {
-                    context_notes.push(TileContextNote {
-                        id: r.note.id.clone(),
-                        title: r.note.title.clone(),
-                        snippet: r.snippet.clone(),
-                        score: r.score,
-                        pinned: pinned_ids.contains(&r.note.id),
-                    });
-                }
-            }
-        }
-    }
-
-    let constitution_query =
-        decision_context_query(&request.prompt, request.decision_metadata.as_ref());
-    let (
-        setup,
-        approved_twin_records,
-        candidate_twin_records,
-        constitution_items,
-        action_gaps,
-        decision_cases,
-    ) = {
-        let mut twin_store = state.twin_store.write().await;
-        let setup = twin_store
-            .get_constitution_setup()
-            .map_err(|error| error.to_string())?;
-        validate_twin_identity_for_answer_mode(&setup, &request.twin_answer_mode)?;
-        let (approved, candidate) = twin_store
-            .select_context_records(&request.prompt)
-            .map_err(|error| error.to_string())?;
-        let (constitution_items, action_gaps) = twin_store
-            .select_constitution_context(&constitution_query)
-            .map_err(|error| error.to_string())?;
-        let decision_cases = twin_store
-            .select_decision_cases(&constitution_query, None, MAX_TWIN_CASE_CONTEXT)
-            .map_err(|error| error.to_string())?;
-        (
-            setup,
-            approved,
-            candidate,
-            constitution_items,
-            action_gaps,
-            decision_cases,
-        )
-    };
-
-    let selection = apply_twin_context_budget(
-        decision_cases,
-        constitution_items,
-        approved_twin_records,
-        candidate_twin_records,
-        action_gaps,
-        note_contexts,
-        TWIN_CONTEXT_TOKEN_BUDGET,
-    );
-    let decision_case_ids = selection
-        .cases
-        .iter()
-        .map(|episode| episode.id.clone())
-        .collect::<Vec<_>>();
-
-    let twin_prompt = build_twin_context_prompt(
-        &setup,
-        &selection.cases,
-        &selection.notes,
-        &selection.approved,
-        &selection.candidates,
-        &selection.constitution_items,
-        &selection.action_gaps,
-        &request.twin_answer_mode,
-        &request.prompt_type,
-        request.decision_metadata.as_ref(),
-    );
-    let system_prompt = match &request.system_prompt {
-        Some(user_sp) if !user_sp.is_empty() => format!("{}\n\n{}", twin_prompt, user_sp),
-        _ => twin_prompt.clone(),
-    };
-
-    Ok(ResolvedPromptContext {
-        messages,
-        context_notes,
-        approved_twin_records: selection.approved,
-        candidate_twin_records: selection.candidates,
-        constitution_items: selection.constitution_items,
-        action_gaps: selection.action_gaps,
-        system_prompt: Some(system_prompt),
-        twin_context_prompt: Some(twin_prompt),
-        context_version: Some(TWIN_CONTEXT_VERSION.to_string()),
-        decision_case_ids,
-    })
-}
-
-/// Fetch full note content for retrieval results, returning (id, title, truncated_content) tuples.
-/// Skips notes that can't be read from the store. Called by both the semantic and twin note-level paths.
-async fn fetch_note_contexts(
-    state: &AppState,
-    results: &[RetrievalResult],
-) -> Vec<(String, String, String)> {
-    let store = state.knowledge_store.read().await;
-    results
-        .iter()
-        .filter_map(|r| {
-            store.get_note(&r.note.id).ok().map(|note| {
-                let truncated = truncate_note_context_content(&note.content, 1500);
-                (note.id.clone(), note.title.clone(), truncated)
-            })
-        })
-        .collect()
-}
-
-/// Fall back to note-level context when chunk retrieval is disabled or returns nothing.
-async fn resolve_note_level_context(
-    state: &AppState,
-    messages: Vec<ChatMessage>,
-    retrieval_results: &[RetrievalResult],
-    pinned_ids: &[String],
-    user_system_prompt: &Option<String>,
-) -> Result<ResolvedPromptContext, String> {
-    let note_contexts = fetch_note_contexts(state, retrieval_results).await;
-
-    let context_notes: Vec<TileContextNote> = retrieval_results
-        .iter()
-        .map(|r| TileContextNote {
-            id: r.note.id.clone(),
-            title: r.note.title.clone(),
-            snippet: r.snippet.clone(),
-            score: r.score,
-            pinned: pinned_ids.contains(&r.note.id),
-        })
-        .collect();
-
-    let note_prompt = build_note_context_prompt(&note_contexts);
-    let system_prompt = match user_system_prompt {
-        Some(user_sp) if !user_sp.is_empty() => format!("{}\n\n{}", note_prompt, user_sp),
-        _ => note_prompt,
-    };
-
-    Ok(ResolvedPromptContext {
-        messages,
-        context_notes,
-        approved_twin_records: Vec::new(),
-        candidate_twin_records: Vec::new(),
-        constitution_items: Vec::new(),
-        action_gaps: Vec::new(),
-        system_prompt: Some(system_prompt),
-        twin_context_prompt: None,
-        context_version: None,
-        decision_case_ids: Vec::new(),
-    })
-}
-
-fn build_canvas_messages(
-    session: &CanvasSession,
-    request: &PromptRequest,
-) -> Result<Vec<ChatMessage>, String> {
-    match request.context_mode {
-        ContextMode::FullHistory => build_full_history_messages(session, request),
-        ContextMode::Compact => build_compact_history_messages(session, request),
-        _ => Ok(vec![ChatMessage {
-            role: "user".to_string(),
-            content: request.prompt.clone(),
-        }]),
-    }
-}
-
-fn build_full_history_messages(
-    session: &CanvasSession,
-    request: &PromptRequest,
-) -> Result<Vec<ChatMessage>, String> {
-    let turns = build_selected_parent_chain(session, request)?;
-    let mut messages = Vec::with_capacity((turns.len() * 2) + 1);
-
-    for turn in turns {
-        messages.push(ChatMessage {
-            role: "user".to_string(),
-            content: turn.prompt,
-        });
-        messages.push(ChatMessage {
-            role: "assistant".to_string(),
-            content: turn.response,
-        });
-    }
-
-    messages.push(ChatMessage {
-        role: "user".to_string(),
-        content: request.prompt.clone(),
-    });
-
-    Ok(messages)
-}
-
-fn build_compact_history_messages(
-    session: &CanvasSession,
-    request: &PromptRequest,
-) -> Result<Vec<ChatMessage>, String> {
-    let turns = build_selected_parent_chain(session, request)?;
-    let mut messages = Vec::new();
-
-    if turns.len() > COMPACT_HISTORY_RECENT_TURNS {
-        let split_at = turns.len() - COMPACT_HISTORY_RECENT_TURNS;
-        let summary = build_compact_history_summary(&turns[..split_at]);
-        messages.push(ChatMessage {
-            role: "user".to_string(),
-            content: summary,
-        });
-
-        for turn in &turns[split_at..] {
-            messages.push(ChatMessage {
-                role: "user".to_string(),
-                content: turn.prompt.clone(),
-            });
-            messages.push(ChatMessage {
-                role: "assistant".to_string(),
-                content: turn.response.clone(),
-            });
-        }
-    } else {
-        for turn in turns {
-            messages.push(ChatMessage {
-                role: "user".to_string(),
-                content: turn.prompt,
-            });
-            messages.push(ChatMessage {
-                role: "assistant".to_string(),
-                content: turn.response,
-            });
-        }
-    }
-
-    messages.push(ChatMessage {
-        role: "user".to_string(),
-        content: request.prompt.clone(),
-    });
-
-    Ok(messages)
-}
-
-fn build_selected_parent_chain(
-    session: &CanvasSession,
-    request: &PromptRequest,
-) -> Result<Vec<ConversationTurn>, String> {
-    let mut tile_id = request
-        .parent_tile_id
-        .clone()
-        .ok_or_else(|| "Context mode requires a parent tile".to_string())?;
-    let mut model_id = request
-        .parent_model_id
-        .clone()
-        .ok_or_else(|| "Context mode requires a parent model".to_string())?;
-    let mut visited = HashSet::new();
-    let mut turns = Vec::new();
-
-    loop {
-        let visit_key = format!("{}::{}", tile_id, model_id);
-        if !visited.insert(visit_key) {
-            return Err("Detected a cycle while reconstructing canvas history".to_string());
-        }
-
-        let tile = session
-            .prompt_tiles
-            .iter()
-            .find(|t| t.id == tile_id)
-            .ok_or_else(|| format!("Parent tile not found in session: {}", tile_id))?;
-        let response = tile.responses.get(&model_id).ok_or_else(|| {
-            format!(
-                "Parent response not found for tile {} and model {}",
-                tile_id, model_id
-            )
-        })?;
-
-        turns.push(ConversationTurn {
-            prompt: tile.prompt.clone(),
-            response: response.content.clone(),
-            model_id: model_id.clone(),
-        });
-
-        match (&tile.parent_tile_id, &tile.parent_model_id) {
-            (Some(next_tile_id), Some(next_model_id)) => {
-                tile_id = next_tile_id.clone();
-                model_id = next_model_id.clone();
-            }
-            (None, None) => break,
-            _ => {
-                return Err(format!(
-                    "Incomplete parent linkage for tile {} while reconstructing history",
-                    tile.id
-                ))
-            }
-        }
-    }
-
-    turns.reverse();
-    Ok(turns)
-}
-
-fn build_compact_history_summary(turns: &[ConversationTurn]) -> String {
-    let mut summary = String::from("Conversation summary before the most recent turns:\n");
-
-    for (index, turn) in turns.iter().enumerate() {
-        summary.push_str(&format!(
-            "\nTurn {}:\nUser: {}\nAssistant ({}): {}\n",
-            index + 1,
-            truncate_for_compact_history(&turn.prompt),
-            turn.model_id,
-            truncate_for_compact_history(&turn.response),
-        ));
-    }
-
-    summary
-}
-
-fn truncate_for_compact_history(content: &str) -> String {
-    if content.chars().count() <= COMPACT_HISTORY_EXCERPT_CHARS {
-        return content.to_string();
-    }
-
-    let mut truncated = content
-        .chars()
-        .take(COMPACT_HISTORY_EXCERPT_CHARS)
-        .collect::<String>();
-    truncated.push_str("...");
-    truncated
-}
-
-/// Build a system prompt that includes retrieved note context.
-/// Used by send_prompt when context_mode is Semantic.
-fn build_chunk_context_prompt(chunks: &[ChunkResult]) -> String {
-    let mut prompt = String::from(
-        "You are a helpful knowledge assistant for the user's personal note-taking system (Grafyn). \
-         Answer questions using the context from the user's notes below. \
-         Reference specific notes by title when citing information. \
-         If the notes don't contain relevant information, say so honestly.\n\n",
-    );
-
-    if chunks.is_empty() {
-        prompt.push_str("No relevant notes were found for this query.\n");
-        return prompt;
-    }
-
-    // Group chunks by parent note, preserving insertion order
-    let mut note_order: Vec<String> = Vec::new();
-    let mut note_map: HashMap<String, (String, Vec<&str>)> = HashMap::new();
-
-    for chunk in chunks {
-        let entry = note_map
-            .entry(chunk.parent_note_id.clone())
-            .or_insert_with(|| {
-                note_order.push(chunk.parent_note_id.clone());
-                (chunk.parent_title.clone(), Vec::new())
-            });
-        entry.1.push(&chunk.text);
-    }
-
-    prompt.push_str("## Relevant Notes\n\n");
-    for note_id in &note_order {
-        if let Some((title, texts)) = note_map.get(note_id) {
-            prompt.push_str(&format!("### {} (id: {})\n", title, note_id));
-            for text in texts {
-                prompt.push_str(text);
-                prompt.push_str("\n\n");
-            }
-        }
-    }
-
-    prompt
-}
-
-fn build_note_context_prompt(notes: &[(String, String, String)]) -> String {
-    let mut prompt = String::from(
-        "You are a helpful knowledge assistant for the user's personal note-taking system (Grafyn). \
-         Answer questions using the context from the user's notes below. \
-         Reference specific notes by title when citing information. \
-         If the notes don't contain relevant information, say so honestly.\n\n",
-    );
+        let request = prompt_request_from_tile(&tile, vec!["openai/gpt-4".to_string()], 0.7);
 
-    if notes.is_empty() {
-        prompt.push_str("No relevant notes were found for this query.\n");
-    } else {
-        prompt.push_str("## Relevant Notes\n\n");
-        for (id, title, content) in notes {
-            prompt.push_str(&format!("### {} (id: {})\n{}\n\n", title, id, content));
-        }
+        assert_eq!(request.context_mode, ContextMode::Twin);
+        assert_eq!(request.twin_answer_mode, TwinAnswerMode::Simulation);
+        assert_eq!(
+            request.twin_context_policy.as_deref(),
+            Some("approved_plus_relevant_candidates")
+        );
+        assert_eq!(request.twin_llm_provider.as_deref(), Some("ollama"));
     }
 
-    prompt
-}
-
-/// Rough token estimate matching the chunk-index convention (words * 4/3).
-fn estimate_tokens(text: &str) -> usize {
-    text.split_whitespace().count() * 4 / 3 + 1
-}
+    #[test]
+    fn test_classify_streamed_model_response_rejects_empty_content() {
+        let update =
+            classify_streamed_model_response("openai/gpt-4".to_string(), "   \n\t".to_string());
 
-/// Render one past decision episode as a verbatim behavioral case.
-fn format_decision_case(episode: &DecisionEpisode) -> String {
-    let mut case = format!("### Past decision: {}\n", episode.decision.trim());
-    if !episode.options.is_empty() {
-        case.push_str(&format!("- Options: {}\n", episode.options.join(" | ")));
-    }
-    if let Some(chosen) = episode.chosen_option.as_deref() {
-        case.push_str(&format!("- Chose: {}\n", chosen.trim()));
-    }
-    if let Some(leaning) = episode.initial_leaning.as_deref() {
-        if !leaning.trim().is_empty() {
-            case.push_str(&format!("- Initial leaning: {}\n", leaning.trim()));
-        }
-    }
-    if let Some(outcome) = episode.outcome.as_deref() {
-        if !outcome.trim().is_empty() {
-            case.push_str(&format!(
-                "- Outcome: {}\n",
-                truncate_note_context_content(outcome.trim(), TWIN_CASE_FIELD_MAX_CHARS)
-            ));
-        }
-    }
-    if let Some(lesson) = episode.lesson.as_deref() {
-        if !lesson.trim().is_empty() {
-            case.push_str(&format!(
-                "- Lesson (verbatim): {}\n",
-                truncate_note_context_content(lesson.trim(), TWIN_CASE_FIELD_MAX_CHARS)
-            ));
-        }
-    }
-    if let Some(note) = episode.correction_note.as_deref() {
-        if !note.trim().is_empty() {
-            case.push_str(&format!(
-                "- Correction note (recorded when an earlier sealed twin guess missed): {}\n",
-                truncate_note_context_content(note.trim(), TWIN_CASE_CORRECTION_MAX_CHARS)
-            ));
-        }
+        assert_eq!(update.0, "openai/gpt-4");
+        assert_eq!(update.1, "");
+        assert_eq!(update.2, ResponseStatus::Error);
+        assert_eq!(update.3.as_deref(), Some(EMPTY_MODEL_RESPONSE_ERROR));
     }
-    case.push('\n');
-    case
-}
-
-struct TwinContextSelection {
-    cases: Vec<DecisionEpisode>,
-    constitution_items: Vec<ConstitutionItem>,
-    approved: Vec<TwinContextRecord>,
-    candidates: Vec<TwinContextRecord>,
-    action_gaps: Vec<ActionGap>,
-    notes: Vec<(String, String, String)>,
-}
-
-/// Greedy-fill the variable twin context sections into a hard token budget,
-/// in priority order: cases > constitution > approved records > candidate
-/// records > action gaps > evidence notes. Fixed scaffolding (operating
-/// contract, identity, answer instructions, decision metadata) sits outside
-/// the budget.
-#[allow(clippy::too_many_arguments)]
-fn apply_twin_context_budget(
-    cases: Vec<DecisionEpisode>,
-    constitution_items: Vec<ConstitutionItem>,
-    approved: Vec<TwinContextRecord>,
-    candidates: Vec<TwinContextRecord>,
-    action_gaps: Vec<ActionGap>,
-    notes: Vec<(String, String, String)>,
-    budget: usize,
-) -> TwinContextSelection {
-    let mut remaining = budget as isize;
-    let mut take_within_budget = move |cost: usize| -> bool {
-        if remaining - cost as isize >= 0 {
-            remaining -= cost as isize;
-            true
-        } else {
-            false
-        }
-    };
 
-    let cases = cases
-        .into_iter()
-        .filter(|episode| take_within_budget(estimate_tokens(&format_decision_case(episode))))
-        .collect();
-    let constitution_items = constitution_items
-        .into_iter()
-        .filter(|item| take_within_budget(estimate_tokens(&format_constitution_item(item))))
-        .collect();
-    let approved = approved
-        .into_iter()
-        .filter(|record| take_within_budget(estimate_tokens(&format_twin_record(record))))
-        .collect();
-    let candidates = candidates
-        .into_iter()
-        .filter(|record| take_within_budget(estimate_tokens(&format_twin_record(record))))
-        .collect();
-    let action_gaps = action_gaps
-        .into_iter()
-        .filter(|gap| take_within_budget(estimate_tokens(&format_action_gap(gap))))
-        .collect();
-    let notes = notes
-        .into_iter()
-        .filter(|(_, title, content)| {
-            take_within_budget(estimate_tokens(title) + estimate_tokens(content))
-        })
-        .collect();
-
-    TwinContextSelection {
-        cases,
-        constitution_items,
-        approved,
-        candidates,
-        action_gaps,
-        notes,
-    }
-}
-
-/// User message for the hidden sealed-prediction call. With a configured
-/// Twin Identity the framing is immersed first person; the fallback is a
-/// neutral decision-support instruction. Disclosure language lives in the
-/// app UI, never in model-facing prompts.
-fn build_twin_prediction_user_message(
-    setup: &ConstitutionSetup,
-    decision: &str,
-    options: &[String],
-    stakes: Option<&str>,
-) -> String {
-    let immersed = has_twin_identity(setup);
-    let mut message = String::new();
-    if immersed {
-        let name = setup
-            .twin_name
-            .as_deref()
-            .unwrap_or_default()
-            .trim()
-            .to_string();
-        message.push_str(&format!(
-            "I am {}. The decision in front of me: {}\n",
-            name,
-            decision.trim()
-        ));
-    } else {
-        message.push_str(&format!(
-            "Decision under consideration: {}\n",
-            decision.trim()
-        ));
-    }
-    if let Some(stakes) = stakes {
-        if !stakes.trim().is_empty() {
-            message.push_str(&format!("Stakes: {}\n", stakes.trim()));
-        }
-    }
-    message.push_str("My options:\n");
-    for (index, option) in options.iter().enumerate() {
-        message.push_str(&format!("{}. {}\n", index + 1, option));
-    }
-    if immersed {
-        message.push_str(
-            "\nWhich option do I choose? I answer with only this JSON object and nothing else:\n",
-        );
-    } else {
-        message.push_str(
-            "\nGiven the context above, determine which option best fits this decision-maker's \
-             documented values, constitution, and past decisions. Respond with only this JSON \
-             object and nothing else:\n",
-        );
-    }
-    message.push_str(
-        "{\"predicted_option\": \"<option text>\", \"option_index\": <option number from the list above>, \
-         \"confidence\": <0.0 to 1.0>, \"rationale\": \"<one or two sentences>\"}",
-    );
-    message
-}
-
-/// The hidden sealed-prediction call. Runs in its own spawned task, never
-/// touches the window, and never blocks the visible streaming flow. Lock
-/// discipline: collect owned data under the store lock, drop it, await the
-/// provider, then re-lock to attach.
-#[allow(clippy::too_many_arguments)]
-async fn run_sealed_twin_prediction(
-    twin_store: Arc<RwLock<TwinStore>>,
-    openrouter: Arc<RwLock<OpenRouterService>>,
-    ollama: Arc<RwLock<OllamaService>>,
-    provider_route: ModelProviderRoute,
-    prediction_model: String,
-    episode_id: String,
-    prompt: String,
-    decision: String,
-    options: Vec<String>,
-    stakes: Option<String>,
-    twin_context_prompt: Option<String>,
-    context_version: String,
-    decision_metadata: Option<DecisionPromptMetadata>,
-) {
-    let built = {
-        let mut store = twin_store.write().await;
-        let setup = match store.get_constitution_setup() {
-            Ok(setup) => setup,
-            Err(error) => {
-                log::warn!("Sealed prediction setup load failed for {episode_id}: {error}");
-                let _ = store.mark_twin_prediction_failed(&episode_id);
-                return;
-            }
-        };
-
-        let system_prompt = if let Some(prompt) = twin_context_prompt {
-            prompt
-        } else {
-            // Non-Twin-context decision tile: build a twin-only context on
-            // the spot so predictions cover every decision, not just
-            // Twin-mode ones (skipping them would bias the eval sample).
-            let query = decision_context_query(&prompt, decision_metadata.as_ref());
-            let selections =
-                store
-                    .select_context_records(&prompt)
-                    .and_then(|(approved, candidates)| {
-                        let (constitution_items, action_gaps) =
-                            store.select_constitution_context(&query)?;
-                        let cases = store.select_decision_cases(
-                            &query,
-                            Some(&episode_id),
-                            MAX_TWIN_CASE_CONTEXT,
-                        )?;
-                        Ok((approved, candidates, constitution_items, action_gaps, cases))
-                    });
-            match selections {
-                Ok((approved, candidates, constitution_items, action_gaps, cases)) => {
-                    let selection = apply_twin_context_budget(
-                        cases,
-                        constitution_items,
-                        approved,
-                        candidates,
-                        action_gaps,
-                        Vec::new(),
-                        TWIN_CONTEXT_TOKEN_BUDGET,
-                    );
-                    let answer_mode = if has_twin_identity(&setup) {
-                        TwinAnswerMode::Simulation
-                    } else {
-                        TwinAnswerMode::Advisor
-                    };
-                    build_twin_context_prompt(
-                        &setup,
-                        &selection.cases,
-                        &selection.notes,
-                        &selection.approved,
-                        &selection.candidates,
-                        &selection.constitution_items,
-                        &selection.action_gaps,
-                        &answer_mode,
-                        &PromptType::Decision,
-                        decision_metadata.as_ref(),
-                    )
-                }
-                Err(error) => {
-                    log::warn!("Sealed prediction context build failed for {episode_id}: {error}");
-                    let _ = store.mark_twin_prediction_failed(&episode_id);
-                    return;
-                }
-            }
-        };
-
-        let user_message =
-            build_twin_prediction_user_message(&setup, &decision, &options, stakes.as_deref());
-        (system_prompt, user_message)
-    };
-    let (system_prompt, user_message) = built;
-
-    let messages = vec![ChatMessage {
-        role: "user".to_string(),
-        content: user_message,
-    }];
-    let result = match provider_route {
-        ModelProviderRoute::Ollama => {
-            let ollama = ollama.read().await;
-            ollama
-                .chat(&prediction_model, messages, Some(&system_prompt), Some(0.2))
-                .await
-        }
-        ModelProviderRoute::OpenRouter => {
-            let openrouter = openrouter.read().await;
-            openrouter
-                .chat(
-                    &prediction_model,
-                    messages,
-                    Some(&system_prompt),
-                    Some(0.2),
-                    Some(600),
-                    Some("none"),
-                    false,
-                    0,
-                )
-                .await
-        }
-    };
-
-    match result {
-        Ok(raw) => {
-            let draft = parse_twin_prediction(&raw, &options);
-            let mut store = twin_store.write().await;
-            if let Err(error) = store.attach_twin_prediction(
-                &episode_id,
-                draft,
-                &prediction_model,
-                &context_version,
-            ) {
-                log::warn!("Failed to seal twin prediction for {episode_id}: {error}");
-            }
-        }
-        Err(error) => {
-            log::warn!("Sealed twin prediction call failed for {episode_id}: {error}");
-            let mut store = twin_store.write().await;
-            let _ = store.mark_twin_prediction_failed(&episode_id);
-        }
-    }
-}
-
-#[allow(clippy::too_many_arguments)]
-fn build_twin_context_prompt(
-    setup: &ConstitutionSetup,
-    decision_cases: &[DecisionEpisode],
-    notes: &[(String, String, String)],
-    approved_records: &[TwinContextRecord],
-    candidate_records: &[TwinContextRecord],
-    constitution_items: &[ConstitutionItem],
-    action_gaps: &[ActionGap],
-    answer_mode: &TwinAnswerMode,
-    prompt_type: &PromptType,
-    decision_metadata: Option<&DecisionPromptMetadata>,
-) -> String {
-    let mut prompt = String::from(
-        "## Twin Operating Contract\n\n\
-         You are Grafyn's native RAG twin mode. Use only the provided Constitution, action gaps, vault evidence, and user-reviewed twin records as context. \
-         Keep uncertainty visible. Do not use evidence to justify a preselected answer; use evidence to constrain the answer before choosing. \
-         Use interviewee answers as evidence about the interviewee, institution, product, or research context. \
-         Use interviewer questions and follow-ups as evidence about the user's reasoning pattern. \
-         Keep these roles separate.\n\n",
-    );
-
-    prompt.push_str(&format_twin_identity_section(setup, answer_mode));
-
-    prompt.push_str("## Past Decision Cases\n\n");
-    if decision_cases.is_empty() {
-        prompt.push_str("No similar past decisions were selected for this prompt.\n\n");
-    } else {
-        prompt.push_str(
-            "These are this person's actual past decisions, verbatim. \
-             Weight them above abstracted records: they show how tradeoffs were really made.\n",
-        );
-        for episode in decision_cases {
-            prompt.push_str(&format_decision_case(episode));
-        }
-    }
-
-    let reviewed_constitution = constitution_items
-        .iter()
-        .filter(|item| {
-            matches!(
-                item.status,
-                crate::models::twin::ConstitutionStatus::Active
-                    | crate::models::twin::ConstitutionStatus::Softened
-            )
-        })
-        .collect::<Vec<_>>();
-    let candidate_constitution = constitution_items
-        .iter()
-        .filter(|item| item.status == crate::models::twin::ConstitutionStatus::Candidate)
-        .collect::<Vec<_>>();
-
-    prompt.push_str("## Reviewed Constitution\n\n");
-    if reviewed_constitution.is_empty() {
-        prompt.push_str("No reviewed Constitution items were selected for this prompt.\n\n");
-    } else {
-        prompt.push_str("These are the governing principles for the answer. Apply them before weighing evidence.\n");
-        for item in reviewed_constitution {
-            prompt.push_str(&format_constitution_item(item));
-        }
-        prompt.push('\n');
-    }
-
-    prompt.push_str("## Action Gap Risks\n\n");
-    if action_gaps.is_empty() {
-        prompt
-            .push_str("No relevant stated-intention vs revealed-behavior gaps were selected.\n\n");
-    } else {
-        prompt.push_str("Use these as risk checks, not accusations. Ask whether the same gap could affect this answer.\n");
-        for gap in action_gaps {
-            prompt.push_str(&format_action_gap(gap));
-        }
-        prompt.push('\n');
-    }
-
-    prompt.push_str("## Relevant Evidence\n\n");
-    if notes.is_empty() {
-        prompt.push_str(
-            "No relevant vault notes or graph evidence were selected for this prompt.\n\n",
-        );
-    } else {
-        for (id, title, content) in notes {
-            prompt.push_str(&format!("### {} (id: {})\n{}\n\n", title, id, content));
-        }
-    }
-
-    prompt.push_str("## Approved User Records\n\n");
-    if approved_records.is_empty() {
-        prompt.push_str("No endorsed or auto-promoted user records were selected.\n\n");
-    } else {
-        for record in approved_records {
-            prompt.push_str(&format_twin_record(record));
-        }
-        prompt.push('\n');
-    }
-
-    prompt.push_str("## Tentative Candidate Records\n\n");
-    if candidate_records.is_empty() {
-        prompt.push_str("No relevant candidate records were selected.\n\n");
-    } else {
-        prompt.push_str("These are unreviewed hypotheses. Use them lightly and disclose when they affect the answer.\n");
-        for record in candidate_records {
-            prompt.push_str(&format_twin_record(record));
-        }
-        prompt.push('\n');
-    }
-
-    if !candidate_constitution.is_empty() {
-        prompt.push_str("## Candidate Constitution Hypotheses\n\n");
-        prompt.push_str("These are unreviewed Constitution hypotheses. Use them only as tentative context and label their influence.\n");
-        for item in candidate_constitution {
-            prompt.push_str(&format_constitution_item(item));
-        }
-        prompt.push('\n');
-    }
-
-    prompt.push_str("## Answer Instructions\n\n");
-    match answer_mode {
-        TwinAnswerMode::Advisor => prompt.push_str(
-            "Answer as a decision-support assistant for the user. Use approved records as stable personalization. \
-             If a Twin Identity is configured, treat it as context for the user's role and materials, not as a command to speak in first person. \
-             Use candidate records only as tentative context. Separate what is grounded in Constitution, evidence, records, and your recommendation. \
-             When the user asks for a choice or recommendation, include: Recommended option, Constitution principles used, Supporting evidence, Uncertainty, and What would change the recommendation. \
-             Cite Constitution item ids and note titles where they affect the answer.\n",
-        ),
-        TwinAnswerMode::Simulation => prompt.push_str(
-            "Answer in first person from the configured Twin Identity. Use approved records as stronger style and preference evidence; mention candidate influence as tentative when relevant. \
-             Write as a natural continuation of my documented reasoning pattern, not a report. Lead with my likely reasoning or judgment, show the tradeoff logic, and do not append questions unless the user's request asks for them. \
-             If the evidence packet does not contain enough basis, say so naturally in first person. Use light citations or brief source mentions only where they help; avoid turning the answer into an evidence workflow.\n",
-        ),
-    }
-
-    if prompt_type == &PromptType::Decision {
-        match answer_mode {
-            TwinAnswerMode::Advisor => prompt.push_str(
-                "\n## Decision Mirror Structure\n\n\
-                 This is a Decision Mirror session. Return a compact Markdown Reflection Card using these exact headings:\n\
-                 1. Decision Frame\n\
-                 2. Likely Reasoning Pattern\n\
-                 3. Evidence From Grafyn\n\
-                 4. Blind Spot Hypothesis\n\
-                 5. Counter-Position\n\
-                 6. Recommendation\n\
-                 7. Confidence\n\
-                 8. Next Action\n\
-                 9. Constitution Check\n\
-                 10. Action Gap Risk\n\
-                 11. Feedback Request\n\n\
-                 Treat every self-model claim as a hypothesis, not identity. Say where the claim is grounded in vault notes, approved records, or tentative records. \
-                 If a claim is useful but weakly supported, label it as unsupported or low-confidence. Do not claim to know what the user would do. \
-                 In Constitution Check, separate stated values, revealed behavior, taste, somatic signal, and constraints. In Action Gap Risk, state whether past intention-action gaps could change the next step. \
-                 Recommendation must be derived after the Constitution Check and Evidence From Grafyn sections, not before them.\n",
-            ),
-            TwinAnswerMode::Simulation => {}
-        }
-
-        if let Some(metadata) = decision_metadata {
-            prompt.push_str("\n## Decision Metadata\n\n");
-            prompt.push_str(&format!("Decision: {}\n", metadata.decision));
-            if !metadata.options.is_empty() {
-                prompt.push_str("Options:\n");
-                for option in &metadata.options {
-                    prompt.push_str(&format!("- {}\n", option));
-                }
-            }
-            if let Some(stakes) = metadata.stakes.as_deref().filter(|value| !value.is_empty()) {
-                prompt.push_str(&format!("Stakes: {}\n", stakes));
-            }
-            if let Some(leaning) = metadata
-                .initial_leaning
-                .as_deref()
-                .filter(|value| !value.is_empty())
-            {
-                prompt.push_str(&format!("Initial leaning: {}\n", leaning));
-            }
-            if let Some(review_date) = metadata
-                .review_date
-                .as_deref()
-                .filter(|value| !value.is_empty())
-            {
-                prompt.push_str(&format!("Follow-up review date: {}\n", review_date));
-            }
-            prompt.push('\n');
-        }
-    }
-
-    prompt
-}
-
-fn validate_twin_identity_for_answer_mode(
-    setup: &ConstitutionSetup,
-    answer_mode: &TwinAnswerMode,
-) -> Result<(), String> {
-    if answer_mode != &TwinAnswerMode::Simulation {
-        return Ok(());
-    }
-
-    if has_twin_identity(setup) {
-        Ok(())
-    } else {
-        Err("Twin Identity requires Name and Role / context before Simulation can run.".to_string())
-    }
-}
-
-fn has_twin_identity(setup: &ConstitutionSetup) -> bool {
-    setup
-        .twin_name
-        .as_deref()
-        .is_some_and(|value| !value.trim().is_empty())
-        && setup
-            .twin_role
-            .as_deref()
-            .is_some_and(|value| !value.trim().is_empty())
-}
-
-fn format_twin_identity_section(setup: &ConstitutionSetup, answer_mode: &TwinAnswerMode) -> String {
-    let mut section = String::from("## Twin Identity\n\n");
-    let name = setup.twin_name.as_deref().map(str::trim).unwrap_or("");
-    let role = setup.twin_role.as_deref().map(str::trim).unwrap_or("");
-
-    if name.is_empty() || role.is_empty() {
-        section.push_str("No Twin Identity is configured for this prompt.\n\n");
-        return section;
-    }
-
-    match answer_mode {
-        TwinAnswerMode::Simulation => {
-            section.push_str(&format!("I am {}.\n", name));
-            section.push_str(&format!("My role/context is {}.\n", role));
-            section.push_str("I reason from supplied Knowledge materials, reviewed Constitution, selected evidence, and reviewed twin records.\n");
-            section.push_str("I speak in first person. I do not explain myself as an outside analyst. Continue my documented reasoning pattern.\n");
-            section.push_str("If the evidence packet does not contain enough basis, I say so naturally: I do not recall that specifically, I would need more details, or based on what I have done before.\n");
-        }
-        TwinAnswerMode::Advisor => {
-            section.push_str(&format!("Twin name: {}\n", name));
-            section.push_str(&format!("Role/context: {}\n", role));
-            section.push_str("Use this identity as context for role, materials, and decision frame while answering as an advisor.\n");
-        }
-    }
-
-    let boundaries = setup
-        .source_boundaries
-        .iter()
-        .map(|boundary| boundary.trim())
-        .filter(|boundary| !boundary.is_empty())
-        .collect::<Vec<_>>();
-    if !boundaries.is_empty() {
-        section.push_str("Source boundaries:\n");
-        for boundary in boundaries {
-            section.push_str(&format!("- {}\n", boundary));
-        }
-    }
-
-    section.push('\n');
-    section
-}
-
-fn format_twin_record(record: &TwinContextRecord) -> String {
-    format!(
-        "- [{:?}; {:?}; confidence {:.2}; evidence {}] {}\n",
-        record.kind,
-        record.promotion_state,
-        record.confidence,
-        record.evidence_count,
-        record.content
-    )
-}
-
-fn format_constitution_item(item: &ConstitutionItem) -> String {
-    let source_labels = constitution_source_labels(item);
-    format!(
-        "- [id {}; dimension {}; status {:?}; confidence {:.2}; priority {:.2}; evidence {}; sources: {}] {}\n",
-        item.id,
-        item.dimension,
-        item.status,
-        item.confidence,
-        item.priority,
-        item.evidence_refs.len(),
-        source_labels,
-        item.claim
-    )
-}
-
-fn constitution_source_labels(item: &ConstitutionItem) -> String {
-    let mut labels = item
-        .evidence_refs
-        .iter()
-        .flat_map(|evidence| {
-            [
-                evidence.source_type.as_deref(),
-                evidence.source_label.as_deref(),
-                evidence.speaker_role.as_deref(),
-            ]
-        })
-        .flatten()
-        .map(str::trim)
-        .filter(|label| !label.is_empty())
-        .map(ToOwned::to_owned)
-        .collect::<Vec<_>>();
-    labels.sort();
-    labels.dedup();
-    if labels.is_empty() {
-        item.source
-            .clone()
-            .unwrap_or_else(|| "unspecified".to_string())
-    } else {
-        labels.join(", ")
-    }
-}
-
-fn format_action_gap(gap: &ActionGap) -> String {
-    format!(
-        "- [id {}; status {:?}; confidence {:.2}; evidence {}] Stated: {} | Revealed: {} | Risk: {}\n",
-        gap.id,
-        gap.status,
-        gap.confidence,
-        gap.evidence_refs.len(),
-        gap.stated_value,
-        gap.revealed_behavior,
-        gap.decision_risk
-    )
-}
-
-fn decision_context_query(
-    prompt: &str,
-    decision_metadata: Option<&DecisionPromptMetadata>,
-) -> String {
-    let mut parts = vec![prompt.to_string()];
-    if let Some(metadata) = decision_metadata {
-        parts.push(metadata.decision.clone());
-        parts.extend(metadata.options.clone());
-        if let Some(stakes) = &metadata.stakes {
-            parts.push(stakes.clone());
-        }
-        if let Some(leaning) = &metadata.initial_leaning {
-            parts.push(leaning.clone());
-        }
-    }
-    parts.join("\n")
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::models::twin::ConstitutionSetup;
-    use chrono::Utc;
-
-    fn build_response(model_id: &str, content: &str) -> ModelResponse {
-        ModelResponse {
-            id: format!("resp-{}", model_id),
-            model_id: model_id.to_string(),
-            model_name: model_id.to_string(),
-            content: content.to_string(),
-            status: ResponseStatus::Completed,
-            error: None,
-            tokens_used: None,
-            created_at: Utc::now(),
-            position: TilePosition::default(),
-        }
-    }
-
-    fn build_tile(
-        id: &str,
-        prompt: &str,
-        model_id: &str,
-        response: &str,
-        parent_tile_id: Option<&str>,
-        parent_model_id: Option<&str>,
-    ) -> PromptTile {
-        let mut responses = HashMap::new();
-        responses.insert(model_id.to_string(), build_response(model_id, response));
-
-        PromptTile {
-            id: id.to_string(),
-            prompt_type: PromptType::Standard,
-            prompt: prompt.to_string(),
-            system_prompt: None,
-            models: vec![model_id.to_string()],
-            responses,
-            position: TilePosition::default(),
-            created_at: Utc::now(),
-            context_mode: ContextMode::default(),
-            parent_tile_id: parent_tile_id.map(str::to_string),
-            parent_model_id: parent_model_id.map(str::to_string),
-            context_notes: Vec::new(),
-            approved_twin_records: Vec::new(),
-            candidate_twin_records: Vec::new(),
-            twin_answer_mode: TwinAnswerMode::default(),
-            twin_context_policy: None,
-            twin_llm_provider: None,
-            decision_metadata: None,
-            decision_episode_id: None,
-            web_search: false,
-            web_search_max_results: 5,
-            reasoning_effort: "none".to_string(),
-        }
-    }
-
-    fn build_session(tiles: Vec<PromptTile>) -> CanvasSession {
-        CanvasSession {
-            id: "session-1".to_string(),
-            title: "Canvas".to_string(),
-            description: None,
-            prompt_tiles: tiles,
-            debates: Vec::new(),
-            viewport: CanvasViewport::default(),
-            created_at: Utc::now(),
-            updated_at: Utc::now(),
-            tags: Vec::new(),
-            status: "draft".to_string(),
-            pinned_note_ids: Vec::new(),
-        }
-    }
-
-    fn build_request(
-        prompt: &str,
-        parent_tile_id: &str,
-        parent_model_id: &str,
-        context_mode: ContextMode,
-    ) -> PromptRequest {
-        PromptRequest {
-            prompt: prompt.to_string(),
-            prompt_type: PromptType::Standard,
-            system_prompt: None,
-            models: vec!["openai/gpt-4".to_string()],
-            position: None,
-            context_mode,
-            twin_answer_mode: TwinAnswerMode::default(),
-            twin_context_policy: None,
-            twin_llm_provider: None,
-            decision_metadata: None,
-            parent_tile_id: Some(parent_tile_id.to_string()),
-            parent_model_id: Some(parent_model_id.to_string()),
-            temperature: 0.7,
-            max_tokens: None,
-            web_search: false,
-            web_search_max_results: 5,
-            reasoning_effort: "none".to_string(),
-        }
-    }
-
-    fn build_root_request(prompt: &str, context_mode: ContextMode) -> PromptRequest {
-        PromptRequest {
-            prompt: prompt.to_string(),
-            prompt_type: PromptType::Standard,
-            system_prompt: None,
-            models: vec!["openai/gpt-4".to_string()],
-            position: None,
-            context_mode,
-            twin_answer_mode: TwinAnswerMode::default(),
-            twin_context_policy: None,
-            twin_llm_provider: None,
-            decision_metadata: None,
-            parent_tile_id: None,
-            parent_model_id: None,
-            temperature: 0.7,
-            max_tokens: None,
-            web_search: false,
-            web_search_max_results: 5,
-            reasoning_effort: "none".to_string(),
-        }
-    }
-
-    fn build_retrieval_result(
-        id: &str,
-        title: &str,
-        snippet: &str,
-        score: f32,
-        reasons: &[&str],
-    ) -> RetrievalResult {
-        RetrievalResult {
-            note: crate::models::note::NoteMeta {
-                id: id.to_string(),
-                title: title.to_string(),
-                relative_path: format!("{}.md", id),
-                aliases: Vec::new(),
-                status: NoteStatus::default(),
-                tags: Vec::new(),
-                created_at: Utc::now(),
-                updated_at: Utc::now(),
-                schema_version: crate::models::note::CURRENT_NOTE_SCHEMA_VERSION,
-                migration_source: None,
-                optimizer_managed: false,
-            },
-            score,
-            snippet: snippet.to_string(),
-            relevance_reasons: reasons.iter().map(|reason| reason.to_string()).collect(),
-        }
-    }
-
-    fn build_constitution_item(
-        id: &str,
-        claim: &str,
-        status: crate::models::twin::ConstitutionStatus,
-        source_type: &str,
-    ) -> ConstitutionItem {
-        ConstitutionItem {
-            id: id.to_string(),
-            claim: claim.to_string(),
-            dimension: "values".to_string(),
-            scope: vec!["general".to_string()],
-            priority: 0.8,
-            confidence: 0.82,
-            status,
-            evidence_refs: vec![crate::models::twin::EvidenceRef {
-                trace_id: format!("trace-{}", id),
-                event_id: format!("event-{}", id),
-                session_id: "session-1".to_string(),
-                tile_id: None,
-                model_id: None,
-                note: Some("Evidence note".to_string()),
-                source_type: Some(source_type.to_string()),
-                source_id: Some(format!("source-{}", id)),
-                source_label: Some("Interview question".to_string()),
-                excerpt: Some("Can you give a concrete example?".to_string()),
-                speaker_role: Some("user".to_string()),
-            }],
-            tensions: Vec::new(),
-            linked_record_ids: Vec::new(),
-            source: Some("interview_behavior_inference".to_string()),
-            created_at: Utc::now(),
-            updated_at: Utc::now(),
-        }
-    }
-
-    fn build_action_gap(id: &str) -> ActionGap {
-        ActionGap {
-            id: id.to_string(),
-            stated_value: "Protect mission alignment".to_string(),
-            revealed_behavior: "Accepts attractive adjacent projects".to_string(),
-            driver_hypothesis: Some("Funding pressure".to_string()),
-            somatic_taste_signal: Some("Prestige pull".to_string()),
-            decision_risk: "May divert faculty from core mission work".to_string(),
-            evidence_refs: Vec::new(),
-            linked_record_ids: Vec::new(),
-            confidence: 0.72,
-            status: crate::models::twin::ConstitutionStatus::Active,
-            created_at: Utc::now(),
-            updated_at: Utc::now(),
-        }
-    }
-
-    fn test_twin_identity_setup() -> ConstitutionSetup {
-        ConstitutionSetup {
-            twin_name: Some("Alex Chen".into()),
-            twin_role: Some("founder deciding from product evidence".into()),
-            source_boundaries: vec!["Use reviewed notes and uploaded interviews only.".into()],
-            ..ConstitutionSetup::default()
-        }
-    }
-
-    #[test]
-    fn test_build_note_context_prompt_with_notes() {
-        let notes = vec![
-            ("id1".into(), "Note A".into(), "Content of A".into()),
-            ("id2".into(), "Note B".into(), "Content of B".into()),
-        ];
-        let prompt = build_note_context_prompt(&notes);
-
-        assert!(prompt.contains("Note A"));
-        assert!(prompt.contains("Content of A"));
-        assert!(prompt.contains("Note B"));
-        assert!(prompt.contains("id: id1"));
-    }
-
-    #[test]
-    fn test_build_note_context_prompt_empty() {
-        let notes: Vec<(String, String, String)> = vec![];
-        let prompt = build_note_context_prompt(&notes);
-
-        assert!(prompt.contains("No relevant notes were found"));
-    }
-
-    #[test]
-    fn test_build_chunk_context_prompt_groups_by_parent() {
-        let chunks = vec![
-            ChunkResult {
-                chunk_id: "c1".into(),
-                parent_note_id: "note-a".into(),
-                parent_title: "Note A".into(),
-                text: "First paragraph of A".into(),
-                start_char: 0,
-                end_char: 20,
-                depth_score: 1.0,
-                search_score: 5.0,
-                token_estimate: 10,
-            },
-            ChunkResult {
-                chunk_id: "c2".into(),
-                parent_note_id: "note-b".into(),
-                parent_title: "Note B".into(),
-                text: "Content of B".into(),
-                start_char: 0,
-                end_char: 12,
-                depth_score: 1.0,
-                search_score: 4.0,
-                token_estimate: 8,
-            },
-            ChunkResult {
-                chunk_id: "c3".into(),
-                parent_note_id: "note-a".into(),
-                parent_title: "Note A".into(),
-                text: "Second paragraph of A".into(),
-                start_char: 21,
-                end_char: 42,
-                depth_score: 0.5,
-                search_score: 3.5,
-                token_estimate: 10,
-            },
-        ];
-        let prompt = build_chunk_context_prompt(&chunks);
-
-        // Both chunks from Note A should be under the same heading
-        assert!(prompt.contains("### Note A (id: note-a)"));
-        assert!(prompt.contains("First paragraph of A"));
-        assert!(prompt.contains("Second paragraph of A"));
-        assert!(prompt.contains("### Note B (id: note-b)"));
-        assert!(prompt.contains("Content of B"));
-        // Note A should appear before Note B (insertion order from chunks)
-        let a_pos = prompt.find("Note A").unwrap();
-        let b_pos = prompt.find("Note B").unwrap();
-        assert!(a_pos < b_pos);
-    }
-
-    #[test]
-    fn test_build_chunk_context_prompt_empty() {
-        let chunks: Vec<ChunkResult> = vec![];
-        let prompt = build_chunk_context_prompt(&chunks);
-        assert!(prompt.contains("No relevant notes were found"));
-    }
-
-    #[test]
-    fn twin_context_prompt_separates_approved_candidates_and_advisor_instructions() {
-        let approved = vec![TwinContextRecord {
-            id: "record-approved".into(),
-            kind: crate::models::twin::UserRecordKind::Preference,
-            content: "User prefers evidence-backed implementation detail.".into(),
-            confidence: 0.9,
-            promotion_state: crate::models::twin::PromotionState::Endorsed,
-            evidence_count: 4,
-            source_label: Some("approved".into()),
-        }];
-        let candidates = vec![TwinContextRecord {
-            id: "record-candidate".into(),
-            kind: crate::models::twin::UserRecordKind::ReasoningPattern,
-            content: "User may prefer red-team critique before shipping.".into(),
-            confidence: 0.62,
-            promotion_state: crate::models::twin::PromotionState::Candidate,
-            evidence_count: 1,
-            source_label: Some("candidate".into()),
-        }];
-        let constitution = vec![
-            build_constitution_item(
-                "constitution-active",
-                "Prefer mission alignment before opportunistic funding.",
-                crate::models::twin::ConstitutionStatus::Active,
-                "interview-question",
-            ),
-            build_constitution_item(
-                "constitution-candidate",
-                "May prefer negotiation before rejection.",
-                crate::models::twin::ConstitutionStatus::Candidate,
-                "behavior",
-            ),
-            build_constitution_item(
-                "constitution-rejected",
-                "Rejected claims must not leak.",
-                crate::models::twin::ConstitutionStatus::Rejected,
-                "note",
-            ),
-            build_constitution_item(
-                "constitution-not-me",
-                "Not-me claims must not leak.",
-                crate::models::twin::ConstitutionStatus::NotMe,
-                "note",
-            ),
-            build_constitution_item(
-                "constitution-no-train",
-                "No-train claims must not leak.",
-                crate::models::twin::ConstitutionStatus::NoTrain,
-                "note",
-            ),
-        ];
-        let gaps = vec![build_action_gap("gap-1")];
-
-        let prompt = build_twin_context_prompt(
-            &ConstitutionSetup::default(),
-            &[],
-            &[(
-                "note-1".into(),
-                "Decision Notes".into(),
-                "### Message 2: Interviewee\nExpert says accept grants when partnerships are strategic.".into(),
-            )],
-            &approved,
-            &candidates,
-            &constitution,
-            &gaps,
-            &TwinAnswerMode::Advisor,
-            &PromptType::Standard,
-            None,
-        );
-
-        assert!(prompt.contains("## Twin Operating Contract"));
-        assert!(prompt.contains("## Reviewed Constitution"));
-        assert!(prompt.contains("Prefer mission alignment before opportunistic funding."));
-        assert!(prompt.contains("Interview question"));
-        assert!(prompt.contains("## Action Gap Risks"));
-        assert!(prompt.contains("May divert faculty from core mission work"));
-        assert!(prompt.contains("## Relevant Evidence"));
-        assert!(prompt.contains("Expert says accept grants when partnerships are strategic."));
-        assert!(prompt.contains("## Approved User Records"));
-        assert!(prompt.contains("## Tentative Candidate Records"));
-        assert!(prompt.contains("Candidate Constitution Hypotheses"));
-        assert!(prompt.contains("May prefer negotiation before rejection."));
-        assert!(!prompt.contains("Rejected claims must not leak."));
-        assert!(!prompt.contains("Not-me claims must not leak."));
-        assert!(!prompt.contains("No-train claims must not leak."));
-        assert!(prompt.contains("Use interviewee answers as evidence about the interviewee"));
-        assert!(prompt.contains("Do not use evidence to justify a preselected answer"));
-        assert!(prompt.contains("Recommended option"));
-        assert!(prompt.contains("decision-support assistant"));
-    }
-
-    #[test]
-    fn twin_context_prompt_labels_simulation_mode() {
-        let setup = test_twin_identity_setup();
-        let prompt = build_twin_context_prompt(
-            &setup,
-            &[],
-            &[],
-            &[],
-            &[],
-            &[],
-            &[],
-            &TwinAnswerMode::Simulation,
-            &PromptType::Standard,
-            None,
-        );
-
-        assert!(prompt.contains("## Twin Identity"));
-        assert!(prompt.contains("I am Alex Chen."));
-        assert!(prompt.contains("My role/context is founder deciding from product evidence."));
-        assert!(prompt.contains("Use reviewed notes and uploaded interviews only."));
-        assert!(prompt.contains("Continue my documented reasoning pattern"));
-        assert!(prompt.contains("do not append questions unless the user's request asks for them"));
-        assert!(!prompt.contains("reflective questions"));
-        assert!(!prompt.contains("next question"));
-        assert!(!prompt.contains("not the user's actual view"));
-        assert!(prompt.contains("## Reviewed Constitution"));
-    }
-
-    #[test]
-    fn twin_context_prompt_rejects_simulation_without_identity() {
-        let setup = ConstitutionSetup::default();
-
-        let result = validate_twin_identity_for_answer_mode(&setup, &TwinAnswerMode::Simulation);
-
-        assert!(result.is_err());
-        assert!(result
-            .unwrap_err()
-            .contains("Twin Identity requires Name and Role / context"));
-    }
-
-    #[test]
-    fn decision_advisor_prompt_uses_reflection_card_structure() {
-        let metadata = DecisionPromptMetadata {
-            decision: "Should Grafyn build Decision Mirror first?".into(),
-            options: vec!["Decision Mirror".into(), "Topology layer".into()],
-            stakes: Some("Product direction".into()),
-            initial_leaning: Some("Decision Mirror first".into()),
-            review_date: Some("2026-05-15".into()),
-        };
-
-        let prompt = build_twin_context_prompt(
-            &ConstitutionSetup::default(),
-            &[],
-            &[],
-            &[],
-            &[],
-            &[],
-            &[],
-            &TwinAnswerMode::Advisor,
-            &PromptType::Decision,
-            Some(&metadata),
-        );
-
-        assert!(prompt.contains("Decision Mirror session"));
-        assert!(prompt.contains("Reflection Card"));
-        assert!(prompt.contains("Blind Spot Hypothesis"));
-        assert!(prompt.contains("Recommendation must be derived after the Constitution Check and Evidence From Grafyn sections"));
-        assert!(prompt.contains("Decision: Should Grafyn build Decision Mirror first?"));
-        assert!(prompt.contains("Topology layer"));
-    }
-
-    #[test]
-    fn decision_simulation_prompt_uses_base_simulation_without_decision_style_block() {
-        let metadata = DecisionPromptMetadata {
-            decision: "Should Grafyn build Decision Mirror first?".into(),
-            options: vec!["Decision Mirror".into(), "Topology layer".into()],
-            stakes: Some("Product direction".into()),
-            initial_leaning: Some("Decision Mirror first".into()),
-            review_date: Some("2026-05-15".into()),
-        };
-
-        let prompt = build_twin_context_prompt(
-            &test_twin_identity_setup(),
-            &[],
-            &[],
-            &[],
-            &[],
-            &[],
-            &[],
-            &TwinAnswerMode::Simulation,
-            &PromptType::Decision,
-            Some(&metadata),
-        );
-
-        assert!(!prompt.contains("Reflection Card"));
-        assert!(!prompt.contains("Evidence From Grafyn"));
-        assert!(!prompt.contains("Blind Spot Hypothesis"));
-        assert!(!prompt.contains("Decision Mirror Simulation Style"));
-        assert!(!prompt.contains("Decision Mirror simulation session"));
-        assert!(!prompt.contains("natural first-person reflection"));
-        assert!(!prompt.contains("numbered headings"));
-        assert!(prompt.contains("do not append questions unless the user's request asks for them"));
-        assert!(!prompt.contains("not the user's actual view"));
-        assert!(prompt.contains("Decision: Should Grafyn build Decision Mirror first?"));
-    }
-
-    fn test_decision_case(
-        id: &str,
-        decision: &str,
-        lesson: Option<&str>,
-        note: Option<&str>,
-    ) -> DecisionEpisode {
-        let now = Utc::now();
-        DecisionEpisode {
-            id: id.to_string(),
-            session_id: "session-1".to_string(),
-            tile_id: format!("tile-{id}"),
-            decision: decision.to_string(),
-            options: vec!["Ship now".to_string(), "Wait a sprint".to_string()],
-            stakes: None,
-            initial_leaning: Some("Ship now".to_string()),
-            selected_response: None,
-            chosen_option: Some("Wait a sprint".to_string()),
-            confidence: None,
-            review_date: None,
-            outcome: None,
-            regret_score: None,
-            lesson: lesson.map(|text| text.to_string()),
-            missed_something: None,
-            primitive_assessment: PrimitiveDecisionAssessment::default(),
-            twin_prediction: None,
-            prediction_status: None,
-            agreement: None,
-            correction_note: note.map(|text| text.to_string()),
-            context_version: None,
-            outcome_recorded_at: None,
-            created_at: now,
-            updated_at: now,
-        }
-    }
-
-    #[test]
-    fn twin_context_prompt_renders_past_decision_cases_verbatim() {
-        let case = test_decision_case(
-            "case-1",
-            "Ship the importer before polish?",
-            Some("I always regret shipping before the empty states are done."),
-            Some("Twin assumed I optimize for speed; I optimize for trust."),
-        );
-
-        let prompt = build_twin_context_prompt(
-            &ConstitutionSetup::default(),
-            &[case],
-            &[],
-            &[],
-            &[],
-            &[],
-            &[],
-            &TwinAnswerMode::Advisor,
-            &PromptType::Standard,
-            None,
-        );
-
-        assert!(prompt.contains("## Past Decision Cases"));
-        assert!(prompt.contains("Past decision: Ship the importer before polish?"));
-        assert!(prompt.contains("Options: Ship now | Wait a sprint"));
-        assert!(prompt.contains("Chose: Wait a sprint"));
-        assert!(prompt.contains("I always regret shipping before the empty states are done."));
-        assert!(prompt.contains("Twin assumed I optimize for speed; I optimize for trust."));
-        assert!(prompt.contains("Weight them above abstracted records"));
-    }
-
-    #[test]
-    fn twin_context_budget_keeps_cases_and_drops_notes_when_tight() {
-        let case = test_decision_case("case-1", "Ship the importer before polish?", None, None);
-        let big_note = (
-            "note-1".to_string(),
-            "Big note".to_string(),
-            "evidence ".repeat(400),
-        );
-
-        let selection = apply_twin_context_budget(
-            vec![case],
-            Vec::new(),
-            Vec::new(),
-            Vec::new(),
-            Vec::new(),
-            vec![big_note],
-            60,
-        );
-
-        assert_eq!(selection.cases.len(), 1);
-        assert!(selection.notes.is_empty());
-    }
-
-    #[test]
-    fn sealed_prediction_prompt_is_immersed_with_identity_and_never_meta_framed() {
-        let setup = test_twin_identity_setup();
-        let options = vec!["Ship now".to_string(), "Wait a sprint".to_string()];
-        let user_message = build_twin_prediction_user_message(
-            &setup,
-            "Ship the importer before polish?",
-            &options,
-            Some("Launch trust"),
-        );
-        let system_prompt = build_twin_context_prompt(
-            &setup,
-            &[],
-            &[],
-            &[],
-            &[],
-            &[],
-            &[],
-            &TwinAnswerMode::Simulation,
-            &PromptType::Decision,
-            None,
-        );
-
-        assert!(user_message.contains("I am Alex Chen."));
-        assert!(user_message.contains("Which option do I choose?"));
-        assert!(user_message.contains("1. Ship now"));
-        assert!(user_message.contains("2. Wait a sprint"));
-        assert!(user_message.contains("predicted_option"));
-
-        // The full model-facing prompt must never meta-frame the twin.
-        let full_prompt = format!("{system_prompt}\n{user_message}").to_lowercase();
-        for forbidden in [
-            "simulate",
-            "roleplay",
-            "role-play",
-            "predict what the user",
-            "what would the user",
-            "pretend to be",
-        ] {
-            assert!(
-                !full_prompt.contains(forbidden),
-                "model-facing prompt contains forbidden meta-framing: {forbidden}"
-            );
-        }
-    }
-
-    #[test]
-    fn sealed_prediction_prompt_uses_advisor_framing_without_identity() {
-        let options = vec!["Ship now".to_string(), "Wait a sprint".to_string()];
-        let user_message = build_twin_prediction_user_message(
-            &ConstitutionSetup::default(),
-            "Ship the importer before polish?",
-            &options,
-            None,
-        );
-
-        assert!(!user_message.contains("I am "));
-        assert!(user_message.contains("best fits this decision-maker's"));
-        assert!(user_message.contains("predicted_option"));
-    }
-
-    #[test]
-    fn test_build_selected_parent_chain_returns_root_to_leaf_order() {
-        let session = build_session(vec![
-            build_tile(
-                "tile-1",
-                "Root prompt",
-                "openai/gpt-4",
-                "Root response",
-                None,
-                None,
-            ),
-            build_tile(
-                "tile-2",
-                "Follow-up prompt",
-                "openai/gpt-4",
-                "Follow-up response",
-                Some("tile-1"),
-                Some("openai/gpt-4"),
-            ),
-            build_tile(
-                "tile-3",
-                "Deep prompt",
-                "openai/gpt-4",
-                "Deep response",
-                Some("tile-2"),
-                Some("openai/gpt-4"),
-            ),
-        ]);
-        let request = build_request(
-            "Newest prompt",
-            "tile-3",
-            "openai/gpt-4",
-            ContextMode::FullHistory,
-        );
-
-        let turns = build_selected_parent_chain(&session, &request).unwrap();
-
-        assert_eq!(turns.len(), 3);
-        assert_eq!(turns[0].prompt, "Root prompt");
-        assert_eq!(turns[1].prompt, "Follow-up prompt");
-        assert_eq!(turns[2].prompt, "Deep prompt");
-    }
-
-    #[test]
-    fn test_build_full_history_messages_interleaves_user_and_assistant_turns() {
-        let session = build_session(vec![
-            build_tile(
-                "tile-1",
-                "Root prompt",
-                "openai/gpt-4",
-                "Root response",
-                None,
-                None,
-            ),
-            build_tile(
-                "tile-2",
-                "Branch prompt",
-                "openai/gpt-4",
-                "Branch response",
-                Some("tile-1"),
-                Some("openai/gpt-4"),
-            ),
-        ]);
-        let request = build_request(
-            "Final prompt",
-            "tile-2",
-            "openai/gpt-4",
-            ContextMode::FullHistory,
-        );
-
-        let messages = build_full_history_messages(&session, &request).unwrap();
-
-        assert_eq!(messages.len(), 5);
-        assert_eq!(messages[0].role, "user");
-        assert_eq!(messages[0].content, "Root prompt");
-        assert_eq!(messages[1].role, "assistant");
-        assert_eq!(messages[1].content, "Root response");
-        assert_eq!(messages[2].content, "Branch prompt");
-        assert_eq!(messages[3].content, "Branch response");
-        assert_eq!(messages[4].content, "Final prompt");
-    }
-
-    #[test]
-    fn test_root_prompt_without_parent_ids_ignores_unrelated_canvas_tiles() {
-        let session = build_session(vec![
-            build_tile(
-                "tile-1",
-                "Unrelated root prompt",
-                "openai/gpt-4",
-                "Unrelated root response",
-                None,
-                None,
-            ),
-            build_tile(
-                "tile-2",
-                "Unrelated branch prompt",
-                "openai/gpt-4",
-                "Unrelated branch response",
-                Some("tile-1"),
-                Some("openai/gpt-4"),
-            ),
-        ]);
-        let request = build_root_request("Fresh root prompt", ContextMode::None);
-
-        let messages = build_canvas_messages(&session, &request).unwrap();
-
-        assert_eq!(messages.len(), 1);
-        assert_eq!(messages[0].role, "user");
-        assert_eq!(messages[0].content, "Fresh root prompt");
-    }
-
-    #[test]
-    fn test_build_compact_history_messages_summarizes_older_turns() {
-        let session = build_session(vec![
-            build_tile(
-                "tile-1",
-                "Prompt 1",
-                "openai/gpt-4",
-                "Response 1",
-                None,
-                None,
-            ),
-            build_tile(
-                "tile-2",
-                "Prompt 2",
-                "openai/gpt-4",
-                "Response 2",
-                Some("tile-1"),
-                Some("openai/gpt-4"),
-            ),
-            build_tile(
-                "tile-3",
-                "Prompt 3",
-                "openai/gpt-4",
-                "Response 3",
-                Some("tile-2"),
-                Some("openai/gpt-4"),
-            ),
-            build_tile(
-                "tile-4",
-                "Prompt 4",
-                "openai/gpt-4",
-                "Response 4",
-                Some("tile-3"),
-                Some("openai/gpt-4"),
-            ),
-        ]);
-        let request = build_request("Prompt 5", "tile-4", "openai/gpt-4", ContextMode::Compact);
-
-        let messages = build_compact_history_messages(&session, &request).unwrap();
-
-        assert_eq!(messages.len(), 6);
-        assert!(messages[0]
-            .content
-            .contains("Conversation summary before the most recent turns"));
-        assert!(messages[0].content.contains("Prompt 1"));
-        assert!(messages[1].content.contains("Prompt 3"));
-        assert!(messages[2].content.contains("Response 3"));
-        assert_eq!(messages[5].content, "Prompt 5");
-    }
-
-    #[test]
-    fn test_build_selected_parent_chain_errors_when_parent_response_is_missing() {
-        let session = build_session(vec![
-            build_tile(
-                "tile-1",
-                "Root prompt",
-                "openai/gpt-4",
-                "Root response",
-                None,
-                None,
-            ),
-            build_tile(
-                "tile-2",
-                "Branch prompt",
-                "anthropic/claude",
-                "Branch response",
-                Some("tile-1"),
-                Some("openai/gpt-4"),
-            ),
-        ]);
-        let request = build_request(
-            "Next prompt",
-            "tile-2",
-            "openai/gpt-4",
-            ContextMode::FullHistory,
-        );
-
-        let err = build_selected_parent_chain(&session, &request).unwrap_err();
-
-        assert!(err.contains("Parent response not found"));
-    }
-
-    #[test]
-    fn test_prompt_request_from_tile_preserves_web_search_settings() {
-        let tile = PromptTile {
-            web_search: true,
-            web_search_max_results: 8,
-            reasoning_effort: "high".to_string(),
-            ..build_tile("tile-1", "Prompt", "openai/gpt-4", "Response", None, None)
-        };
-
-        let request = prompt_request_from_tile(&tile, vec!["openai/gpt-4".to_string()], 0.3);
-
-        assert!(request.web_search);
-        assert_eq!(request.web_search_max_results, 8);
-        assert_eq!(request.temperature, 0.3);
-        assert_eq!(request.max_tokens, None);
-        assert_eq!(request.reasoning_effort, "high");
-    }
-
-    #[test]
-    fn test_prompt_request_from_tile_preserves_twin_settings() {
-        let tile = PromptTile {
-            context_mode: ContextMode::Twin,
-            twin_answer_mode: TwinAnswerMode::Simulation,
-            twin_context_policy: Some("approved_plus_relevant_candidates".to_string()),
-            twin_llm_provider: Some("ollama".to_string()),
-            ..build_tile("tile-1", "Prompt", "openai/gpt-4", "Response", None, None)
-        };
-
-        let request = prompt_request_from_tile(&tile, vec!["openai/gpt-4".to_string()], 0.7);
-
-        assert_eq!(request.context_mode, ContextMode::Twin);
-        assert_eq!(request.twin_answer_mode, TwinAnswerMode::Simulation);
-        assert_eq!(
-            request.twin_context_policy.as_deref(),
-            Some("approved_plus_relevant_candidates")
-        );
-        assert_eq!(request.twin_llm_provider.as_deref(), Some("ollama"));
-    }
-
-    #[test]
-    fn test_classify_streamed_model_response_rejects_empty_content() {
-        let update =
-            classify_streamed_model_response("openai/gpt-4".to_string(), "   \n\t".to_string());
-
-        assert_eq!(update.0, "openai/gpt-4");
-        assert_eq!(update.1, "");
-        assert_eq!(update.2, ResponseStatus::Error);
-        assert_eq!(update.3.as_deref(), Some(EMPTY_MODEL_RESPONSE_ERROR));
-    }
-
-    #[test]
-    fn test_classify_streamed_model_response_accepts_non_empty_content() {
-        let update =
-            classify_streamed_model_response("openai/gpt-4".to_string(), "Answer".to_string());
+    #[test]
+    fn test_classify_streamed_model_response_accepts_non_empty_content() {
+        let update =
+            classify_streamed_model_response("openai/gpt-4".to_string(), "Answer".to_string());
 
         assert_eq!(update.2, ResponseStatus::Completed);
         assert_eq!(update.3, None);
         assert_eq!(update.1, "Answer");
     }
-
-    #[test]
-    fn test_should_use_retrieved_notes_accepts_relevant_matches() {
-        let results = vec![build_retrieval_result(
-            "note-1",
-            "Mirofish architecture ideas",
-            "A note about robust social media posting architecture.",
-            12.0,
-            &["keyword match"],
-        )];
-
-        let decision = should_use_retrieved_notes(
-            "How can I make the Mirofish social media architecture more robust?",
-            &results,
-        );
-
-        assert_eq!(decision, RetrievalDecisionReason::UseRetrievedNotes);
-    }
-
-    #[test]
-    fn test_should_use_retrieved_notes_rejects_off_topic_matches() {
-        let results = vec![build_retrieval_result(
-            "note-1",
-            "Claude skills overview",
-            "General AI skills and coding workflow tips.",
-            72.0,
-            &["keyword match", "hub (5 backlinks)"],
-        )];
-
-        let decision = should_use_retrieved_notes(
-            "How can I make the Mirofish social media architecture more robust?",
-            &results,
-        );
-
-        assert_eq!(decision, RetrievalDecisionReason::NoLexicalOverlap);
-    }
-
-    #[test]
-    fn test_should_use_retrieved_notes_rejects_graph_only_results() {
-        let results = vec![build_retrieval_result(
-            "note-1",
-            "Mirofish architecture",
-            "A note about robust social media posting architecture.",
-            20.0,
-            &["graph neighbor (1 hop)", "hub (4 backlinks)"],
-        )];
-
-        let decision = should_use_retrieved_notes(
-            "How can I make the Mirofish social media architecture more robust?",
-            &results,
-        );
-
-        assert_eq!(decision, RetrievalDecisionReason::NoKeywordMatch);
-    }
 }
diff --git a/frontend/src-tauri/src/commands/canvas/shared.rs b/frontend/src-tauri/src/commands/canvas/shared.rs
index da05237..c4c4dcf 100644
--- a/frontend/src-tauri/src/commands/canvas/shared.rs
+++ b/frontend/src-tauri/src/commands/canvas/shared.rs
@@ -2,7 +2,6 @@ use crate::models::canvas::{CanvasSession, ContextMode, PromptType};
 use crate::models::settings::UserSettings;
 use crate::models::twin::TraceEventType;
 use crate::services::twin_store::TwinStore;
-use serde_json::json;
 use std::sync::Arc;
 use tokio::sync::RwLock;
 
@@ -65,7 +64,10 @@ pub(super) fn source_tile_context_provider(
     (false, None)
 }
 
-pub(super) fn is_vault_context_prompt(prompt_type: &PromptType, context_mode: &ContextMode) -> bool {
+pub(super) fn is_vault_context_prompt(
+    prompt_type: &PromptType,
+    context_mode: &ContextMode,
+) -> bool {
     prompt_type == &PromptType::Decision
         || matches!(
             context_mode,
@@ -77,7 +79,10 @@ pub(super) fn is_vault_context_prompt(prompt_type: &PromptType, context_mode: &C
         )
 }
 
-pub(super) fn effective_model_ids(route: &ModelRoute, requested_model_ids: &[String]) -> Vec<String> {
+pub(super) fn effective_model_ids(
+    route: &ModelRoute,
+    requested_model_ids: &[String],
+) -> Vec<String> {
     match route.provider {
         ModelProviderRoute::Ollama => {
             if requested_model_ids.is_empty() {
diff --git a/frontend/src-tauri/src/commands/canvas/test_support.rs b/frontend/src-tauri/src/commands/canvas/test_support.rs
new file mode 100644
index 0000000..a6d3af2
--- /dev/null
+++ b/frontend/src-tauri/src/commands/canvas/test_support.rs
@@ -0,0 +1,61 @@
+//! Test-only builder helpers shared by more than one canvas submodule's test
+//! suite (currently `context` and `streaming`). Kept separate from either
+//! module so neither has to duplicate `build_tile`/`build_response`.
+#![cfg(test)]
+
+use crate::models::canvas::{
+    ContextMode, ModelResponse, PromptTile, PromptType, ResponseStatus, TilePosition,
+    TwinAnswerMode,
+};
+use std::collections::HashMap;
+
+pub(super) fn build_response(model_id: &str, content: &str) -> ModelResponse {
+    ModelResponse {
+        id: format!("resp-{}", model_id),
+        model_id: model_id.to_string(),
+        model_name: model_id.to_string(),
+        content: content.to_string(),
+        status: ResponseStatus::Completed,
+        error: None,
+        tokens_used: None,
+        created_at: chrono::Utc::now(),
+        position: TilePosition::default(),
+    }
+}
+
+pub(super) fn build_tile(
+    id: &str,
+    prompt: &str,
+    model_id: &str,
+    response: &str,
+    parent_tile_id: Option<&str>,
+    parent_model_id: Option<&str>,
+) -> PromptTile {
+    let mut responses = HashMap::new();
+    responses.insert(model_id.to_string(), build_response(model_id, response));
+
+    PromptTile {
+        id: id.to_string(),
+        prompt_type: PromptType::Standard,
+        prompt: prompt.to_string(),
+        system_prompt: None,
+        models: vec![model_id.to_string()],
+        responses,
+        position: TilePosition::default(),
+        created_at: chrono::Utc::now(),
+        context_mode: ContextMode::default(),
+        parent_tile_id: parent_tile_id.map(str::to_string),
+        parent_model_id: parent_model_id.map(str::to_string),
+        context_notes: Vec::new(),
+        approved_twin_records: Vec::new(),
+        candidate_twin_records: Vec::new(),
+        twin_answer_mode: TwinAnswerMode::default(),
+        twin_context_policy: None,
+        twin_llm_provider: None,
+        decision_metadata: None,
+        decision_episode_id: None,
+        web_search: false,
+        web_search_max_results: 5,
+        reasoning_effort: "none".to_string(),
+    }
+}

From 97fc87808cd24f7e53e00c2565173fc636e15ed0 Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 14:34:01 +0800
Subject: [PATCH 04/30] refactor: extract canvas::streaming
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move send_prompt, add_models_to_tile, regenerate_response, and the
per-model stream task helpers (persistence-error emitters, timeout
handling, response classification) into canvas::streaming. Pure move;
tests move verbatim, reusing canvas::test_support for tile builders.

canvas::mod.rs now glob re-exports streaming's tauri commands
(`pub use streaming::*;`) rather than naming them individually — the
`#[tauri::command]` macro emits a hidden `__cmd__<name>` sibling item
that a named re-export wouldn't carry along, which broke
`tauri::generate_handler!` resolution in main.rs.
---
 frontend/src-tauri/src/commands/canvas/mod.rs | 1235 +---------------
 .../src/commands/canvas/streaming.rs          | 1237 +++++++++++++++++
 2 files changed, 1245 insertions(+), 1227 deletions(-)
 create mode 100644 frontend/src-tauri/src/commands/canvas/streaming.rs

diff --git a/frontend/src-tauri/src/commands/canvas/mod.rs b/frontend/src-tauri/src/commands/canvas/mod.rs
index b3e163a..5552dfa 100644
--- a/frontend/src-tauri/src/commands/canvas/mod.rs
+++ b/frontend/src-tauri/src/commands/canvas/mod.rs
@@ -1,25 +1,20 @@
 use crate::commands::commit_note_write;
 use crate::models::canvas::{
-    AddModelsRequest, AvailableModel, CanvasSession, CanvasStreamEvent, CanvasViewport,
-    ContextMode, Debate, DebateContinueRequest, DebateResponse, DebateRound, DebateStartRequest,
-    LLMNodePositionUpdate, ModelResponse, PromptRequest, PromptTile, PromptType, ResponseStatus,
-    SessionCreate, SessionMeta, SessionUpdate, TilePosition, TilePositionUpdate,
+    AvailableModel, CanvasSession, CanvasStreamEvent, CanvasViewport, ContextMode, Debate,
+    DebateContinueRequest, DebateResponse, DebateRound, DebateStartRequest, LLMNodePositionUpdate,
+    PromptType, ResponseStatus, SessionCreate, SessionMeta, SessionUpdate, TilePosition,
+    TilePositionUpdate,
 };
 use crate::models::note::{NoteCreate, NoteStatus};
-use crate::models::twin::{
-    DecisionEpisodeCreate, PrimitiveDecisionAssessment, ReflectionCardCreate, TraceEventType,
-};
+use crate::models::twin::TraceEventType;
 use crate::services::openrouter::ChatMessage;
-use crate::services::twin_store::TwinStore;
 use crate::AppState;
 use chrono::Utc;
 use futures::StreamExt;
 use serde_json::json;
 use std::collections::HashMap;
-use std::sync::Arc;
 use std::time::Duration;
 use tauri::State;
-use tokio::sync::RwLock;
 
 mod shared;
 use shared::{
@@ -28,21 +23,13 @@ use shared::{
 };
 
 mod context;
-use context::{resolve_prompt_context, run_sealed_twin_prediction, TWIN_CONTEXT_VERSION};
+
+mod streaming;
+pub use streaming::*;
 
 #[cfg(test)]
 mod test_support;
 
-const EMPTY_MODEL_RESPONSE_ERROR: &str = "No response returned from model";
-
-// LLM node layout constants
-const LLM_NODE_WIDTH: f64 = 280.0;
-const LLM_NODE_HEIGHT: f64 = 200.0;
-const LLM_NODE_Y_STEP: f64 = 300.0; // height(200) + 100px gap for content overflow
-const LLM_NODE_X_GAP: f64 = 80.0;
-
-type StreamedResponseUpdate = (String, String, ResponseStatus, Option<String>);
-
 /// List all canvas sessions
 #[tauri::command]
 pub async fn list_sessions(state: State<'_, AppState>) -> Result<Vec<SessionMeta>, String> {
@@ -146,475 +133,6 @@ pub async fn get_available_models(
         .map_err(|e| e.to_string())
 }
 
-/// Send a prompt to multiple models with streaming responses via Tauri events.
-/// Returns the tile_id immediately; actual responses stream via "canvas-stream" events.
-#[tauri::command]
-pub async fn send_prompt(
-    window: tauri::Window,
-    session_id: String,
-    mut request: PromptRequest,
-    state: State<'_, AppState>,
-) -> Result<String, String> {
-    let tile_id = uuid::Uuid::new_v4().to_string();
-    let now = Utc::now();
-    let model_route = {
-        let settings = state.settings_service.read().await;
-        resolve_model_route(
-            &request.prompt_type,
-            &request.context_mode,
-            request.twin_llm_provider.as_deref(),
-            settings.get(),
-        )?
-    };
-    request.models = effective_model_ids(&model_route, &request.models);
-    let session = {
-        let mut store = state.canvas_store.write().await;
-        store.get_session(&session_id).map_err(|e| e.to_string())?
-    };
-    let resolved_context = resolve_prompt_context(state.inner(), &session, &request).await?;
-    let decision_episode_id = if request.prompt_type == PromptType::Decision {
-        Some(uuid::Uuid::new_v4().to_string())
-    } else {
-        None
-    };
-
-    // Compute LLM node positions (offset from prompt tile)
-    let prompt_pos = request.position.clone().unwrap_or_default();
-    let llm_start_x = prompt_pos.x + prompt_pos.width + LLM_NODE_X_GAP;
-
-    // Create initial responses map with positions
-    let mut responses: HashMap<String, ModelResponse> = HashMap::new();
-    for (i, model_id) in request.models.iter().enumerate() {
-        let model_name = model_id.split('/').last().unwrap_or(model_id).to_string();
-        let llm_y = prompt_pos.y + (i as f64) * LLM_NODE_Y_STEP;
-        responses.insert(
-            model_id.clone(),
-            ModelResponse {
-                id: uuid::Uuid::new_v4().to_string(),
-                model_id: model_id.clone(),
-                model_name,
-                content: String::new(),
-                status: ResponseStatus::Pending,
-                error: None,
-                tokens_used: None,
-                created_at: now,
-                position: TilePosition {
-                    x: llm_start_x,
-                    y: llm_y,
-                    width: LLM_NODE_WIDTH,
-                    height: LLM_NODE_HEIGHT,
-                },
-            },
-        );
-    }
-
-    // Create the tile (with context notes attached)
-    let tile = PromptTile {
-        id: tile_id.clone(),
-        prompt_type: request.prompt_type.clone(),
-        prompt: request.prompt.clone(),
-        system_prompt: request.system_prompt.clone(),
-        models: request.models.clone(),
-        responses: responses.clone(),
-        position: prompt_pos,
-        created_at: now,
-        context_mode: request.context_mode,
-        parent_tile_id: request.parent_tile_id,
-        parent_model_id: request.parent_model_id,
-        context_notes: resolved_context.context_notes.clone(),
-        approved_twin_records: resolved_context.approved_twin_records.clone(),
-        candidate_twin_records: resolved_context.candidate_twin_records.clone(),
-        twin_answer_mode: request.twin_answer_mode.clone(),
-        twin_context_policy: request.twin_context_policy.clone(),
-        twin_llm_provider: request.twin_llm_provider.clone(),
-        decision_metadata: request.decision_metadata.clone(),
-        decision_episode_id: decision_episode_id.clone(),
-        web_search: request.web_search,
-        web_search_max_results: request.web_search_max_results,
-        reasoning_effort: request.reasoning_effort.clone(),
-    };
-
-    // Save tile to session
-    {
-        let mut store = state.canvas_store.write().await;
-        store
-            .add_tile(&session_id, tile.clone())
-            .map_err(|e| e.to_string())?;
-    }
-
-    if let Some(decision_episode_id) = decision_episode_id.clone() {
-        let decision_metadata = request.decision_metadata.clone().unwrap_or_default();
-        let decision = if decision_metadata.decision.trim().is_empty() {
-            request.prompt.clone()
-        } else {
-            decision_metadata.decision
-        };
-        let mut twin_store = state.twin_store.write().await;
-        twin_store
-            .record_decision_episode(DecisionEpisodeCreate {
-                id: decision_episode_id,
-                session_id: session_id.clone(),
-                tile_id: tile_id.clone(),
-                decision,
-                options: decision_metadata.options,
-                stakes: decision_metadata.stakes,
-                initial_leaning: decision_metadata.initial_leaning,
-                review_date: decision_metadata.review_date,
-                primitive_assessment: PrimitiveDecisionAssessment::default(),
-                // Stamped on every decision episode — including non-Twin
-                // context tiles — so attribution survives a failed or absent
-                // hidden prediction call.
-                context_version: Some(
-                    resolved_context
-                        .context_version
-                        .clone()
-                        .unwrap_or_else(|| TWIN_CONTEXT_VERSION.to_string()),
-                ),
-            })
-            .map_err(|error| error.to_string())?;
-    }
-
-    append_canvas_trace(
-        state.twin_store.clone(),
-        &session_id,
-        TraceEventType::PromptSubmitted,
-        json!({
-            "tile_id": tile.id.clone(),
-            "prompt_type": tile.prompt_type.clone(),
-            "decision_episode_id": tile.decision_episode_id.clone(),
-            "decision_metadata": tile.decision_metadata.clone(),
-            "prompt": tile.prompt.clone(),
-            "models": tile.models.clone(),
-            "context_mode": tile.context_mode.clone(),
-            "parent_tile_id": tile.parent_tile_id.clone(),
-            "parent_model_id": tile.parent_model_id.clone(),
-            "context_note_ids": tile.context_notes.iter().map(|note| note.id.clone()).collect::<Vec<_>>(),
-            "twin_answer_mode": tile.twin_answer_mode.clone(),
-            "approved_twin_record_ids": tile.approved_twin_records.iter().map(|record| record.id.clone()).collect::<Vec<_>>(),
-            "candidate_twin_record_ids": tile.candidate_twin_records.iter().map(|record| record.id.clone()).collect::<Vec<_>>(),
-            "constitution_item_ids": resolved_context.constitution_items.iter().map(|item| item.id.clone()).collect::<Vec<_>>(),
-            "action_gap_ids": resolved_context.action_gaps.iter().map(|gap| gap.id.clone()).collect::<Vec<_>>(),
-            "context_version": resolved_context.context_version.clone(),
-            "decision_case_ids": resolved_context.decision_case_ids.clone(),
-            "web_search": tile.web_search,
-            "web_search_max_results": tile.web_search_max_results,
-        }),
-    )
-    .await;
-
-    // Emit TileCreated event
-    let _ = window.emit(
-        "canvas-stream",
-        CanvasStreamEvent::TileCreated {
-            session_id: session_id.clone(),
-            tile: tile.clone(),
-        },
-    );
-
-    // Emit ContextNotes event (so frontend can display which notes were used)
-    if !resolved_context.context_notes.is_empty() {
-        let _ = window.emit(
-            "canvas-stream",
-            CanvasStreamEvent::ContextNotes {
-                session_id: session_id.clone(),
-                tile_id: tile_id.clone(),
-                notes: resolved_context.context_notes.clone(),
-            },
-        );
-    }
-
-    // Clone what we need for the spawned task
-    let openrouter_arc = state.openrouter.clone();
-    let ollama_arc = state.ollama.clone();
-    let canvas_store_arc = state.canvas_store.clone();
-    let twin_store_arc = state.twin_store.clone();
-    let models = request.models.clone();
-    let messages = resolved_context.messages.clone();
-    let system_prompt = resolved_context.system_prompt.clone();
-    let temperature = request.temperature;
-    let web_search = request.web_search;
-    let web_search_max_results = request.web_search_max_results;
-    let reasoning_effort = request.reasoning_effort.clone();
-    let provider_route = model_route.provider.clone();
-    let tile_id_clone = tile_id.clone();
-    let session_id_clone = session_id.clone();
-    let decision_episode_id_for_reflection = tile.decision_episode_id.clone();
-    let reflection_note_ids = tile
-        .context_notes
-        .iter()
-        .map(|note| note.id.clone())
-        .collect::<Vec<_>>();
-    let reflection_user_record_ids = tile
-        .approved_twin_records
-        .iter()
-        .chain(tile.candidate_twin_records.iter())
-        .map(|record| record.id.clone())
-        .collect::<Vec<_>>();
-    let reflection_constitution_item_ids = resolved_context
-        .constitution_items
-        .iter()
-        .map(|item| item.id.clone())
-        .collect::<Vec<_>>();
-    let reflection_action_gap_ids = resolved_context
-        .action_gaps
-        .iter()
-        .map(|gap| gap.id.clone())
-        .collect::<Vec<_>>();
-
-    // Spawn async task for streaming (doesn't block the IPC response)
-    tauri::async_runtime::spawn(async move {
-        // Stream all models concurrently using JoinSet
-        let mut join_set = tokio::task::JoinSet::new();
-
-        for model_id in models {
-            let messages = messages.clone();
-            let system_prompt = system_prompt.clone();
-            let reasoning_effort = reasoning_effort.clone();
-            let provider_route = provider_route.clone();
-            let openrouter_arc = openrouter_arc.clone();
-            let ollama_arc = ollama_arc.clone();
-            let window = window.clone();
-            let session_id = session_id_clone.clone();
-            let tile_id = tile_id_clone.clone();
-
-            join_set.spawn(async move {
-                let stream_result = match provider_route {
-                    ModelProviderRoute::Ollama => {
-                        let ollama = ollama_arc.read().await;
-                        let result = ollama
-                            .chat_stream(
-                                &model_id,
-                                messages,
-                                system_prompt.as_deref(),
-                                Some(temperature),
-                            )
-                            .await;
-                        drop(ollama);
-                        result.map(|stream| {
-                            Box::pin(stream)
-                                as std::pin::Pin<
-                                    Box<dyn futures::Stream<Item = anyhow::Result<String>> + Send>,
-                                >
-                        })
-                    }
-                    ModelProviderRoute::OpenRouter => {
-                        let openrouter = openrouter_arc.read().await;
-                        let result = openrouter
-                            .chat_stream(
-                                &model_id,
-                                messages,
-                                system_prompt.as_deref(),
-                                Some(temperature),
-                                None,
-                                Some(reasoning_effort.as_str()),
-                                web_search,
-                                web_search_max_results,
-                            )
-                            .await;
-                        drop(openrouter);
-                        result.map(|stream| {
-                            Box::pin(stream)
-                                as std::pin::Pin<
-                                    Box<dyn futures::Stream<Item = anyhow::Result<String>> + Send>,
-                                >
-                        })
-                    }
-                };
-
-                match stream_result {
-                    Ok(stream) => {
-                        let mut stream = stream;
-                        let mut full_content = String::new();
-
-                        loop {
-                            match tokio::time::timeout(Duration::from_secs(60), stream.next()).await
-                            {
-                                Ok(Some(Ok(chunk))) => {
-                                    if !chunk.is_empty() {
-                                        full_content.push_str(&chunk);
-                                        let _ = window.emit(
-                                            "canvas-stream",
-                                            CanvasStreamEvent::Chunk {
-                                                session_id: session_id.clone(),
-                                                tile_id: tile_id.clone(),
-                                                model_id: model_id.clone(),
-                                                chunk,
-                                            },
-                                        );
-                                    }
-                                }
-                                Ok(Some(Err(e))) => {
-                                    let error = e.to_string();
-                                    emit_canvas_error(
-                                        &window,
-                                        &session_id,
-                                        &tile_id,
-                                        &model_id,
-                                        &error,
-                                    );
-                                    return (
-                                        model_id,
-                                        String::new(),
-                                        ResponseStatus::Error,
-                                        Some(error),
-                                    );
-                                }
-                                Ok(None) => break, // Stream ended naturally
-                                Err(_) => {
-                                    let error = "Stream idle timeout (60s)".to_string();
-                                    emit_canvas_error(
-                                        &window,
-                                        &session_id,
-                                        &tile_id,
-                                        &model_id,
-                                        &error,
-                                    );
-                                    return (
-                                        model_id,
-                                        full_content,
-                                        ResponseStatus::Error,
-                                        Some(error),
-                                    );
-                                }
-                            }
-                        }
-
-                        finalize_streamed_model_response(
-                            &window,
-                            &session_id,
-                            &tile_id,
-                            model_id,
-                            full_content,
-                        )
-                    }
-                    Err(e) => {
-                        let error = e.to_string();
-                        emit_canvas_error(&window, &session_id, &tile_id, &model_id, &error);
-                        (model_id, String::new(), ResponseStatus::Error, Some(error))
-                    }
-                }
-            });
-        }
-
-        // Wait for all models and collect results
-        let mut results = Vec::new();
-        while let Some(result) = join_set.join_next().await {
-            if let Ok(r) = result {
-                results.push(r);
-            }
-        }
-
-        // Batch update store with all results in a single write
-        let persistence_ok = {
-            let mut store = canvas_store_arc.write().await;
-            match store.batch_update_tile_responses(&session_id_clone, &tile_id_clone, &results) {
-                Ok(()) => true,
-                Err(error) => {
-                    let model_ids: Vec<String> = results
-                        .iter()
-                        .map(|(model_id, _, _, _)| model_id.clone())
-                        .collect();
-                    emit_persistence_error(
-                        &window,
-                        &session_id_clone,
-                        &tile_id_clone,
-                        &model_ids,
-                        &error,
-                    );
-                    false
-                }
-            }
-        };
-
-        append_model_result_traces(
-            twin_store_arc.clone(),
-            &session_id_clone,
-            &tile_id_clone,
-            "send_prompt",
-            &results,
-        )
-        .await;
-
-        if let Some(decision_episode_id) = decision_episode_id_for_reflection {
-            let mut twin_store = twin_store_arc.write().await;
-            for (model_id, content, status, _) in &results {
-                if *status != ResponseStatus::Completed || content.trim().is_empty() {
-                    continue;
-                }
-
-                let _ = twin_store.record_reflection_card(ReflectionCardCreate {
-                    decision_episode_id: decision_episode_id.clone(),
-                    session_id: session_id_clone.clone(),
-                    tile_id: tile_id_clone.clone(),
-                    model_id: model_id.clone(),
-                    content: content.clone(),
-                    cited_note_ids: reflection_note_ids.clone(),
-                    cited_user_record_ids: reflection_user_record_ids.clone(),
-                    cited_constitution_item_ids: reflection_constitution_item_ids.clone(),
-                    cited_action_gap_ids: reflection_action_gap_ids.clone(),
-                    evidence_packet: None,
-                });
-            }
-        }
-
-        // Emit session saved after all models complete — but only if the
-        // batch persist above actually succeeded. If it failed, per-model
-        // Error events were already emitted and the frontend must not
-        // believe the (in-memory only) responses were saved to disk.
-        if persistence_ok {
-            let _ = window.emit(
-                "canvas-stream",
-                CanvasStreamEvent::SessionSaved {
-                    session_id: session_id_clone,
-                },
-            );
-        }
-    });
-
-    // Sealed twin prediction: one hidden, non-streaming call per decision
-    // episode with at least two options. Fire-and-forget in its own task —
-    // it never emits canvas-stream events and cannot block or fail the
-    // visible flow above.
-    if let Some(episode_id) = tile.decision_episode_id.clone() {
-        let metadata = tile.decision_metadata.clone().unwrap_or_default();
-        if metadata.options.len() >= 2 {
-            let prediction_model = match model_route.provider {
-                ModelProviderRoute::Ollama => tile.models.first().cloned().unwrap_or_default(),
-                ModelProviderRoute::OpenRouter => {
-                    let settings = state.settings_service.read().await;
-                    settings.get().llm_model.clone()
-                }
-            };
-            let decision = if metadata.decision.trim().is_empty() {
-                tile.prompt.clone()
-            } else {
-                metadata.decision.clone()
-            };
-            let context_version = resolved_context
-                .context_version
-                .clone()
-                .unwrap_or_else(|| TWIN_CONTEXT_VERSION.to_string());
-            tauri::async_runtime::spawn(run_sealed_twin_prediction(
-                state.twin_store.clone(),
-                state.openrouter.clone(),
-                state.ollama.clone(),
-                model_route.provider.clone(),
-                prediction_model,
-                episode_id,
-                tile.prompt.clone(),
-                decision,
-                metadata.options.clone(),
-                metadata.stakes.clone(),
-                resolved_context.twin_context_prompt.clone(),
-                context_version,
-                tile.decision_metadata.clone(),
-            ));
-        }
-    }
-
-    Ok(tile_id)
-}
-
 /// Update a tile's position
 #[tauri::command]
 pub async fn update_tile_position(
@@ -1524,630 +1042,6 @@ pub async fn continue_debate(
     Ok(())
 }
 
-/// Add new models to an existing tile (same prompt, new model responses)
-#[tauri::command]
-pub async fn add_models_to_tile(
-    window: tauri::Window,
-    session_id: String,
-    tile_id: String,
-    request: AddModelsRequest,
-    state: State<'_, AppState>,
-) -> Result<(), String> {
-    // Get the tile's prompt
-    let mut store = state.canvas_store.write().await;
-    let session = store.get_session(&session_id).map_err(|e| e.to_string())?;
-    drop(store);
-
-    let tile = session
-        .prompt_tiles
-        .iter()
-        .find(|t| t.id == tile_id)
-        .ok_or_else(|| "Tile not found".to_string())?
-        .clone();
-    let model_route = {
-        let settings = state.settings_service.read().await;
-        resolve_model_route(
-            &tile.prompt_type,
-            &tile.context_mode,
-            tile.twin_llm_provider.as_deref(),
-            settings.get(),
-        )?
-    };
-    let model_ids = effective_model_ids(&model_route, &request.model_ids);
-    let prompt_request = prompt_request_from_tile(&tile, model_ids.clone(), 0.7);
-    let resolved_context = resolve_prompt_context(state.inner(), &session, &prompt_request).await?;
-
-    let now = Utc::now();
-
-    // Calculate positions for new models
-    let existing_count = tile.responses.len();
-    let prompt_pos = &tile.position;
-    let llm_start_x = prompt_pos.x + prompt_pos.width + LLM_NODE_X_GAP;
-
-    // Add initial pending responses and notify frontend before streaming
-    let mut new_responses: HashMap<String, ModelResponse> = HashMap::new();
-    {
-        let mut store = state.canvas_store.write().await;
-        let mut session = store.get_session(&session_id).map_err(|e| e.to_string())?;
-        if let Some(t) = session.prompt_tiles.iter_mut().find(|t| t.id == tile_id) {
-            for (i, model_id) in model_ids.iter().enumerate() {
-                let model_name = model_id.split('/').last().unwrap_or(model_id).to_string();
-                let llm_y = prompt_pos.y + ((existing_count + i) as f64) * LLM_NODE_Y_STEP;
-                let response = ModelResponse {
-                    id: uuid::Uuid::new_v4().to_string(),
-                    model_id: model_id.clone(),
-                    model_name,
-                    content: String::new(),
-                    status: ResponseStatus::Pending,
-                    error: None,
-                    tokens_used: None,
-                    created_at: now,
-                    position: TilePosition {
-                        x: llm_start_x,
-                        y: llm_y,
-                        width: LLM_NODE_WIDTH,
-                        height: LLM_NODE_HEIGHT,
-                    },
-                };
-                new_responses.insert(model_id.clone(), response.clone());
-                t.models.push(model_id.clone());
-                t.responses.insert(model_id.clone(), response);
-            }
-            session.updated_at = Utc::now();
-            store.save_session(&session).map_err(|e| e.to_string())?;
-        }
-    }
-
-    // Notify frontend about new responses before streaming starts
-    let _ = window.emit(
-        "canvas-stream",
-        CanvasStreamEvent::ModelsAdded {
-            session_id: session_id.clone(),
-            tile_id: tile_id.clone(),
-            responses: new_responses,
-        },
-    );
-
-    // Spawn streaming task
-    let openrouter_arc = state.openrouter.clone();
-    let ollama_arc = state.ollama.clone();
-    let canvas_store_arc = state.canvas_store.clone();
-    let twin_store_arc = state.twin_store.clone();
-    let messages = resolved_context.messages.clone();
-    let system_prompt = resolved_context.system_prompt.clone();
-    let web_search = prompt_request.web_search;
-    let web_search_max_results = prompt_request.web_search_max_results;
-    let reasoning_effort = prompt_request.reasoning_effort.clone();
-    let provider_route = model_route.provider.clone();
-
-    tauri::async_runtime::spawn(async move {
-        // Stream all new models concurrently using JoinSet
-        let mut join_set = tokio::task::JoinSet::new();
-
-        for model_id in model_ids {
-            let messages = messages.clone();
-            let system_prompt = system_prompt.clone();
-            let openrouter_arc = openrouter_arc.clone();
-            let window = window.clone();
-            let session_id = session_id.clone();
-            let tile_id = tile_id.clone();
-            let reasoning_effort = reasoning_effort.clone();
-            let provider_route = provider_route.clone();
-            let ollama_arc = ollama_arc.clone();
-
-            join_set.spawn(async move {
-                let stream_result = match provider_route {
-                    ModelProviderRoute::Ollama => {
-                        let ollama = ollama_arc.read().await;
-                        let result = ollama
-                            .chat_stream(&model_id, messages, system_prompt.as_deref(), Some(0.7))
-                            .await;
-                        drop(ollama);
-                        result.map(|stream| {
-                            Box::pin(stream)
-                                as std::pin::Pin<
-                                    Box<dyn futures::Stream<Item = anyhow::Result<String>> + Send>,
-                                >
-                        })
-                    }
-                    ModelProviderRoute::OpenRouter => {
-                        let openrouter = openrouter_arc.read().await;
-                        let result = openrouter
-                            .chat_stream(
-                                &model_id,
-                                messages,
-                                system_prompt.as_deref(),
-                                Some(0.7),
-                                None,
-                                Some(reasoning_effort.as_str()),
-                                web_search,
-                                web_search_max_results,
-                            )
-                            .await;
-                        drop(openrouter);
-                        result.map(|stream| {
-                            Box::pin(stream)
-                                as std::pin::Pin<
-                                    Box<dyn futures::Stream<Item = anyhow::Result<String>> + Send>,
-                                >
-                        })
-                    }
-                };
-
-                match stream_result {
-                    Ok(stream) => {
-                        let mut stream = stream;
-                        let mut full_content = String::new();
-
-                        loop {
-                            match tokio::time::timeout(Duration::from_secs(60), stream.next()).await
-                            {
-                                Ok(Some(Ok(chunk))) => {
-                                    if !chunk.is_empty() {
-                                        full_content.push_str(&chunk);
-                                        let _ = window.emit(
-                                            "canvas-stream",
-                                            CanvasStreamEvent::Chunk {
-                                                session_id: session_id.clone(),
-                                                tile_id: tile_id.clone(),
-                                                model_id: model_id.clone(),
-                                                chunk,
-                                            },
-                                        );
-                                    }
-                                }
-                                Ok(Some(Err(e))) => {
-                                    let error = e.to_string();
-                                    emit_canvas_error(
-                                        &window,
-                                        &session_id,
-                                        &tile_id,
-                                        &model_id,
-                                        &error,
-                                    );
-                                    return (
-                                        model_id,
-                                        String::new(),
-                                        ResponseStatus::Error,
-                                        Some(error),
-                                    );
-                                }
-                                Ok(None) => break,
-                                Err(_) => {
-                                    let error = "Stream idle timeout (60s)".to_string();
-                                    emit_canvas_error(
-                                        &window,
-                                        &session_id,
-                                        &tile_id,
-                                        &model_id,
-                                        &error,
-                                    );
-                                    return (
-                                        model_id,
-                                        full_content,
-                                        ResponseStatus::Error,
-                                        Some(error),
-                                    );
-                                }
-                            }
-                        }
-
-                        finalize_streamed_model_response(
-                            &window,
-                            &session_id,
-                            &tile_id,
-                            model_id,
-                            full_content,
-                        )
-                    }
-                    Err(e) => {
-                        let error = e.to_string();
-                        emit_canvas_error(&window, &session_id, &tile_id, &model_id, &error);
-                        (model_id, String::new(), ResponseStatus::Error, Some(error))
-                    }
-                }
-            });
-        }
-
-        // Wait for all models and collect results
-        let mut results = Vec::new();
-        while let Some(result) = join_set.join_next().await {
-            if let Ok(r) = result {
-                results.push(r);
-            }
-        }
-
-        // Batch update store
-        let persistence_ok = {
-            let mut store = canvas_store_arc.write().await;
-            match store.batch_update_tile_responses(&session_id, &tile_id, &results) {
-                Ok(()) => true,
-                Err(error) => {
-                    let model_ids: Vec<String> = results
-                        .iter()
-                        .map(|(model_id, _, _, _)| model_id.clone())
-                        .collect();
-                    emit_persistence_error(&window, &session_id, &tile_id, &model_ids, &error);
-                    false
-                }
-            }
-        };
-
-        append_canvas_trace(
-            twin_store_arc.clone(),
-            &session_id,
-            TraceEventType::ModelsAdded,
-            json!({
-                "tile_id": tile_id.clone(),
-                "model_ids": results.iter().map(|(model_id, _, _, _)| model_id.clone()).collect::<Vec<_>>(),
-            }),
-        )
-        .await;
-        append_model_result_traces(
-            twin_store_arc.clone(),
-            &session_id,
-            &tile_id,
-            "add_models_to_tile",
-            &results,
-        )
-        .await;
-
-        if persistence_ok {
-            let _ = window.emit(
-                "canvas-stream",
-                CanvasStreamEvent::SessionSaved { session_id },
-            );
-        }
-    });
-
-    Ok(())
-}
-
-/// Regenerate a single model's response
-#[tauri::command]
-pub async fn regenerate_response(
-    window: tauri::Window,
-    session_id: String,
-    tile_id: String,
-    model_id: String,
-    state: State<'_, AppState>,
-) -> Result<(), String> {
-    // Get the tile's prompt
-    let mut store = state.canvas_store.write().await;
-    let session = store.get_session(&session_id).map_err(|e| e.to_string())?;
-    drop(store);
-
-    let tile = session
-        .prompt_tiles
-        .iter()
-        .find(|t| t.id == tile_id)
-        .ok_or_else(|| "Tile not found".to_string())?;
-
-    let model_route = {
-        let settings = state.settings_service.read().await;
-        resolve_model_route(
-            &tile.prompt_type,
-            &tile.context_mode,
-            tile.twin_llm_provider.as_deref(),
-            settings.get(),
-        )?
-    };
-    let effective_model_id = effective_model_ids(&model_route, std::slice::from_ref(&model_id))
-        .into_iter()
-        .next()
-        .unwrap_or_else(|| model_id.clone());
-
-    if !tile.responses.contains_key(&effective_model_id) {
-        return Err("Response not found".to_string());
-    }
-
-    let request = prompt_request_from_tile(tile, vec![effective_model_id.clone()], 0.7);
-    let resolved_context = resolve_prompt_context(state.inner(), &session, &request).await?;
-
-    // Reset response to streaming
-    {
-        let mut store = state.canvas_store.write().await;
-        let _ = store.update_tile_response(
-            &session_id,
-            &tile_id,
-            &effective_model_id,
-            "",
-            ResponseStatus::Streaming,
-            None,
-        );
-    }
-
-    let openrouter_arc = state.openrouter.clone();
-    let ollama_arc = state.ollama.clone();
-    let canvas_store_arc = state.canvas_store.clone();
-    let twin_store_arc = state.twin_store.clone();
-    let messages = resolved_context.messages.clone();
-    let system_prompt = resolved_context.system_prompt.clone();
-    let web_search = request.web_search;
-    let web_search_max_results = request.web_search_max_results;
-    let reasoning_effort = request.reasoning_effort.clone();
-    let provider_route = model_route.provider.clone();
-
-    tauri::async_runtime::spawn(async move {
-        let model_id = effective_model_id;
-        let stream_result = match provider_route {
-            ModelProviderRoute::Ollama => {
-                let ollama = ollama_arc.read().await;
-                let result = ollama
-                    .chat_stream(&model_id, messages, system_prompt.as_deref(), Some(0.7))
-                    .await;
-                drop(ollama);
-                result.map(|stream| {
-                    Box::pin(stream)
-                        as std::pin::Pin<
-                            Box<dyn futures::Stream<Item = anyhow::Result<String>> + Send>,
-                        >
-                })
-            }
-            ModelProviderRoute::OpenRouter => {
-                let openrouter = openrouter_arc.read().await;
-                let result = openrouter
-                    .chat_stream(
-                        &model_id,
-                        messages,
-                        system_prompt.as_deref(),
-                        Some(0.7),
-                        None,
-                        Some(reasoning_effort.as_str()),
-                        web_search,
-                        web_search_max_results,
-                    )
-                    .await;
-                drop(openrouter);
-                result.map(|stream| {
-                    Box::pin(stream)
-                        as std::pin::Pin<
-                            Box<dyn futures::Stream<Item = anyhow::Result<String>> + Send>,
-                        >
-                })
-            }
-        };
-
-        let mut persistence_ok = true;
-
-        match stream_result {
-            Ok(stream) => {
-                let mut stream = stream;
-                let mut full_content = String::new();
-                let mut final_error: Option<String> = None;
-
-                loop {
-                    match tokio::time::timeout(Duration::from_secs(60), stream.next()).await {
-                        Ok(Some(Ok(chunk))) => {
-                            if !chunk.is_empty() {
-                                full_content.push_str(&chunk);
-                                let _ = window.emit(
-                                    "canvas-stream",
-                                    CanvasStreamEvent::Chunk {
-                                        session_id: session_id.clone(),
-                                        tile_id: tile_id.clone(),
-                                        model_id: model_id.clone(),
-                                        chunk,
-                                    },
-                                );
-                            }
-                        }
-                        Ok(Some(Err(e))) => {
-                            let error = e.to_string();
-                            emit_canvas_error(&window, &session_id, &tile_id, &model_id, &error);
-                            final_error = Some(error);
-                            break;
-                        }
-                        Ok(None) => break, // Stream ended naturally
-                        Err(_) => {
-                            let error = "Stream idle timeout (60s)".to_string();
-                            emit_canvas_error(&window, &session_id, &tile_id, &model_id, &error);
-                            final_error = Some(error);
-                            break;
-                        }
-                    }
-                }
-
-                let (final_content, final_status) = if final_error.is_some() {
-                    (full_content, ResponseStatus::Error)
-                } else {
-                    let update =
-                        classify_streamed_model_response(model_id.clone(), full_content.clone());
-                    final_error = update.3.clone();
-                    if let Some(error) = final_error.as_deref() {
-                        emit_canvas_error(&window, &session_id, &tile_id, &model_id, error);
-                    } else {
-                        emit_canvas_complete(&window, &session_id, &tile_id, &model_id);
-                    }
-                    (update.1, update.2)
-                };
-
-                {
-                    let mut store = canvas_store_arc.write().await;
-                    if let Err(persist_error) = store.update_tile_response(
-                        &session_id,
-                        &tile_id,
-                        &model_id,
-                        &final_content,
-                        final_status.clone(),
-                        final_error.as_deref(),
-                    ) {
-                        emit_persistence_error(
-                            &window,
-                            &session_id,
-                            &tile_id,
-                            std::slice::from_ref(&model_id),
-                            &persist_error,
-                        );
-                        persistence_ok = false;
-                    }
-                }
-
-                append_canvas_trace(
-                    twin_store_arc.clone(),
-                    &session_id,
-                    TraceEventType::ResponseRegenerated,
-                    json!({
-                        "tile_id": tile_id.clone(),
-                        "model_id": model_id.clone(),
-                        "status": final_status,
-                        "error": final_error.clone(),
-                        "content": final_content.clone(),
-                    }),
-                )
-                .await;
-            }
-            Err(e) => {
-                let error = e.to_string();
-                {
-                    let mut store = canvas_store_arc.write().await;
-                    if let Err(persist_error) = store.update_tile_response(
-                        &session_id,
-                        &tile_id,
-                        &model_id,
-                        "",
-                        ResponseStatus::Error,
-                        Some(error.as_str()),
-                    ) {
-                        emit_persistence_error(
-                            &window,
-                            &session_id,
-                            &tile_id,
-                            std::slice::from_ref(&model_id),
-                            &persist_error,
-                        );
-                        persistence_ok = false;
-                    }
-                }
-                emit_canvas_error(&window, &session_id, &tile_id, &model_id, &error);
-                append_canvas_trace(
-                    twin_store_arc.clone(),
-                    &session_id,
-                    TraceEventType::ResponseRegenerated,
-                    json!({
-                        "tile_id": tile_id.clone(),
-                        "model_id": model_id.clone(),
-                        "status": ResponseStatus::Error,
-                        "error": error,
-                        "content": "",
-                    }),
-                )
-                .await;
-            }
-        }
-
-        if persistence_ok {
-            let _ = window.emit(
-                "canvas-stream",
-                CanvasStreamEvent::SessionSaved { session_id },
-            );
-        }
-    });
-
-    Ok(())
-}
-
-fn prompt_request_from_tile(
-    tile: &PromptTile,
-    models: Vec<String>,
-    temperature: f64,
-) -> PromptRequest {
-    PromptRequest {
-        prompt: tile.prompt.clone(),
-        prompt_type: tile.prompt_type.clone(),
-        system_prompt: tile.system_prompt.clone(),
-        models,
-        position: None,
-        context_mode: tile.context_mode.clone(),
-        twin_answer_mode: tile.twin_answer_mode.clone(),
-        twin_context_policy: tile.twin_context_policy.clone(),
-        twin_llm_provider: tile.twin_llm_provider.clone(),
-        decision_metadata: tile.decision_metadata.clone(),
-        parent_tile_id: tile.parent_tile_id.clone(),
-        parent_model_id: tile.parent_model_id.clone(),
-        temperature,
-        max_tokens: None,
-        web_search: tile.web_search,
-        web_search_max_results: tile.web_search_max_results,
-        reasoning_effort: tile.reasoning_effort.clone(),
-    }
-}
-
-async fn append_model_result_traces(
-    twin_store_arc: Arc<RwLock<TwinStore>>,
-    session_id: &str,
-    tile_id: &str,
-    trigger: &str,
-    results: &[StreamedResponseUpdate],
-) {
-    for (model_id, content, status, error) in results {
-        let event_type = if *status == ResponseStatus::Error {
-            TraceEventType::ResponseErrored
-        } else {
-            TraceEventType::ResponseCompleted
-        };
-
-        append_canvas_trace(
-            twin_store_arc.clone(),
-            session_id,
-            event_type,
-            json!({
-                "tile_id": tile_id,
-                "model_id": model_id,
-                "trigger": trigger,
-                "status": status,
-                "content": content,
-                "error": error,
-            }),
-        )
-        .await;
-    }
-}
-
-fn emit_canvas_error(
-    window: &tauri::Window,
-    session_id: &str,
-    tile_id: &str,
-    model_id: &str,
-    error: &str,
-) {
-    let _ = window.emit(
-        "canvas-stream",
-        CanvasStreamEvent::Error {
-            session_id: session_id.to_string(),
-            tile_id: tile_id.to_string(),
-            model_id: model_id.to_string(),
-            error: error.to_string(),
-        },
-    );
-}
-
-/// Emit an Error event for every model whose response was streamed
-/// successfully but then failed to persist to the session file (disk full,
-/// file locked, etc.). Without this, the frontend has already rendered a
-/// complete response, `SessionSaved` would otherwise still fire, and the
-/// content silently reverts to an empty Pending stub the next time the
-/// session is reopened — with no error anywhere in the UI.
-fn emit_persistence_error(
-    window: &tauri::Window,
-    session_id: &str,
-    tile_id: &str,
-    model_ids: &[String],
-    error: &anyhow::Error,
-) {
-    log::error!(
-        "Failed to persist canvas tile '{}' responses for session '{}': {}",
-        tile_id,
-        session_id,
-        error
-    );
-
-    let message = format!("Failed to save response: {}", error);
-    for model_id in model_ids {
-        emit_canvas_error(window, session_id, tile_id, model_id, &message);
-    }
-}
-
 /// Same contract as `emit_persistence_error` but for debate rounds, which
 /// don't have a single tile/model — a round can involve several models at
 /// once. Emits a `DebateError` per participating model in the round that
@@ -2203,116 +1097,3 @@ fn emit_debate_persist_error(
         );
     }
 }
-
-fn emit_canvas_complete(window: &tauri::Window, session_id: &str, tile_id: &str, model_id: &str) {
-    let _ = window.emit(
-        "canvas-stream",
-        CanvasStreamEvent::Complete {
-            session_id: session_id.to_string(),
-            tile_id: tile_id.to_string(),
-            model_id: model_id.to_string(),
-            tokens_used: None,
-        },
-    );
-}
-
-fn finalize_streamed_model_response(
-    window: &tauri::Window,
-    session_id: &str,
-    tile_id: &str,
-    model_id: String,
-    full_content: String,
-) -> StreamedResponseUpdate {
-    let update = classify_streamed_model_response(model_id, full_content);
-
-    if let Some(error) = &update.3 {
-        emit_canvas_error(window, session_id, tile_id, &update.0, error);
-    } else {
-        emit_canvas_complete(window, session_id, tile_id, &update.0);
-    }
-
-    update
-}
-
-fn classify_streamed_model_response(
-    model_id: String,
-    full_content: String,
-) -> StreamedResponseUpdate {
-    if full_content.trim().is_empty() {
-        (
-            model_id,
-            String::new(),
-            ResponseStatus::Error,
-            Some(EMPTY_MODEL_RESPONSE_ERROR.to_string()),
-        )
-    } else {
-        (model_id, full_content, ResponseStatus::Completed, None)
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::commands::canvas::test_support::build_tile;
-    use crate::models::canvas::TwinAnswerMode;
-
-    #[test]
-    fn test_prompt_request_from_tile_preserves_web_search_settings() {
-        let tile = PromptTile {
-            web_search: true,
-            web_search_max_results: 8,
-            reasoning_effort: "high".to_string(),
-            ..build_tile("tile-1", "Prompt", "openai/gpt-4", "Response", None, None)
-        };
-
-        let request = prompt_request_from_tile(&tile, vec!["openai/gpt-4".to_string()], 0.3);
-
-        assert!(request.web_search);
-        assert_eq!(request.web_search_max_results, 8);
-        assert_eq!(request.temperature, 0.3);
-        assert_eq!(request.max_tokens, None);
-        assert_eq!(request.reasoning_effort, "high");
-    }
-
-    #[test]
-    fn test_prompt_request_from_tile_preserves_twin_settings() {
-        let tile = PromptTile {
-            context_mode: ContextMode::Twin,
-            twin_answer_mode: TwinAnswerMode::Simulation,
-            twin_context_policy: Some("approved_plus_relevant_candidates".to_string()),
-            twin_llm_provider: Some("ollama".to_string()),
-            ..build_tile("tile-1", "Prompt", "openai/gpt-4", "Response", None, None)
-        };
-
-        let request = prompt_request_from_tile(&tile, vec!["openai/gpt-4".to_string()], 0.7);
-
-        assert_eq!(request.context_mode, ContextMode::Twin);
-        assert_eq!(request.twin_answer_mode, TwinAnswerMode::Simulation);
-        assert_eq!(
-            request.twin_context_policy.as_deref(),
-            Some("approved_plus_relevant_candidates")
-        );
-        assert_eq!(request.twin_llm_provider.as_deref(), Some("ollama"));
-    }
-
-    #[test]
-    fn test_classify_streamed_model_response_rejects_empty_content() {
-        let update =
-            classify_streamed_model_response("openai/gpt-4".to_string(), "   \n\t".to_string());
-
-        assert_eq!(update.0, "openai/gpt-4");
-        assert_eq!(update.1, "");
-        assert_eq!(update.2, ResponseStatus::Error);
-        assert_eq!(update.3.as_deref(), Some(EMPTY_MODEL_RESPONSE_ERROR));
-    }
-
-    #[test]
-    fn test_classify_streamed_model_response_accepts_non_empty_content() {
-        let update =
-            classify_streamed_model_response("openai/gpt-4".to_string(), "Answer".to_string());
-
-        assert_eq!(update.2, ResponseStatus::Completed);
-        assert_eq!(update.3, None);
-        assert_eq!(update.1, "Answer");
-    }
-}
diff --git a/frontend/src-tauri/src/commands/canvas/streaming.rs b/frontend/src-tauri/src/commands/canvas/streaming.rs
new file mode 100644
index 0000000..0d4f4f7
--- /dev/null
+++ b/frontend/src-tauri/src/commands/canvas/streaming.rs
@@ -0,0 +1,1237 @@
+use super::context::{resolve_prompt_context, run_sealed_twin_prediction, TWIN_CONTEXT_VERSION};
+use super::shared::{
+    append_canvas_trace, effective_model_ids, resolve_model_route, ModelProviderRoute,
+};
+use crate::models::canvas::{
+    AddModelsRequest, CanvasStreamEvent, ModelResponse, PromptRequest, PromptTile, PromptType,
+    ResponseStatus, TilePosition,
+};
+use crate::models::twin::{
+    DecisionEpisodeCreate, PrimitiveDecisionAssessment, ReflectionCardCreate, TraceEventType,
+};
+use crate::services::twin_store::TwinStore;
+use crate::AppState;
+use chrono::Utc;
+use futures::StreamExt;
+use serde_json::json;
+use std::collections::HashMap;
+use std::sync::Arc;
+use std::time::Duration;
+use tauri::State;
+use tokio::sync::RwLock;
+
+const EMPTY_MODEL_RESPONSE_ERROR: &str = "No response returned from model";
+
+// LLM node layout constants
+const LLM_NODE_WIDTH: f64 = 280.0;
+const LLM_NODE_HEIGHT: f64 = 200.0;
+const LLM_NODE_Y_STEP: f64 = 300.0; // height(200) + 100px gap for content overflow
+const LLM_NODE_X_GAP: f64 = 80.0;
+
+type StreamedResponseUpdate = (String, String, ResponseStatus, Option<String>);
+
+/// Send a prompt to multiple models with streaming responses via Tauri events.
+/// Returns the tile_id immediately; actual responses stream via "canvas-stream" events.
+#[tauri::command]
+pub async fn send_prompt(
+    window: tauri::Window,
+    session_id: String,
+    mut request: PromptRequest,
+    state: State<'_, AppState>,
+) -> Result<String, String> {
+    let tile_id = uuid::Uuid::new_v4().to_string();
+    let now = Utc::now();
+    let model_route = {
+        let settings = state.settings_service.read().await;
+        resolve_model_route(
+            &request.prompt_type,
+            &request.context_mode,
+            request.twin_llm_provider.as_deref(),
+            settings.get(),
+        )?
+    };
+    request.models = effective_model_ids(&model_route, &request.models);
+    let session = {
+        let mut store = state.canvas_store.write().await;
+        store.get_session(&session_id).map_err(|e| e.to_string())?
+    };
+    let resolved_context = resolve_prompt_context(state.inner(), &session, &request).await?;
+    let decision_episode_id = if request.prompt_type == PromptType::Decision {
+        Some(uuid::Uuid::new_v4().to_string())
+    } else {
+        None
+    };
+
+    // Compute LLM node positions (offset from prompt tile)
+    let prompt_pos = request.position.clone().unwrap_or_default();
+    let llm_start_x = prompt_pos.x + prompt_pos.width + LLM_NODE_X_GAP;
+
+    // Create initial responses map with positions
+    let mut responses: HashMap<String, ModelResponse> = HashMap::new();
+    for (i, model_id) in request.models.iter().enumerate() {
+        let model_name = model_id.split('/').last().unwrap_or(model_id).to_string();
+        let llm_y = prompt_pos.y + (i as f64) * LLM_NODE_Y_STEP;
+        responses.insert(
+            model_id.clone(),
+            ModelResponse {
+                id: uuid::Uuid::new_v4().to_string(),
+                model_id: model_id.clone(),
+                model_name,
+                content: String::new(),
+                status: ResponseStatus::Pending,
+                error: None,
+                tokens_used: None,
+                created_at: now,
+                position: TilePosition {
+                    x: llm_start_x,
+                    y: llm_y,
+                    width: LLM_NODE_WIDTH,
+                    height: LLM_NODE_HEIGHT,
+                },
+            },
+        );
+    }
+
+    // Create the tile (with context notes attached)
+    let tile = PromptTile {
+        id: tile_id.clone(),
+        prompt_type: request.prompt_type.clone(),
+        prompt: request.prompt.clone(),
+        system_prompt: request.system_prompt.clone(),
+        models: request.models.clone(),
+        responses: responses.clone(),
+        position: prompt_pos,
+        created_at: now,
+        context_mode: request.context_mode,
+        parent_tile_id: request.parent_tile_id,
+        parent_model_id: request.parent_model_id,
+        context_notes: resolved_context.context_notes.clone(),
+        approved_twin_records: resolved_context.approved_twin_records.clone(),
+        candidate_twin_records: resolved_context.candidate_twin_records.clone(),
+        twin_answer_mode: request.twin_answer_mode.clone(),
+        twin_context_policy: request.twin_context_policy.clone(),
+        twin_llm_provider: request.twin_llm_provider.clone(),
+        decision_metadata: request.decision_metadata.clone(),
+        decision_episode_id: decision_episode_id.clone(),
+        web_search: request.web_search,
+        web_search_max_results: request.web_search_max_results,
+        reasoning_effort: request.reasoning_effort.clone(),
+    };
+
+    // Save tile to session
+    {
+        let mut store = state.canvas_store.write().await;
+        store
+            .add_tile(&session_id, tile.clone())
+            .map_err(|e| e.to_string())?;
+    }
+
+    if let Some(decision_episode_id) = decision_episode_id.clone() {
+        let decision_metadata = request.decision_metadata.clone().unwrap_or_default();
+        let decision = if decision_metadata.decision.trim().is_empty() {
+            request.prompt.clone()
+        } else {
+            decision_metadata.decision
+        };
+        let mut twin_store = state.twin_store.write().await;
+        twin_store
+            .record_decision_episode(DecisionEpisodeCreate {
+                id: decision_episode_id,
+                session_id: session_id.clone(),
+                tile_id: tile_id.clone(),
+                decision,
+                options: decision_metadata.options,
+                stakes: decision_metadata.stakes,
+                initial_leaning: decision_metadata.initial_leaning,
+                review_date: decision_metadata.review_date,
+                primitive_assessment: PrimitiveDecisionAssessment::default(),
+                // Stamped on every decision episode — including non-Twin
+                // context tiles — so attribution survives a failed or absent
+                // hidden prediction call.
+                context_version: Some(
+                    resolved_context
+                        .context_version
+                        .clone()
+                        .unwrap_or_else(|| TWIN_CONTEXT_VERSION.to_string()),
+                ),
+            })
+            .map_err(|error| error.to_string())?;
+    }
+
+    append_canvas_trace(
+        state.twin_store.clone(),
+        &session_id,
+        TraceEventType::PromptSubmitted,
+        json!({
+            "tile_id": tile.id.clone(),
+            "prompt_type": tile.prompt_type.clone(),
+            "decision_episode_id": tile.decision_episode_id.clone(),
+            "decision_metadata": tile.decision_metadata.clone(),
+            "prompt": tile.prompt.clone(),
+            "models": tile.models.clone(),
+            "context_mode": tile.context_mode.clone(),
+            "parent_tile_id": tile.parent_tile_id.clone(),
+            "parent_model_id": tile.parent_model_id.clone(),
+            "context_note_ids": tile.context_notes.iter().map(|note| note.id.clone()).collect::<Vec<_>>(),
+            "twin_answer_mode": tile.twin_answer_mode.clone(),
+            "approved_twin_record_ids": tile.approved_twin_records.iter().map(|record| record.id.clone()).collect::<Vec<_>>(),
+            "candidate_twin_record_ids": tile.candidate_twin_records.iter().map(|record| record.id.clone()).collect::<Vec<_>>(),
+            "constitution_item_ids": resolved_context.constitution_items.iter().map(|item| item.id.clone()).collect::<Vec<_>>(),
+            "action_gap_ids": resolved_context.action_gaps.iter().map(|gap| gap.id.clone()).collect::<Vec<_>>(),
+            "context_version": resolved_context.context_version.clone(),
+            "decision_case_ids": resolved_context.decision_case_ids.clone(),
+            "web_search": tile.web_search,
+            "web_search_max_results": tile.web_search_max_results,
+        }),
+    )
+    .await;
+
+    // Emit TileCreated event
+    let _ = window.emit(
+        "canvas-stream",
+        CanvasStreamEvent::TileCreated {
+            session_id: session_id.clone(),
+            tile: tile.clone(),
+        },
+    );
+
+    // Emit ContextNotes event (so frontend can display which notes were used)
+    if !resolved_context.context_notes.is_empty() {
+        let _ = window.emit(
+            "canvas-stream",
+            CanvasStreamEvent::ContextNotes {
+                session_id: session_id.clone(),
+                tile_id: tile_id.clone(),
+                notes: resolved_context.context_notes.clone(),
+            },
+        );
+    }
+
+    // Clone what we need for the spawned task
+    let openrouter_arc = state.openrouter.clone();
+    let ollama_arc = state.ollama.clone();
+    let canvas_store_arc = state.canvas_store.clone();
+    let twin_store_arc = state.twin_store.clone();
+    let models = request.models.clone();
+    let messages = resolved_context.messages.clone();
+    let system_prompt = resolved_context.system_prompt.clone();
+    let temperature = request.temperature;
+    let web_search = request.web_search;
+    let web_search_max_results = request.web_search_max_results;
+    let reasoning_effort = request.reasoning_effort.clone();
+    let provider_route = model_route.provider.clone();
+    let tile_id_clone = tile_id.clone();
+    let session_id_clone = session_id.clone();
+    let decision_episode_id_for_reflection = tile.decision_episode_id.clone();
+    let reflection_note_ids = tile
+        .context_notes
+        .iter()
+        .map(|note| note.id.clone())
+        .collect::<Vec<_>>();
+    let reflection_user_record_ids = tile
+        .approved_twin_records
+        .iter()
+        .chain(tile.candidate_twin_records.iter())
+        .map(|record| record.id.clone())
+        .collect::<Vec<_>>();
+    let reflection_constitution_item_ids = resolved_context
+        .constitution_items
+        .iter()
+        .map(|item| item.id.clone())
+        .collect::<Vec<_>>();
+    let reflection_action_gap_ids = resolved_context
+        .action_gaps
+        .iter()
+        .map(|gap| gap.id.clone())
+        .collect::<Vec<_>>();
+
+    // Spawn async task for streaming (doesn't block the IPC response)
+    tauri::async_runtime::spawn(async move {
+        // Stream all models concurrently using JoinSet
+        let mut join_set = tokio::task::JoinSet::new();
+
+        for model_id in models {
+            let messages = messages.clone();
+            let system_prompt = system_prompt.clone();
+            let reasoning_effort = reasoning_effort.clone();
+            let provider_route = provider_route.clone();
+            let openrouter_arc = openrouter_arc.clone();
+            let ollama_arc = ollama_arc.clone();
+            let window = window.clone();
+            let session_id = session_id_clone.clone();
+            let tile_id = tile_id_clone.clone();
+
+            join_set.spawn(async move {
+                let stream_result = match provider_route {
+                    ModelProviderRoute::Ollama => {
+                        let ollama = ollama_arc.read().await;
+                        let result = ollama
+                            .chat_stream(
+                                &model_id,
+                                messages,
+                                system_prompt.as_deref(),
+                                Some(temperature),
+                            )
+                            .await;
+                        drop(ollama);
+                        result.map(|stream| {
+                            Box::pin(stream)
+                                as std::pin::Pin<
+                                    Box<dyn futures::Stream<Item = anyhow::Result<String>> + Send>,
+                                >
+                        })
+                    }
+                    ModelProviderRoute::OpenRouter => {
+                        let openrouter = openrouter_arc.read().await;
+                        let result = openrouter
+                            .chat_stream(
+                                &model_id,
+                                messages,
+                                system_prompt.as_deref(),
+                                Some(temperature),
+                                None,
+                                Some(reasoning_effort.as_str()),
+                                web_search,
+                                web_search_max_results,
+                            )
+                            .await;
+                        drop(openrouter);
+                        result.map(|stream| {
+                            Box::pin(stream)
+                                as std::pin::Pin<
+                                    Box<dyn futures::Stream<Item = anyhow::Result<String>> + Send>,
+                                >
+                        })
+                    }
+                };
+
+                match stream_result {
+                    Ok(stream) => {
+                        let mut stream = stream;
+                        let mut full_content = String::new();
+
+                        loop {
+                            match tokio::time::timeout(Duration::from_secs(60), stream.next()).await
+                            {
+                                Ok(Some(Ok(chunk))) => {
+                                    if !chunk.is_empty() {
+                                        full_content.push_str(&chunk);
+                                        let _ = window.emit(
+                                            "canvas-stream",
+                                            CanvasStreamEvent::Chunk {
+                                                session_id: session_id.clone(),
+                                                tile_id: tile_id.clone(),
+                                                model_id: model_id.clone(),
+                                                chunk,
+                                            },
+                                        );
+                                    }
+                                }
+                                Ok(Some(Err(e))) => {
+                                    let error = e.to_string();
+                                    emit_canvas_error(
+                                        &window,
+                                        &session_id,
+                                        &tile_id,
+                                        &model_id,
+                                        &error,
+                                    );
+                                    return (
+                                        model_id,
+                                        String::new(),
+                                        ResponseStatus::Error,
+                                        Some(error),
+                                    );
+                                }
+                                Ok(None) => break, // Stream ended naturally
+                                Err(_) => {
+                                    let error = "Stream idle timeout (60s)".to_string();
+                                    emit_canvas_error(
+                                        &window,
+                                        &session_id,
+                                        &tile_id,
+                                        &model_id,
+                                        &error,
+                                    );
+                                    return (
+                                        model_id,
+                                        full_content,
+                                        ResponseStatus::Error,
+                                        Some(error),
+                                    );
+                                }
+                            }
+                        }
+
+                        finalize_streamed_model_response(
+                            &window,
+                            &session_id,
+                            &tile_id,
+                            model_id,
+                            full_content,
+                        )
+                    }
+                    Err(e) => {
+                        let error = e.to_string();
+                        emit_canvas_error(&window, &session_id, &tile_id, &model_id, &error);
+                        (model_id, String::new(), ResponseStatus::Error, Some(error))
+                    }
+                }
+            });
+        }
+
+        // Wait for all models and collect results
+        let mut results = Vec::new();
+        while let Some(result) = join_set.join_next().await {
+            if let Ok(r) = result {
+                results.push(r);
+            }
+        }
+
+        // Batch update store with all results in a single write
+        let persistence_ok = {
+            let mut store = canvas_store_arc.write().await;
+            match store.batch_update_tile_responses(&session_id_clone, &tile_id_clone, &results) {
+                Ok(()) => true,
+                Err(error) => {
+                    let model_ids: Vec<String> = results
+                        .iter()
+                        .map(|(model_id, _, _, _)| model_id.clone())
+                        .collect();
+                    emit_persistence_error(
+                        &window,
+                        &session_id_clone,
+                        &tile_id_clone,
+                        &model_ids,
+                        &error,
+                    );
+                    false
+                }
+            }
+        };
+
+        append_model_result_traces(
+            twin_store_arc.clone(),
+            &session_id_clone,
+            &tile_id_clone,
+            "send_prompt",
+            &results,
+        )
+        .await;
+
+        if let Some(decision_episode_id) = decision_episode_id_for_reflection {
+            let mut twin_store = twin_store_arc.write().await;
+            for (model_id, content, status, _) in &results {
+                if *status != ResponseStatus::Completed || content.trim().is_empty() {
+                    continue;
+                }
+
+                let _ = twin_store.record_reflection_card(ReflectionCardCreate {
+                    decision_episode_id: decision_episode_id.clone(),
+                    session_id: session_id_clone.clone(),
+                    tile_id: tile_id_clone.clone(),
+                    model_id: model_id.clone(),
+                    content: content.clone(),
+                    cited_note_ids: reflection_note_ids.clone(),
+                    cited_user_record_ids: reflection_user_record_ids.clone(),
+                    cited_constitution_item_ids: reflection_constitution_item_ids.clone(),
+                    cited_action_gap_ids: reflection_action_gap_ids.clone(),
+                    evidence_packet: None,
+                });
+            }
+        }
+
+        // Emit session saved after all models complete — but only if the
+        // batch persist above actually succeeded. If it failed, per-model
+        // Error events were already emitted and the frontend must not
+        // believe the (in-memory only) responses were saved to disk.
+        if persistence_ok {
+            let _ = window.emit(
+                "canvas-stream",
+                CanvasStreamEvent::SessionSaved {
+                    session_id: session_id_clone,
+                },
+            );
+        }
+    });
+
+    // Sealed twin prediction: one hidden, non-streaming call per decision
+    // episode with at least two options. Fire-and-forget in its own task —
+    // it never emits canvas-stream events and cannot block or fail the
+    // visible flow above.
+    if let Some(episode_id) = tile.decision_episode_id.clone() {
+        let metadata = tile.decision_metadata.clone().unwrap_or_default();
+        if metadata.options.len() >= 2 {
+            let prediction_model = match model_route.provider {
+                ModelProviderRoute::Ollama => tile.models.first().cloned().unwrap_or_default(),
+                ModelProviderRoute::OpenRouter => {
+                    let settings = state.settings_service.read().await;
+                    settings.get().llm_model.clone()
+                }
+            };
+            let decision = if metadata.decision.trim().is_empty() {
+                tile.prompt.clone()
+            } else {
+                metadata.decision.clone()
+            };
+            let context_version = resolved_context
+                .context_version
+                .clone()
+                .unwrap_or_else(|| TWIN_CONTEXT_VERSION.to_string());
+            tauri::async_runtime::spawn(run_sealed_twin_prediction(
+                state.twin_store.clone(),
+                state.openrouter.clone(),
+                state.ollama.clone(),
+                model_route.provider.clone(),
+                prediction_model,
+                episode_id,
+                tile.prompt.clone(),
+                decision,
+                metadata.options.clone(),
+                metadata.stakes.clone(),
+                resolved_context.twin_context_prompt.clone(),
+                context_version,
+                tile.decision_metadata.clone(),
+            ));
+        }
+    }
+
+    Ok(tile_id)
+}
+
+/// Add new models to an existing tile (same prompt, new model responses)
+#[tauri::command]
+pub async fn add_models_to_tile(
+    window: tauri::Window,
+    session_id: String,
+    tile_id: String,
+    request: AddModelsRequest,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    // Get the tile's prompt
+    let mut store = state.canvas_store.write().await;
+    let session = store.get_session(&session_id).map_err(|e| e.to_string())?;
+    drop(store);
+
+    let tile = session
+        .prompt_tiles
+        .iter()
+        .find(|t| t.id == tile_id)
+        .ok_or_else(|| "Tile not found".to_string())?
+        .clone();
+    let model_route = {
+        let settings = state.settings_service.read().await;
+        resolve_model_route(
+            &tile.prompt_type,
+            &tile.context_mode,
+            tile.twin_llm_provider.as_deref(),
+            settings.get(),
+        )?
+    };
+    let model_ids = effective_model_ids(&model_route, &request.model_ids);
+    let prompt_request = prompt_request_from_tile(&tile, model_ids.clone(), 0.7);
+    let resolved_context = resolve_prompt_context(state.inner(), &session, &prompt_request).await?;
+
+    let now = Utc::now();
+
+    // Calculate positions for new models
+    let existing_count = tile.responses.len();
+    let prompt_pos = &tile.position;
+    let llm_start_x = prompt_pos.x + prompt_pos.width + LLM_NODE_X_GAP;
+
+    // Add initial pending responses and notify frontend before streaming
+    let mut new_responses: HashMap<String, ModelResponse> = HashMap::new();
+    {
+        let mut store = state.canvas_store.write().await;
+        let mut session = store.get_session(&session_id).map_err(|e| e.to_string())?;
+        if let Some(t) = session.prompt_tiles.iter_mut().find(|t| t.id == tile_id) {
+            for (i, model_id) in model_ids.iter().enumerate() {
+                let model_name = model_id.split('/').last().unwrap_or(model_id).to_string();
+                let llm_y = prompt_pos.y + ((existing_count + i) as f64) * LLM_NODE_Y_STEP;
+                let response = ModelResponse {
+                    id: uuid::Uuid::new_v4().to_string(),
+                    model_id: model_id.clone(),
+                    model_name,
+                    content: String::new(),
+                    status: ResponseStatus::Pending,
+                    error: None,
+                    tokens_used: None,
+                    created_at: now,
+                    position: TilePosition {
+                        x: llm_start_x,
+                        y: llm_y,
+                        width: LLM_NODE_WIDTH,
+                        height: LLM_NODE_HEIGHT,
+                    },
+                };
+                new_responses.insert(model_id.clone(), response.clone());
+                t.models.push(model_id.clone());
+                t.responses.insert(model_id.clone(), response);
+            }
+            session.updated_at = Utc::now();
+            store.save_session(&session).map_err(|e| e.to_string())?;
+        }
+    }
+
+    // Notify frontend about new responses before streaming starts
+    let _ = window.emit(
+        "canvas-stream",
+        CanvasStreamEvent::ModelsAdded {
+            session_id: session_id.clone(),
+            tile_id: tile_id.clone(),
+            responses: new_responses,
+        },
+    );
+
+    // Spawn streaming task
+    let openrouter_arc = state.openrouter.clone();
+    let ollama_arc = state.ollama.clone();
+    let canvas_store_arc = state.canvas_store.clone();
+    let twin_store_arc = state.twin_store.clone();
+    let messages = resolved_context.messages.clone();
+    let system_prompt = resolved_context.system_prompt.clone();
+    let web_search = prompt_request.web_search;
+    let web_search_max_results = prompt_request.web_search_max_results;
+    let reasoning_effort = prompt_request.reasoning_effort.clone();
+    let provider_route = model_route.provider.clone();
+
+    tauri::async_runtime::spawn(async move {
+        // Stream all new models concurrently using JoinSet
+        let mut join_set = tokio::task::JoinSet::new();
+
+        for model_id in model_ids {
+            let messages = messages.clone();
+            let system_prompt = system_prompt.clone();
+            let openrouter_arc = openrouter_arc.clone();
+            let window = window.clone();
+            let session_id = session_id.clone();
+            let tile_id = tile_id.clone();
+            let reasoning_effort = reasoning_effort.clone();
+            let provider_route = provider_route.clone();
+            let ollama_arc = ollama_arc.clone();
+
+            join_set.spawn(async move {
+                let stream_result = match provider_route {
+                    ModelProviderRoute::Ollama => {
+                        let ollama = ollama_arc.read().await;
+                        let result = ollama
+                            .chat_stream(&model_id, messages, system_prompt.as_deref(), Some(0.7))
+                            .await;
+                        drop(ollama);
+                        result.map(|stream| {
+                            Box::pin(stream)
+                                as std::pin::Pin<
+                                    Box<dyn futures::Stream<Item = anyhow::Result<String>> + Send>,
+                                >
+                        })
+                    }
+                    ModelProviderRoute::OpenRouter => {
+                        let openrouter = openrouter_arc.read().await;
+                        let result = openrouter
+                            .chat_stream(
+                                &model_id,
+                                messages,
+                                system_prompt.as_deref(),
+                                Some(0.7),
+                                None,
+                                Some(reasoning_effort.as_str()),
+                                web_search,
+                                web_search_max_results,
+                            )
+                            .await;
+                        drop(openrouter);
+                        result.map(|stream| {
+                            Box::pin(stream)
+                                as std::pin::Pin<
+                                    Box<dyn futures::Stream<Item = anyhow::Result<String>> + Send>,
+                                >
+                        })
+                    }
+                };
+
+                match stream_result {
+                    Ok(stream) => {
+                        let mut stream = stream;
+                        let mut full_content = String::new();
+
+                        loop {
+                            match tokio::time::timeout(Duration::from_secs(60), stream.next()).await
+                            {
+                                Ok(Some(Ok(chunk))) => {
+                                    if !chunk.is_empty() {
+                                        full_content.push_str(&chunk);
+                                        let _ = window.emit(
+                                            "canvas-stream",
+                                            CanvasStreamEvent::Chunk {
+                                                session_id: session_id.clone(),
+                                                tile_id: tile_id.clone(),
+                                                model_id: model_id.clone(),
+                                                chunk,
+                                            },
+                                        );
+                                    }
+                                }
+                                Ok(Some(Err(e))) => {
+                                    let error = e.to_string();
+                                    emit_canvas_error(
+                                        &window,
+                                        &session_id,
+                                        &tile_id,
+                                        &model_id,
+                                        &error,
+                                    );
+                                    return (
+                                        model_id,
+                                        String::new(),
+                                        ResponseStatus::Error,
+                                        Some(error),
+                                    );
+                                }
+                                Ok(None) => break,
+                                Err(_) => {
+                                    let error = "Stream idle timeout (60s)".to_string();
+                                    emit_canvas_error(
+                                        &window,
+                                        &session_id,
+                                        &tile_id,
+                                        &model_id,
+                                        &error,
+                                    );
+                                    return (
+                                        model_id,
+                                        full_content,
+                                        ResponseStatus::Error,
+                                        Some(error),
+                                    );
+                                }
+                            }
+                        }
+
+                        finalize_streamed_model_response(
+                            &window,
+                            &session_id,
+                            &tile_id,
+                            model_id,
+                            full_content,
+                        )
+                    }
+                    Err(e) => {
+                        let error = e.to_string();
+                        emit_canvas_error(&window, &session_id, &tile_id, &model_id, &error);
+                        (model_id, String::new(), ResponseStatus::Error, Some(error))
+                    }
+                }
+            });
+        }
+
+        // Wait for all models and collect results
+        let mut results = Vec::new();
+        while let Some(result) = join_set.join_next().await {
+            if let Ok(r) = result {
+                results.push(r);
+            }
+        }
+
+        // Batch update store
+        let persistence_ok = {
+            let mut store = canvas_store_arc.write().await;
+            match store.batch_update_tile_responses(&session_id, &tile_id, &results) {
+                Ok(()) => true,
+                Err(error) => {
+                    let model_ids: Vec<String> = results
+                        .iter()
+                        .map(|(model_id, _, _, _)| model_id.clone())
+                        .collect();
+                    emit_persistence_error(&window, &session_id, &tile_id, &model_ids, &error);
+                    false
+                }
+            }
+        };
+
+        append_canvas_trace(
+            twin_store_arc.clone(),
+            &session_id,
+            TraceEventType::ModelsAdded,
+            json!({
+                "tile_id": tile_id.clone(),
+                "model_ids": results.iter().map(|(model_id, _, _, _)| model_id.clone()).collect::<Vec<_>>(),
+            }),
+        )
+        .await;
+        append_model_result_traces(
+            twin_store_arc.clone(),
+            &session_id,
+            &tile_id,
+            "add_models_to_tile",
+            &results,
+        )
+        .await;
+
+        if persistence_ok {
+            let _ = window.emit(
+                "canvas-stream",
+                CanvasStreamEvent::SessionSaved { session_id },
+            );
+        }
+    });
+
+    Ok(())
+}
+
+/// Regenerate a single model's response
+#[tauri::command]
+pub async fn regenerate_response(
+    window: tauri::Window,
+    session_id: String,
+    tile_id: String,
+    model_id: String,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    // Get the tile's prompt
+    let mut store = state.canvas_store.write().await;
+    let session = store.get_session(&session_id).map_err(|e| e.to_string())?;
+    drop(store);
+
+    let tile = session
+        .prompt_tiles
+        .iter()
+        .find(|t| t.id == tile_id)
+        .ok_or_else(|| "Tile not found".to_string())?;
+
+    let model_route = {
+        let settings = state.settings_service.read().await;
+        resolve_model_route(
+            &tile.prompt_type,
+            &tile.context_mode,
+            tile.twin_llm_provider.as_deref(),
+            settings.get(),
+        )?
+    };
+    let effective_model_id = effective_model_ids(&model_route, std::slice::from_ref(&model_id))
+        .into_iter()
+        .next()
+        .unwrap_or_else(|| model_id.clone());
+
+    if !tile.responses.contains_key(&effective_model_id) {
+        return Err("Response not found".to_string());
+    }
+
+    let request = prompt_request_from_tile(tile, vec![effective_model_id.clone()], 0.7);
+    let resolved_context = resolve_prompt_context(state.inner(), &session, &request).await?;
+
+    // Reset response to streaming
+    {
+        let mut store = state.canvas_store.write().await;
+        let _ = store.update_tile_response(
+            &session_id,
+            &tile_id,
+            &effective_model_id,
+            "",
+            ResponseStatus::Streaming,
+            None,
+        );
+    }
+
+    let openrouter_arc = state.openrouter.clone();
+    let ollama_arc = state.ollama.clone();
+    let canvas_store_arc = state.canvas_store.clone();
+    let twin_store_arc = state.twin_store.clone();
+    let messages = resolved_context.messages.clone();
+    let system_prompt = resolved_context.system_prompt.clone();
+    let web_search = request.web_search;
+    let web_search_max_results = request.web_search_max_results;
+    let reasoning_effort = request.reasoning_effort.clone();
+    let provider_route = model_route.provider.clone();
+
+    tauri::async_runtime::spawn(async move {
+        let model_id = effective_model_id;
+        let stream_result = match provider_route {
+            ModelProviderRoute::Ollama => {
+                let ollama = ollama_arc.read().await;
+                let result = ollama
+                    .chat_stream(&model_id, messages, system_prompt.as_deref(), Some(0.7))
+                    .await;
+                drop(ollama);
+                result.map(|stream| {
+                    Box::pin(stream)
+                        as std::pin::Pin<
+                            Box<dyn futures::Stream<Item = anyhow::Result<String>> + Send>,
+                        >
+                })
+            }
+            ModelProviderRoute::OpenRouter => {
+                let openrouter = openrouter_arc.read().await;
+                let result = openrouter
+                    .chat_stream(
+                        &model_id,
+                        messages,
+                        system_prompt.as_deref(),
+                        Some(0.7),
+                        None,
+                        Some(reasoning_effort.as_str()),
+                        web_search,
+                        web_search_max_results,
+                    )
+                    .await;
+                drop(openrouter);
+                result.map(|stream| {
+                    Box::pin(stream)
+                        as std::pin::Pin<
+                            Box<dyn futures::Stream<Item = anyhow::Result<String>> + Send>,
+                        >
+                })
+            }
+        };
+
+        let mut persistence_ok = true;
+
+        match stream_result {
+            Ok(stream) => {
+                let mut stream = stream;
+                let mut full_content = String::new();
+                let mut final_error: Option<String> = None;
+
+                loop {
+                    match tokio::time::timeout(Duration::from_secs(60), stream.next()).await {
+                        Ok(Some(Ok(chunk))) => {
+                            if !chunk.is_empty() {
+                                full_content.push_str(&chunk);
+                                let _ = window.emit(
+                                    "canvas-stream",
+                                    CanvasStreamEvent::Chunk {
+                                        session_id: session_id.clone(),
+                                        tile_id: tile_id.clone(),
+                                        model_id: model_id.clone(),
+                                        chunk,
+                                    },
+                                );
+                            }
+                        }
+                        Ok(Some(Err(e))) => {
+                            let error = e.to_string();
+                            emit_canvas_error(&window, &session_id, &tile_id, &model_id, &error);
+                            final_error = Some(error);
+                            break;
+                        }
+                        Ok(None) => break, // Stream ended naturally
+                        Err(_) => {
+                            let error = "Stream idle timeout (60s)".to_string();
+                            emit_canvas_error(&window, &session_id, &tile_id, &model_id, &error);
+                            final_error = Some(error);
+                            break;
+                        }
+                    }
+                }
+
+                let (final_content, final_status) = if final_error.is_some() {
+                    (full_content, ResponseStatus::Error)
+                } else {
+                    let update =
+                        classify_streamed_model_response(model_id.clone(), full_content.clone());
+                    final_error = update.3.clone();
+                    if let Some(error) = final_error.as_deref() {
+                        emit_canvas_error(&window, &session_id, &tile_id, &model_id, error);
+                    } else {
+                        emit_canvas_complete(&window, &session_id, &tile_id, &model_id);
+                    }
+                    (update.1, update.2)
+                };
+
+                {
+                    let mut store = canvas_store_arc.write().await;
+                    if let Err(persist_error) = store.update_tile_response(
+                        &session_id,
+                        &tile_id,
+                        &model_id,
+                        &final_content,
+                        final_status.clone(),
+                        final_error.as_deref(),
+                    ) {
+                        emit_persistence_error(
+                            &window,
+                            &session_id,
+                            &tile_id,
+                            std::slice::from_ref(&model_id),
+                            &persist_error,
+                        );
+                        persistence_ok = false;
+                    }
+                }
+
+                append_canvas_trace(
+                    twin_store_arc.clone(),
+                    &session_id,
+                    TraceEventType::ResponseRegenerated,
+                    json!({
+                        "tile_id": tile_id.clone(),
+                        "model_id": model_id.clone(),
+                        "status": final_status,
+                        "error": final_error.clone(),
+                        "content": final_content.clone(),
+                    }),
+                )
+                .await;
+            }
+            Err(e) => {
+                let error = e.to_string();
+                {
+                    let mut store = canvas_store_arc.write().await;
+                    if let Err(persist_error) = store.update_tile_response(
+                        &session_id,
+                        &tile_id,
+                        &model_id,
+                        "",
+                        ResponseStatus::Error,
+                        Some(error.as_str()),
+                    ) {
+                        emit_persistence_error(
+                            &window,
+                            &session_id,
+                            &tile_id,
+                            std::slice::from_ref(&model_id),
+                            &persist_error,
+                        );
+                        persistence_ok = false;
+                    }
+                }
+                emit_canvas_error(&window, &session_id, &tile_id, &model_id, &error);
+                append_canvas_trace(
+                    twin_store_arc.clone(),
+                    &session_id,
+                    TraceEventType::ResponseRegenerated,
+                    json!({
+                        "tile_id": tile_id.clone(),
+                        "model_id": model_id.clone(),
+                        "status": ResponseStatus::Error,
+                        "error": error,
+                        "content": "",
+                    }),
+                )
+                .await;
+            }
+        }
+
+        if persistence_ok {
+            let _ = window.emit(
+                "canvas-stream",
+                CanvasStreamEvent::SessionSaved { session_id },
+            );
+        }
+    });
+
+    Ok(())
+}
+
+fn prompt_request_from_tile(
+    tile: &PromptTile,
+    models: Vec<String>,
+    temperature: f64,
+) -> PromptRequest {
+    PromptRequest {
+        prompt: tile.prompt.clone(),
+        prompt_type: tile.prompt_type.clone(),
+        system_prompt: tile.system_prompt.clone(),
+        models,
+        position: None,
+        context_mode: tile.context_mode.clone(),
+        twin_answer_mode: tile.twin_answer_mode.clone(),
+        twin_context_policy: tile.twin_context_policy.clone(),
+        twin_llm_provider: tile.twin_llm_provider.clone(),
+        decision_metadata: tile.decision_metadata.clone(),
+        parent_tile_id: tile.parent_tile_id.clone(),
+        parent_model_id: tile.parent_model_id.clone(),
+        temperature,
+        max_tokens: None,
+        web_search: tile.web_search,
+        web_search_max_results: tile.web_search_max_results,
+        reasoning_effort: tile.reasoning_effort.clone(),
+    }
+}
+
+async fn append_model_result_traces(
+    twin_store_arc: Arc<RwLock<TwinStore>>,
+    session_id: &str,
+    tile_id: &str,
+    trigger: &str,
+    results: &[StreamedResponseUpdate],
+) {
+    for (model_id, content, status, error) in results {
+        let event_type = if *status == ResponseStatus::Error {
+            TraceEventType::ResponseErrored
+        } else {
+            TraceEventType::ResponseCompleted
+        };
+
+        append_canvas_trace(
+            twin_store_arc.clone(),
+            session_id,
+            event_type,
+            json!({
+                "tile_id": tile_id,
+                "model_id": model_id,
+                "trigger": trigger,
+                "status": status,
+                "content": content,
+                "error": error,
+            }),
+        )
+        .await;
+    }
+}
+
+fn emit_canvas_error(
+    window: &tauri::Window,
+    session_id: &str,
+    tile_id: &str,
+    model_id: &str,
+    error: &str,
+) {
+    let _ = window.emit(
+        "canvas-stream",
+        CanvasStreamEvent::Error {
+            session_id: session_id.to_string(),
+            tile_id: tile_id.to_string(),
+            model_id: model_id.to_string(),
+            error: error.to_string(),
+        },
+    );
+}
+
+/// Emit an Error event for every model whose response was streamed
+/// successfully but then failed to persist to the session file (disk full,
+/// file locked, etc.). Without this, the frontend has already rendered a
+/// complete response, `SessionSaved` would otherwise still fire, and the
+/// content silently reverts to an empty Pending stub the next time the
+/// session is reopened — with no error anywhere in the UI.
+fn emit_persistence_error(
+    window: &tauri::Window,
+    session_id: &str,
+    tile_id: &str,
+    model_ids: &[String],
+    error: &anyhow::Error,
+) {
+    log::error!(
+        "Failed to persist canvas tile '{}' responses for session '{}': {}",
+        tile_id,
+        session_id,
+        error
+    );
+
+    let message = format!("Failed to save response: {}", error);
+    for model_id in model_ids {
+        emit_canvas_error(window, session_id, tile_id, model_id, &message);
+    }
+}
+
+fn emit_canvas_complete(window: &tauri::Window, session_id: &str, tile_id: &str, model_id: &str) {
+    let _ = window.emit(
+        "canvas-stream",
+        CanvasStreamEvent::Complete {
+            session_id: session_id.to_string(),
+            tile_id: tile_id.to_string(),
+            model_id: model_id.to_string(),
+            tokens_used: None,
+        },
+    );
+}
+
+fn finalize_streamed_model_response(
+    window: &tauri::Window,
+    session_id: &str,
+    tile_id: &str,
+    model_id: String,
+    full_content: String,
+) -> StreamedResponseUpdate {
+    let update = classify_streamed_model_response(model_id, full_content);
+
+    if let Some(error) = &update.3 {
+        emit_canvas_error(window, session_id, tile_id, &update.0, error);
+    } else {
+        emit_canvas_complete(window, session_id, tile_id, &update.0);
+    }
+
+    update
+}
+
+fn classify_streamed_model_response(
+    model_id: String,
+    full_content: String,
+) -> StreamedResponseUpdate {
+    if full_content.trim().is_empty() {
+        (
+            model_id,
+            String::new(),
+            ResponseStatus::Error,
+            Some(EMPTY_MODEL_RESPONSE_ERROR.to_string()),
+        )
+    } else {
+        (model_id, full_content, ResponseStatus::Completed, None)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::commands::canvas::test_support::build_tile;
+    use crate::models::canvas::{ContextMode, TwinAnswerMode};
+
+    #[test]
+    fn test_prompt_request_from_tile_preserves_web_search_settings() {
+        let tile = PromptTile {
+            web_search: true,
+            web_search_max_results: 8,
+            reasoning_effort: "high".to_string(),
+            ..build_tile("tile-1", "Prompt", "openai/gpt-4", "Response", None, None)
+        };
+
+        let request = prompt_request_from_tile(&tile, vec!["openai/gpt-4".to_string()], 0.3);
+
+        assert!(request.web_search);
+        assert_eq!(request.web_search_max_results, 8);
+        assert_eq!(request.temperature, 0.3);
+        assert_eq!(request.max_tokens, None);
+        assert_eq!(request.reasoning_effort, "high");
+    }
+
+    #[test]
+    fn test_prompt_request_from_tile_preserves_twin_settings() {
+        let tile = PromptTile {
+            context_mode: ContextMode::Twin,
+            twin_answer_mode: TwinAnswerMode::Simulation,
+            twin_context_policy: Some("approved_plus_relevant_candidates".to_string()),
+            twin_llm_provider: Some("ollama".to_string()),
+            ..build_tile("tile-1", "Prompt", "openai/gpt-4", "Response", None, None)
+        };
+
+        let request = prompt_request_from_tile(&tile, vec!["openai/gpt-4".to_string()], 0.7);
+
+        assert_eq!(request.context_mode, ContextMode::Twin);
+        assert_eq!(request.twin_answer_mode, TwinAnswerMode::Simulation);
+        assert_eq!(
+            request.twin_context_policy.as_deref(),
+            Some("approved_plus_relevant_candidates")
+        );
+        assert_eq!(request.twin_llm_provider.as_deref(), Some("ollama"));
+    }
+
+    #[test]
+    fn test_classify_streamed_model_response_rejects_empty_content() {
+        let update =
+            classify_streamed_model_response("openai/gpt-4".to_string(), "   \n\t".to_string());
+
+        assert_eq!(update.0, "openai/gpt-4");
+        assert_eq!(update.1, "");
+        assert_eq!(update.2, ResponseStatus::Error);
+        assert_eq!(update.3.as_deref(), Some(EMPTY_MODEL_RESPONSE_ERROR));
+    }
+
+    #[test]
+    fn test_classify_streamed_model_response_accepts_non_empty_content() {
+        let update =
+            classify_streamed_model_response("openai/gpt-4".to_string(), "Answer".to_string());
+
+        assert_eq!(update.2, ResponseStatus::Completed);
+        assert_eq!(update.3, None);
+        assert_eq!(update.1, "Answer");
+    }
+}

From 68ecce5305644a2875b976e1624e75389403c77d Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 14:40:48 +0800
Subject: [PATCH 05/30] refactor: extract canvas::debate

Move start_debate, continue_debate, and emit_debate_persist_error into
canvas::debate. Pure move; no logic changes. mod.rs now glob re-exports
debate's tauri commands for the same __cmd__ macro-visibility reason as
the streaming extraction.
---
 .../src-tauri/src/commands/canvas/debate.rs   | 785 +++++++++++++++++
 frontend/src-tauri/src/commands/canvas/mod.rs | 787 +-----------------
 2 files changed, 791 insertions(+), 781 deletions(-)
 create mode 100644 frontend/src-tauri/src/commands/canvas/debate.rs

diff --git a/frontend/src-tauri/src/commands/canvas/debate.rs b/frontend/src-tauri/src/commands/canvas/debate.rs
new file mode 100644
index 0000000..b07ac8c
--- /dev/null
+++ b/frontend/src-tauri/src/commands/canvas/debate.rs
@@ -0,0 +1,785 @@
+use super::shared::{
+    append_canvas_trace, effective_model_ids, resolve_model_route, source_tile_context_provider,
+    ModelProviderRoute,
+};
+use crate::models::canvas::{
+    CanvasStreamEvent, ContextMode, Debate, DebateContinueRequest, DebateResponse, DebateRound,
+    DebateStartRequest, PromptType, TilePosition,
+};
+use crate::models::twin::TraceEventType;
+use crate::services::openrouter::ChatMessage;
+use crate::AppState;
+use chrono::Utc;
+use futures::StreamExt;
+use serde_json::json;
+use std::time::Duration;
+use tauri::State;
+
+/// Start a debate between models with streaming via Tauri events
+#[tauri::command]
+pub async fn start_debate(
+    window: tauri::Window,
+    session_id: String,
+    mut request: DebateStartRequest,
+    state: State<'_, AppState>,
+) -> Result<String, String> {
+    let debate_id = uuid::Uuid::new_v4().to_string();
+    let now = Utc::now();
+
+    // Collect source content from tiles
+    let mut store = state.canvas_store.write().await;
+    let session = store.get_session(&session_id).map_err(|e| e.to_string())?;
+    drop(store);
+
+    let mut source_content = String::new();
+    let (source_has_vault_context, source_twin_provider) =
+        source_tile_context_provider(&session, &request.source_tile_ids);
+    let model_route = {
+        let settings = state.settings_service.read().await;
+        if source_has_vault_context {
+            resolve_model_route(
+                &PromptType::Decision,
+                &ContextMode::Twin,
+                source_twin_provider.as_deref(),
+                settings.get(),
+            )?
+        } else {
+            resolve_model_route(
+                &PromptType::Standard,
+                &ContextMode::KnowledgeSearch,
+                None,
+                settings.get(),
+            )?
+        }
+    };
+    request.participating_models = effective_model_ids(&model_route, &request.participating_models);
+    for tile_id in &request.source_tile_ids {
+        if let Some(tile) = session.prompt_tiles.iter().find(|t| &t.id == tile_id) {
+            source_content.push_str(&format!("Prompt: {}\n", tile.prompt));
+            for model_id in &request.participating_models {
+                if let Some(resp) = tile.responses.get(model_id) {
+                    source_content.push_str(&format!(
+                        "{} responded: {}\n",
+                        resp.model_name, resp.content
+                    ));
+                }
+            }
+        }
+    }
+
+    // Calculate position (to the right of source tiles)
+    let max_x = session
+        .prompt_tiles
+        .iter()
+        .flat_map(|t| {
+            t.responses
+                .values()
+                .map(|r| r.position.x + r.position.width)
+        })
+        .fold(0.0_f64, f64::max);
+
+    let debate = Debate {
+        id: debate_id.clone(),
+        participating_models: request.participating_models.clone(),
+        source_tile_ids: request.source_tile_ids.clone(),
+        rounds: Vec::new(),
+        status: "active".to_string(),
+        position: TilePosition {
+            x: max_x + 100.0,
+            y: 100.0,
+            width: 400.0,
+            height: 300.0,
+        },
+        debate_mode: request.debate_mode.clone(),
+        reasoning_effort: request.reasoning_effort.clone(),
+        created_at: now,
+    };
+
+    // Save debate to session
+    {
+        let mut store = state.canvas_store.write().await;
+        store
+            .add_debate(&session_id, debate.clone())
+            .map_err(|e| e.to_string())?;
+    }
+
+    append_canvas_trace(
+        state.twin_store.clone(),
+        &session_id,
+        TraceEventType::DebateStarted,
+        json!({
+            "debate_id": debate.id.clone(),
+            "source_tile_ids": debate.source_tile_ids.clone(),
+            "participating_models": debate.participating_models.clone(),
+            "debate_mode": debate.debate_mode.clone(),
+            "max_rounds": request.max_rounds,
+        }),
+    )
+    .await;
+
+    // Emit debate created
+    let _ = window.emit(
+        "canvas-stream",
+        CanvasStreamEvent::DebateCreated {
+            session_id: session_id.clone(),
+            debate: debate.clone(),
+        },
+    );
+
+    // Spawn async task for debate streaming
+    let openrouter_arc = state.openrouter.clone();
+    let ollama_arc = state.ollama.clone();
+    let canvas_store_arc = state.canvas_store.clone();
+    let models = request.participating_models.clone();
+    let max_rounds = request.max_rounds;
+    let reasoning_effort = request.reasoning_effort.clone();
+    let provider_route = model_route.provider.clone();
+    let debate_id_clone = debate_id.clone();
+    let session_id_clone = session_id.clone();
+
+    tauri::async_runtime::spawn(async move {
+        let mut debate_state = debate;
+
+        for round_num in 1..=max_rounds {
+            let _ = window.emit(
+                "canvas-stream",
+                CanvasStreamEvent::RoundStart {
+                    session_id: session_id_clone.clone(),
+                    debate_id: debate_id_clone.clone(),
+                    round_number: round_num,
+                },
+            );
+
+            // Build debate context
+            let mut context = format!(
+                "You are participating in a structured debate.\n\nOriginal context:\n{}\n\n",
+                source_content
+            );
+
+            // Add previous rounds for context
+            for prev_round in &debate_state.rounds {
+                context.push_str(&format!("Round {}:\n", prev_round.round_number));
+                for resp in &prev_round.responses {
+                    context.push_str(&format!("{}: {}\n", resp.model_name, resp.content));
+                }
+                context.push('\n');
+            }
+
+            context.push_str(&format!(
+                "Round {} - Present your analysis. Be concise and insightful. If other models have responded before you, engage with their points.",
+                round_num
+            ));
+
+            // Stream all models concurrently within this round using JoinSet
+            let mut join_set = tokio::task::JoinSet::new();
+
+            for model_id in models.clone() {
+                let model_name = model_id.split('/').last().unwrap_or(&model_id).to_string();
+                let messages = vec![ChatMessage {
+                    role: "user".to_string(),
+                    content: context.clone(),
+                }];
+                let openrouter_arc = openrouter_arc.clone();
+                let ollama_arc = ollama_arc.clone();
+                let window = window.clone();
+                let session_id = session_id_clone.clone();
+                let debate_id = debate_id_clone.clone();
+                let reasoning_effort = reasoning_effort.clone();
+                let provider_route = provider_route.clone();
+
+                join_set.spawn(async move {
+                    let stream_result = match provider_route {
+                        ModelProviderRoute::Ollama => {
+                            let ollama = ollama_arc.read().await;
+                            let result = ollama
+                                .chat_stream(&model_id, messages, None, Some(0.7))
+                                .await;
+                            drop(ollama);
+                            result.map(|stream| {
+                                Box::pin(stream)
+                                    as std::pin::Pin<
+                                        Box<
+                                            dyn futures::Stream<Item = anyhow::Result<String>>
+                                                + Send,
+                                        >,
+                                    >
+                            })
+                        }
+                        ModelProviderRoute::OpenRouter => {
+                            let openrouter = openrouter_arc.read().await;
+                            let result = openrouter
+                                .chat_stream(
+                                    &model_id,
+                                    messages,
+                                    None,
+                                    Some(0.7),
+                                    None,
+                                    Some(reasoning_effort.as_str()),
+                                    false,
+                                    5,
+                                )
+                                .await;
+                            drop(openrouter);
+                            result.map(|stream| {
+                                Box::pin(stream)
+                                    as std::pin::Pin<
+                                        Box<
+                                            dyn futures::Stream<Item = anyhow::Result<String>>
+                                                + Send,
+                                        >,
+                                    >
+                            })
+                        }
+                    };
+
+                    match stream_result {
+                        Ok(stream) => {
+                            let mut stream = stream;
+                            let mut full_content = String::new();
+
+                            loop {
+                                match tokio::time::timeout(Duration::from_secs(60), stream.next())
+                                    .await
+                                {
+                                    Ok(Some(Ok(chunk))) => {
+                                        if !chunk.is_empty() {
+                                            full_content.push_str(&chunk);
+                                            let _ = window.emit(
+                                                "canvas-stream",
+                                                CanvasStreamEvent::DebateChunk {
+                                                    session_id: session_id.clone(),
+                                                    debate_id: debate_id.clone(),
+                                                    model_id: model_id.clone(),
+                                                    chunk,
+                                                    round_number: round_num,
+                                                },
+                                            );
+                                        }
+                                    }
+                                    Ok(Some(Err(e))) => {
+                                        let _ = window.emit(
+                                            "canvas-stream",
+                                            CanvasStreamEvent::DebateError {
+                                                session_id: session_id.clone(),
+                                                debate_id: debate_id.clone(),
+                                                model_id: model_id.clone(),
+                                                error: e.to_string(),
+                                                round_number: round_num,
+                                            },
+                                        );
+                                        return DebateResponse {
+                                            model_id,
+                                            model_name,
+                                            content: full_content,
+                                            stance: None,
+                                        };
+                                    }
+                                    Ok(None) => break, // Stream ended naturally
+                                    Err(_) => {
+                                        let _ = window.emit(
+                                            "canvas-stream",
+                                            CanvasStreamEvent::DebateError {
+                                                session_id: session_id.clone(),
+                                                debate_id: debate_id.clone(),
+                                                model_id: model_id.clone(),
+                                                error: "Stream idle timeout (60s)".to_string(),
+                                                round_number: round_num,
+                                            },
+                                        );
+                                        return DebateResponse {
+                                            model_id,
+                                            model_name,
+                                            content: full_content,
+                                            stance: None,
+                                        };
+                                    }
+                                }
+                            }
+
+                            let _ = window.emit(
+                                "canvas-stream",
+                                CanvasStreamEvent::ModelComplete {
+                                    session_id: session_id.clone(),
+                                    debate_id: debate_id.clone(),
+                                    model_id: model_id.clone(),
+                                    round_number: round_num,
+                                },
+                            );
+
+                            DebateResponse {
+                                model_id,
+                                model_name,
+                                content: full_content,
+                                stance: None,
+                            }
+                        }
+                        Err(e) => {
+                            let _ = window.emit(
+                                "canvas-stream",
+                                CanvasStreamEvent::DebateError {
+                                    session_id: session_id.clone(),
+                                    debate_id: debate_id.clone(),
+                                    model_id: model_id.clone(),
+                                    error: e.to_string(),
+                                    round_number: round_num,
+                                },
+                            );
+                            let _ = window.emit(
+                                "canvas-stream",
+                                CanvasStreamEvent::ModelComplete {
+                                    session_id: session_id.clone(),
+                                    debate_id: debate_id.clone(),
+                                    model_id: model_id.clone(),
+                                    round_number: round_num,
+                                },
+                            );
+                            DebateResponse {
+                                model_id,
+                                model_name,
+                                content: e.to_string(),
+                                stance: None,
+                            }
+                        }
+                    }
+                });
+            }
+
+            // Collect all model responses from this round
+            let mut round_responses = Vec::new();
+            while let Some(result) = join_set.join_next().await {
+                if let Ok(response) = result {
+                    round_responses.push(response);
+                }
+            }
+
+            // Save round
+            let round = DebateRound {
+                round_number: round_num,
+                topic: format!("Round {}", round_num),
+                responses: round_responses,
+                created_at: Utc::now(),
+            };
+            debate_state.rounds.push(round);
+
+            // Persist after each round. If this fails, surface it instead of
+            // silently continuing to stream rounds that will never survive a
+            // session reopen.
+            let round_persisted = {
+                let mut store = canvas_store_arc.write().await;
+                match store.update_debate(&session_id_clone, &debate_state) {
+                    Ok(()) => true,
+                    Err(error) => {
+                        emit_debate_persist_error(
+                            &window,
+                            &session_id_clone,
+                            &debate_id_clone,
+                            round_num,
+                            &debate_state,
+                            &error,
+                        );
+                        false
+                    }
+                }
+            };
+
+            if !round_persisted {
+                return;
+            }
+        }
+
+        // Mark debate as complete
+        debate_state.status = "completed".to_string();
+        let final_round_number = debate_state
+            .rounds
+            .last()
+            .map(|round| round.round_number)
+            .unwrap_or(max_rounds);
+        let completion_persisted = {
+            let mut store = canvas_store_arc.write().await;
+            match store.update_debate(&session_id_clone, &debate_state) {
+                Ok(()) => true,
+                Err(error) => {
+                    emit_debate_persist_error(
+                        &window,
+                        &session_id_clone,
+                        &debate_id_clone,
+                        final_round_number,
+                        &debate_state,
+                        &error,
+                    );
+                    false
+                }
+            }
+        };
+
+        if completion_persisted {
+            let _ = window.emit(
+                "canvas-stream",
+                CanvasStreamEvent::DebateComplete {
+                    session_id: session_id_clone,
+                    debate_id: debate_id_clone,
+                },
+            );
+        }
+    });
+
+    Ok(debate_id)
+}
+
+/// Continue a debate with a new round
+#[tauri::command]
+pub async fn continue_debate(
+    window: tauri::Window,
+    session_id: String,
+    debate_id: String,
+    request: DebateContinueRequest,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    let mut store = state.canvas_store.write().await;
+    let session = store.get_session(&session_id).map_err(|e| e.to_string())?;
+    drop(store);
+
+    let debate = session
+        .debates
+        .iter()
+        .find(|d| d.id == debate_id)
+        .ok_or_else(|| "Debate not found".to_string())?
+        .clone();
+    let (source_has_vault_context, source_twin_provider) =
+        source_tile_context_provider(&session, &debate.source_tile_ids);
+    let model_route = {
+        let settings = state.settings_service.read().await;
+        if source_has_vault_context {
+            resolve_model_route(
+                &PromptType::Decision,
+                &ContextMode::Twin,
+                source_twin_provider.as_deref(),
+                settings.get(),
+            )?
+        } else {
+            resolve_model_route(
+                &PromptType::Standard,
+                &ContextMode::KnowledgeSearch,
+                None,
+                settings.get(),
+            )?
+        }
+    };
+
+    append_canvas_trace(
+        state.twin_store.clone(),
+        &session_id,
+        TraceEventType::DebateContinued,
+        json!({
+            "debate_id": debate_id.clone(),
+            "prompt": request.prompt.clone(),
+            "participating_models": debate.participating_models.clone(),
+        }),
+    )
+    .await;
+
+    let openrouter_arc = state.openrouter.clone();
+    let ollama_arc = state.ollama.clone();
+    let canvas_store_arc = state.canvas_store.clone();
+    let models = effective_model_ids(&model_route, &debate.participating_models);
+    let reasoning_effort = request.reasoning_effort.clone();
+    let provider_route = model_route.provider.clone();
+
+    tauri::async_runtime::spawn(async move {
+        let mut debate_state = debate;
+        let round_num = debate_state.rounds.len() as u32 + 1;
+
+        let _ = window.emit(
+            "canvas-stream",
+            CanvasStreamEvent::RoundStart {
+                session_id: session_id.clone(),
+                debate_id: debate_id.clone(),
+                round_number: round_num,
+            },
+        );
+
+        // Build context from previous rounds + new prompt
+        let mut context = String::from("Previous debate rounds:\n\n");
+        for round in &debate_state.rounds {
+            context.push_str(&format!("Round {}:\n", round.round_number));
+            for resp in &round.responses {
+                context.push_str(&format!("{}: {}\n", resp.model_name, resp.content));
+            }
+            context.push('\n');
+        }
+        context.push_str(&format!(
+            "New prompt: {}\n\nRespond to this new direction.",
+            request.prompt
+        ));
+
+        // Stream all models concurrently using JoinSet
+        let mut join_set = tokio::task::JoinSet::new();
+
+        for model_id in models {
+            let model_name = model_id.split('/').last().unwrap_or(&model_id).to_string();
+            let messages = vec![ChatMessage {
+                role: "user".to_string(),
+                content: context.clone(),
+            }];
+            let openrouter_arc = openrouter_arc.clone();
+            let ollama_arc = ollama_arc.clone();
+            let window = window.clone();
+            let session_id = session_id.clone();
+            let debate_id = debate_id.clone();
+            let reasoning_effort = reasoning_effort.clone();
+            let provider_route = provider_route.clone();
+
+            join_set.spawn(async move {
+                let stream_result = match provider_route {
+                    ModelProviderRoute::Ollama => {
+                        let ollama = ollama_arc.read().await;
+                        let result = ollama
+                            .chat_stream(&model_id, messages, None, Some(0.7))
+                            .await;
+                        drop(ollama);
+                        result.map(|stream| {
+                            Box::pin(stream)
+                                as std::pin::Pin<
+                                    Box<dyn futures::Stream<Item = anyhow::Result<String>> + Send>,
+                                >
+                        })
+                    }
+                    ModelProviderRoute::OpenRouter => {
+                        let openrouter = openrouter_arc.read().await;
+                        let result = openrouter
+                            .chat_stream(
+                                &model_id,
+                                messages,
+                                None,
+                                Some(0.7),
+                                None,
+                                Some(reasoning_effort.as_str()),
+                                false,
+                                5,
+                            )
+                            .await;
+                        drop(openrouter);
+                        result.map(|stream| {
+                            Box::pin(stream)
+                                as std::pin::Pin<
+                                    Box<dyn futures::Stream<Item = anyhow::Result<String>> + Send>,
+                                >
+                        })
+                    }
+                };
+
+                match stream_result {
+                    Ok(stream) => {
+                        let mut stream = stream;
+                        let mut full_content = String::new();
+
+                        loop {
+                            match tokio::time::timeout(Duration::from_secs(60), stream.next()).await
+                            {
+                                Ok(Some(Ok(chunk))) => {
+                                    if !chunk.is_empty() {
+                                        full_content.push_str(&chunk);
+                                        let _ = window.emit(
+                                            "canvas-stream",
+                                            CanvasStreamEvent::DebateChunk {
+                                                session_id: session_id.clone(),
+                                                debate_id: debate_id.clone(),
+                                                model_id: model_id.clone(),
+                                                chunk,
+                                                round_number: round_num,
+                                            },
+                                        );
+                                    }
+                                }
+                                Ok(Some(Err(e))) => {
+                                    let _ = window.emit(
+                                        "canvas-stream",
+                                        CanvasStreamEvent::DebateError {
+                                            session_id: session_id.clone(),
+                                            debate_id: debate_id.clone(),
+                                            model_id: model_id.clone(),
+                                            error: e.to_string(),
+                                            round_number: round_num,
+                                        },
+                                    );
+                                    return DebateResponse {
+                                        model_id,
+                                        model_name,
+                                        content: full_content,
+                                        stance: None,
+                                    };
+                                }
+                                Ok(None) => break, // Stream ended naturally
+                                Err(_) => {
+                                    let _ = window.emit(
+                                        "canvas-stream",
+                                        CanvasStreamEvent::DebateError {
+                                            session_id: session_id.clone(),
+                                            debate_id: debate_id.clone(),
+                                            model_id: model_id.clone(),
+                                            error: "Stream idle timeout (60s)".to_string(),
+                                            round_number: round_num,
+                                        },
+                                    );
+                                    return DebateResponse {
+                                        model_id,
+                                        model_name,
+                                        content: full_content,
+                                        stance: None,
+                                    };
+                                }
+                            }
+                        }
+
+                        let _ = window.emit(
+                            "canvas-stream",
+                            CanvasStreamEvent::ModelComplete {
+                                session_id: session_id.clone(),
+                                debate_id: debate_id.clone(),
+                                model_id: model_id.clone(),
+                                round_number: round_num,
+                            },
+                        );
+
+                        DebateResponse {
+                            model_id,
+                            model_name,
+                            content: full_content,
+                            stance: None,
+                        }
+                    }
+                    Err(e) => {
+                        let _ = window.emit(
+                            "canvas-stream",
+                            CanvasStreamEvent::DebateError {
+                                session_id: session_id.clone(),
+                                debate_id: debate_id.clone(),
+                                model_id: model_id.clone(),
+                                error: e.to_string(),
+                                round_number: round_num,
+                            },
+                        );
+                        let _ = window.emit(
+                            "canvas-stream",
+                            CanvasStreamEvent::ModelComplete {
+                                session_id: session_id.clone(),
+                                debate_id: debate_id.clone(),
+                                model_id: model_id.clone(),
+                                round_number: round_num,
+                            },
+                        );
+                        DebateResponse {
+                            model_id,
+                            model_name,
+                            content: e.to_string(),
+                            stance: None,
+                        }
+                    }
+                }
+            });
+        }
+
+        // Collect all model responses from this round
+        let mut round_responses = Vec::new();
+        while let Some(result) = join_set.join_next().await {
+            if let Ok(response) = result {
+                round_responses.push(response);
+            }
+        }
+
+        // Save round
+        let round = DebateRound {
+            round_number: round_num,
+            topic: request.prompt,
+            responses: round_responses,
+            created_at: Utc::now(),
+        };
+        debate_state.rounds.push(round);
+
+        let persisted = {
+            let mut store = canvas_store_arc.write().await;
+            match store.update_debate(&session_id, &debate_state) {
+                Ok(()) => true,
+                Err(error) => {
+                    emit_debate_persist_error(
+                        &window,
+                        &session_id,
+                        &debate_id,
+                        round_num,
+                        &debate_state,
+                        &error,
+                    );
+                    false
+                }
+            }
+        };
+
+        if persisted {
+            let _ = window.emit(
+                "canvas-stream",
+                CanvasStreamEvent::DebateComplete {
+                    session_id,
+                    debate_id,
+                },
+            );
+        }
+    });
+
+    Ok(())
+}
+
+/// Same contract as `emit_persistence_error` but for debate rounds, which
+/// don't have a single tile/model — a round can involve several models at
+/// once. Emits a `DebateError` per participating model in the round that
+/// failed to persist so the frontend has something concrete to render.
+fn emit_debate_persist_error(
+    window: &tauri::Window,
+    session_id: &str,
+    debate_id: &str,
+    round_number: u32,
+    debate_state: &Debate,
+    error: &anyhow::Error,
+) {
+    log::error!(
+        "Failed to persist debate '{}' round {} for session '{}': {}",
+        debate_id,
+        round_number,
+        session_id,
+        error
+    );
+
+    let model_ids: Vec<String> = debate_state
+        .rounds
+        .last()
+        .map(|round| round.responses.iter().map(|r| r.model_id.clone()).collect())
+        .unwrap_or_default();
+
+    let message = format!("Failed to save debate round: {}", error);
+
+    if model_ids.is_empty() {
+        let _ = window.emit(
+            "canvas-stream",
+            CanvasStreamEvent::DebateError {
+                session_id: session_id.to_string(),
+                debate_id: debate_id.to_string(),
+                model_id: "system".to_string(),
+                error: message,
+                round_number,
+            },
+        );
+        return;
+    }
+
+    for model_id in model_ids {
+        let _ = window.emit(
+            "canvas-stream",
+            CanvasStreamEvent::DebateError {
+                session_id: session_id.to_string(),
+                debate_id: debate_id.to_string(),
+                model_id,
+                error: message.clone(),
+                round_number,
+            },
+        );
+    }
+}
diff --git a/frontend/src-tauri/src/commands/canvas/mod.rs b/frontend/src-tauri/src/commands/canvas/mod.rs
index 5552dfa..4c7e2f6 100644
--- a/frontend/src-tauri/src/commands/canvas/mod.rs
+++ b/frontend/src-tauri/src/commands/canvas/mod.rs
@@ -1,32 +1,26 @@
 use crate::commands::commit_note_write;
 use crate::models::canvas::{
-    AvailableModel, CanvasSession, CanvasStreamEvent, CanvasViewport, ContextMode, Debate,
-    DebateContinueRequest, DebateResponse, DebateRound, DebateStartRequest, LLMNodePositionUpdate,
-    PromptType, ResponseStatus, SessionCreate, SessionMeta, SessionUpdate, TilePosition,
-    TilePositionUpdate,
+    AvailableModel, CanvasSession, CanvasViewport, LLMNodePositionUpdate, ResponseStatus,
+    SessionCreate, SessionMeta, SessionUpdate, TilePosition, TilePositionUpdate,
 };
 use crate::models::note::{NoteCreate, NoteStatus};
 use crate::models::twin::TraceEventType;
-use crate::services::openrouter::ChatMessage;
 use crate::AppState;
-use chrono::Utc;
-use futures::StreamExt;
 use serde_json::json;
 use std::collections::HashMap;
-use std::time::Duration;
 use tauri::State;
 
 mod shared;
-use shared::{
-    append_canvas_trace, effective_model_ids, resolve_model_route, source_tile_context_provider,
-    ModelProviderRoute,
-};
+use shared::append_canvas_trace;
 
 mod context;
 
 mod streaming;
 pub use streaming::*;
 
+mod debate;
+pub use debate::*;
+
 #[cfg(test)]
 mod test_support;
 
@@ -328,772 +322,3 @@ pub async fn export_to_note(
         "updated": false,
     }))
 }
-
-/// Start a debate between models with streaming via Tauri events
-#[tauri::command]
-pub async fn start_debate(
-    window: tauri::Window,
-    session_id: String,
-    mut request: DebateStartRequest,
-    state: State<'_, AppState>,
-) -> Result<String, String> {
-    let debate_id = uuid::Uuid::new_v4().to_string();
-    let now = Utc::now();
-
-    // Collect source content from tiles
-    let mut store = state.canvas_store.write().await;
-    let session = store.get_session(&session_id).map_err(|e| e.to_string())?;
-    drop(store);
-
-    let mut source_content = String::new();
-    let (source_has_vault_context, source_twin_provider) =
-        source_tile_context_provider(&session, &request.source_tile_ids);
-    let model_route = {
-        let settings = state.settings_service.read().await;
-        if source_has_vault_context {
-            resolve_model_route(
-                &PromptType::Decision,
-                &ContextMode::Twin,
-                source_twin_provider.as_deref(),
-                settings.get(),
-            )?
-        } else {
-            resolve_model_route(
-                &PromptType::Standard,
-                &ContextMode::KnowledgeSearch,
-                None,
-                settings.get(),
-            )?
-        }
-    };
-    request.participating_models = effective_model_ids(&model_route, &request.participating_models);
-    for tile_id in &request.source_tile_ids {
-        if let Some(tile) = session.prompt_tiles.iter().find(|t| &t.id == tile_id) {
-            source_content.push_str(&format!("Prompt: {}\n", tile.prompt));
-            for model_id in &request.participating_models {
-                if let Some(resp) = tile.responses.get(model_id) {
-                    source_content.push_str(&format!(
-                        "{} responded: {}\n",
-                        resp.model_name, resp.content
-                    ));
-                }
-            }
-        }
-    }
-
-    // Calculate position (to the right of source tiles)
-    let max_x = session
-        .prompt_tiles
-        .iter()
-        .flat_map(|t| {
-            t.responses
-                .values()
-                .map(|r| r.position.x + r.position.width)
-        })
-        .fold(0.0_f64, f64::max);
-
-    let debate = Debate {
-        id: debate_id.clone(),
-        participating_models: request.participating_models.clone(),
-        source_tile_ids: request.source_tile_ids.clone(),
-        rounds: Vec::new(),
-        status: "active".to_string(),
-        position: TilePosition {
-            x: max_x + 100.0,
-            y: 100.0,
-            width: 400.0,
-            height: 300.0,
-        },
-        debate_mode: request.debate_mode.clone(),
-        reasoning_effort: request.reasoning_effort.clone(),
-        created_at: now,
-    };
-
-    // Save debate to session
-    {
-        let mut store = state.canvas_store.write().await;
-        store
-            .add_debate(&session_id, debate.clone())
-            .map_err(|e| e.to_string())?;
-    }
-
-    append_canvas_trace(
-        state.twin_store.clone(),
-        &session_id,
-        TraceEventType::DebateStarted,
-        json!({
-            "debate_id": debate.id.clone(),
-            "source_tile_ids": debate.source_tile_ids.clone(),
-            "participating_models": debate.participating_models.clone(),
-            "debate_mode": debate.debate_mode.clone(),
-            "max_rounds": request.max_rounds,
-        }),
-    )
-    .await;
-
-    // Emit debate created
-    let _ = window.emit(
-        "canvas-stream",
-        CanvasStreamEvent::DebateCreated {
-            session_id: session_id.clone(),
-            debate: debate.clone(),
-        },
-    );
-
-    // Spawn async task for debate streaming
-    let openrouter_arc = state.openrouter.clone();
-    let ollama_arc = state.ollama.clone();
-    let canvas_store_arc = state.canvas_store.clone();
-    let models = request.participating_models.clone();
-    let max_rounds = request.max_rounds;
-    let reasoning_effort = request.reasoning_effort.clone();
-    let provider_route = model_route.provider.clone();
-    let debate_id_clone = debate_id.clone();
-    let session_id_clone = session_id.clone();
-
-    tauri::async_runtime::spawn(async move {
-        let mut debate_state = debate;
-
-        for round_num in 1..=max_rounds {
-            let _ = window.emit(
-                "canvas-stream",
-                CanvasStreamEvent::RoundStart {
-                    session_id: session_id_clone.clone(),
-                    debate_id: debate_id_clone.clone(),
-                    round_number: round_num,
-                },
-            );
-
-            // Build debate context
-            let mut context = format!(
-                "You are participating in a structured debate.\n\nOriginal context:\n{}\n\n",
-                source_content
-            );
-
-            // Add previous rounds for context
-            for prev_round in &debate_state.rounds {
-                context.push_str(&format!("Round {}:\n", prev_round.round_number));
-                for resp in &prev_round.responses {
-                    context.push_str(&format!("{}: {}\n", resp.model_name, resp.content));
-                }
-                context.push('\n');
-            }
-
-            context.push_str(&format!(
-                "Round {} - Present your analysis. Be concise and insightful. If other models have responded before you, engage with their points.",
-                round_num
-            ));
-
-            // Stream all models concurrently within this round using JoinSet
-            let mut join_set = tokio::task::JoinSet::new();
-
-            for model_id in models.clone() {
-                let model_name = model_id.split('/').last().unwrap_or(&model_id).to_string();
-                let messages = vec![ChatMessage {
-                    role: "user".to_string(),
-                    content: context.clone(),
-                }];
-                let openrouter_arc = openrouter_arc.clone();
-                let ollama_arc = ollama_arc.clone();
-                let window = window.clone();
-                let session_id = session_id_clone.clone();
-                let debate_id = debate_id_clone.clone();
-                let reasoning_effort = reasoning_effort.clone();
-                let provider_route = provider_route.clone();
-
-                join_set.spawn(async move {
-                    let stream_result = match provider_route {
-                        ModelProviderRoute::Ollama => {
-                            let ollama = ollama_arc.read().await;
-                            let result = ollama
-                                .chat_stream(&model_id, messages, None, Some(0.7))
-                                .await;
-                            drop(ollama);
-                            result.map(|stream| {
-                                Box::pin(stream)
-                                    as std::pin::Pin<
-                                        Box<
-                                            dyn futures::Stream<Item = anyhow::Result<String>>
-                                                + Send,
-                                        >,
-                                    >
-                            })
-                        }
-                        ModelProviderRoute::OpenRouter => {
-                            let openrouter = openrouter_arc.read().await;
-                            let result = openrouter
-                                .chat_stream(
-                                    &model_id,
-                                    messages,
-                                    None,
-                                    Some(0.7),
-                                    None,
-                                    Some(reasoning_effort.as_str()),
-                                    false,
-                                    5,
-                                )
-                                .await;
-                            drop(openrouter);
-                            result.map(|stream| {
-                                Box::pin(stream)
-                                    as std::pin::Pin<
-                                        Box<
-                                            dyn futures::Stream<Item = anyhow::Result<String>>
-                                                + Send,
-                                        >,
-                                    >
-                            })
-                        }
-                    };
-
-                    match stream_result {
-                        Ok(stream) => {
-                            let mut stream = stream;
-                            let mut full_content = String::new();
-
-                            loop {
-                                match tokio::time::timeout(Duration::from_secs(60), stream.next())
-                                    .await
-                                {
-                                    Ok(Some(Ok(chunk))) => {
-                                        if !chunk.is_empty() {
-                                            full_content.push_str(&chunk);
-                                            let _ = window.emit(
-                                                "canvas-stream",
-                                                CanvasStreamEvent::DebateChunk {
-                                                    session_id: session_id.clone(),
-                                                    debate_id: debate_id.clone(),
-                                                    model_id: model_id.clone(),
-                                                    chunk,
-                                                    round_number: round_num,
-                                                },
-                                            );
-                                        }
-                                    }
-                                    Ok(Some(Err(e))) => {
-                                        let _ = window.emit(
-                                            "canvas-stream",
-                                            CanvasStreamEvent::DebateError {
-                                                session_id: session_id.clone(),
-                                                debate_id: debate_id.clone(),
-                                                model_id: model_id.clone(),
-                                                error: e.to_string(),
-                                                round_number: round_num,
-                                            },
-                                        );
-                                        return DebateResponse {
-                                            model_id,
-                                            model_name,
-                                            content: full_content,
-                                            stance: None,
-                                        };
-                                    }
-                                    Ok(None) => break, // Stream ended naturally
-                                    Err(_) => {
-                                        let _ = window.emit(
-                                            "canvas-stream",
-                                            CanvasStreamEvent::DebateError {
-                                                session_id: session_id.clone(),
-                                                debate_id: debate_id.clone(),
-                                                model_id: model_id.clone(),
-                                                error: "Stream idle timeout (60s)".to_string(),
-                                                round_number: round_num,
-                                            },
-                                        );
-                                        return DebateResponse {
-                                            model_id,
-                                            model_name,
-                                            content: full_content,
-                                            stance: None,
-                                        };
-                                    }
-                                }
-                            }
-
-                            let _ = window.emit(
-                                "canvas-stream",
-                                CanvasStreamEvent::ModelComplete {
-                                    session_id: session_id.clone(),
-                                    debate_id: debate_id.clone(),
-                                    model_id: model_id.clone(),
-                                    round_number: round_num,
-                                },
-                            );
-
-                            DebateResponse {
-                                model_id,
-                                model_name,
-                                content: full_content,
-                                stance: None,
-                            }
-                        }
-                        Err(e) => {
-                            let _ = window.emit(
-                                "canvas-stream",
-                                CanvasStreamEvent::DebateError {
-                                    session_id: session_id.clone(),
-                                    debate_id: debate_id.clone(),
-                                    model_id: model_id.clone(),
-                                    error: e.to_string(),
-                                    round_number: round_num,
-                                },
-                            );
-                            let _ = window.emit(
-                                "canvas-stream",
-                                CanvasStreamEvent::ModelComplete {
-                                    session_id: session_id.clone(),
-                                    debate_id: debate_id.clone(),
-                                    model_id: model_id.clone(),
-                                    round_number: round_num,
-                                },
-                            );
-                            DebateResponse {
-                                model_id,
-                                model_name,
-                                content: e.to_string(),
-                                stance: None,
-                            }
-                        }
-                    }
-                });
-            }
-
-            // Collect all model responses from this round
-            let mut round_responses = Vec::new();
-            while let Some(result) = join_set.join_next().await {
-                if let Ok(response) = result {
-                    round_responses.push(response);
-                }
-            }
-
-            // Save round
-            let round = DebateRound {
-                round_number: round_num,
-                topic: format!("Round {}", round_num),
-                responses: round_responses,
-                created_at: Utc::now(),
-            };
-            debate_state.rounds.push(round);
-
-            // Persist after each round. If this fails, surface it instead of
-            // silently continuing to stream rounds that will never survive a
-            // session reopen.
-            let round_persisted = {
-                let mut store = canvas_store_arc.write().await;
-                match store.update_debate(&session_id_clone, &debate_state) {
-                    Ok(()) => true,
-                    Err(error) => {
-                        emit_debate_persist_error(
-                            &window,
-                            &session_id_clone,
-                            &debate_id_clone,
-                            round_num,
-                            &debate_state,
-                            &error,
-                        );
-                        false
-                    }
-                }
-            };
-
-            if !round_persisted {
-                return;
-            }
-        }
-
-        // Mark debate as complete
-        debate_state.status = "completed".to_string();
-        let final_round_number = debate_state
-            .rounds
-            .last()
-            .map(|round| round.round_number)
-            .unwrap_or(max_rounds);
-        let completion_persisted = {
-            let mut store = canvas_store_arc.write().await;
-            match store.update_debate(&session_id_clone, &debate_state) {
-                Ok(()) => true,
-                Err(error) => {
-                    emit_debate_persist_error(
-                        &window,
-                        &session_id_clone,
-                        &debate_id_clone,
-                        final_round_number,
-                        &debate_state,
-                        &error,
-                    );
-                    false
-                }
-            }
-        };
-
-        if completion_persisted {
-            let _ = window.emit(
-                "canvas-stream",
-                CanvasStreamEvent::DebateComplete {
-                    session_id: session_id_clone,
-                    debate_id: debate_id_clone,
-                },
-            );
-        }
-    });
-
-    Ok(debate_id)
-}
-
-/// Continue a debate with a new round
-#[tauri::command]
-pub async fn continue_debate(
-    window: tauri::Window,
-    session_id: String,
-    debate_id: String,
-    request: DebateContinueRequest,
-    state: State<'_, AppState>,
-) -> Result<(), String> {
-    let mut store = state.canvas_store.write().await;
-    let session = store.get_session(&session_id).map_err(|e| e.to_string())?;
-    drop(store);
-
-    let debate = session
-        .debates
-        .iter()
-        .find(|d| d.id == debate_id)
-        .ok_or_else(|| "Debate not found".to_string())?
-        .clone();
-    let (source_has_vault_context, source_twin_provider) =
-        source_tile_context_provider(&session, &debate.source_tile_ids);
-    let model_route = {
-        let settings = state.settings_service.read().await;
-        if source_has_vault_context {
-            resolve_model_route(
-                &PromptType::Decision,
-                &ContextMode::Twin,
-                source_twin_provider.as_deref(),
-                settings.get(),
-            )?
-        } else {
-            resolve_model_route(
-                &PromptType::Standard,
-                &ContextMode::KnowledgeSearch,
-                None,
-                settings.get(),
-            )?
-        }
-    };
-
-    append_canvas_trace(
-        state.twin_store.clone(),
-        &session_id,
-        TraceEventType::DebateContinued,
-        json!({
-            "debate_id": debate_id.clone(),
-            "prompt": request.prompt.clone(),
-            "participating_models": debate.participating_models.clone(),
-        }),
-    )
-    .await;
-
-    let openrouter_arc = state.openrouter.clone();
-    let ollama_arc = state.ollama.clone();
-    let canvas_store_arc = state.canvas_store.clone();
-    let models = effective_model_ids(&model_route, &debate.participating_models);
-    let reasoning_effort = request.reasoning_effort.clone();
-    let provider_route = model_route.provider.clone();
-
-    tauri::async_runtime::spawn(async move {
-        let mut debate_state = debate;
-        let round_num = debate_state.rounds.len() as u32 + 1;
-
-        let _ = window.emit(
-            "canvas-stream",
-            CanvasStreamEvent::RoundStart {
-                session_id: session_id.clone(),
-                debate_id: debate_id.clone(),
-                round_number: round_num,
-            },
-        );
-
-        // Build context from previous rounds + new prompt
-        let mut context = String::from("Previous debate rounds:\n\n");
-        for round in &debate_state.rounds {
-            context.push_str(&format!("Round {}:\n", round.round_number));
-            for resp in &round.responses {
-                context.push_str(&format!("{}: {}\n", resp.model_name, resp.content));
-            }
-            context.push('\n');
-        }
-        context.push_str(&format!(
-            "New prompt: {}\n\nRespond to this new direction.",
-            request.prompt
-        ));
-
-        // Stream all models concurrently using JoinSet
-        let mut join_set = tokio::task::JoinSet::new();
-
-        for model_id in models {
-            let model_name = model_id.split('/').last().unwrap_or(&model_id).to_string();
-            let messages = vec![ChatMessage {
-                role: "user".to_string(),
-                content: context.clone(),
-            }];
-            let openrouter_arc = openrouter_arc.clone();
-            let ollama_arc = ollama_arc.clone();
-            let window = window.clone();
-            let session_id = session_id.clone();
-            let debate_id = debate_id.clone();
-            let reasoning_effort = reasoning_effort.clone();
-            let provider_route = provider_route.clone();
-
-            join_set.spawn(async move {
-                let stream_result = match provider_route {
-                    ModelProviderRoute::Ollama => {
-                        let ollama = ollama_arc.read().await;
-                        let result = ollama
-                            .chat_stream(&model_id, messages, None, Some(0.7))
-                            .await;
-                        drop(ollama);
-                        result.map(|stream| {
-                            Box::pin(stream)
-                                as std::pin::Pin<
-                                    Box<dyn futures::Stream<Item = anyhow::Result<String>> + Send>,
-                                >
-                        })
-                    }
-                    ModelProviderRoute::OpenRouter => {
-                        let openrouter = openrouter_arc.read().await;
-                        let result = openrouter
-                            .chat_stream(
-                                &model_id,
-                                messages,
-                                None,
-                                Some(0.7),
-                                None,
-                                Some(reasoning_effort.as_str()),
-                                false,
-                                5,
-                            )
-                            .await;
-                        drop(openrouter);
-                        result.map(|stream| {
-                            Box::pin(stream)
-                                as std::pin::Pin<
-                                    Box<dyn futures::Stream<Item = anyhow::Result<String>> + Send>,
-                                >
-                        })
-                    }
-                };
-
-                match stream_result {
-                    Ok(stream) => {
-                        let mut stream = stream;
-                        let mut full_content = String::new();
-
-                        loop {
-                            match tokio::time::timeout(Duration::from_secs(60), stream.next()).await
-                            {
-                                Ok(Some(Ok(chunk))) => {
-                                    if !chunk.is_empty() {
-                                        full_content.push_str(&chunk);
-                                        let _ = window.emit(
-                                            "canvas-stream",
-                                            CanvasStreamEvent::DebateChunk {
-                                                session_id: session_id.clone(),
-                                                debate_id: debate_id.clone(),
-                                                model_id: model_id.clone(),
-                                                chunk,
-                                                round_number: round_num,
-                                            },
-                                        );
-                                    }
-                                }
-                                Ok(Some(Err(e))) => {
-                                    let _ = window.emit(
-                                        "canvas-stream",
-                                        CanvasStreamEvent::DebateError {
-                                            session_id: session_id.clone(),
-                                            debate_id: debate_id.clone(),
-                                            model_id: model_id.clone(),
-                                            error: e.to_string(),
-                                            round_number: round_num,
-                                        },
-                                    );
-                                    return DebateResponse {
-                                        model_id,
-                                        model_name,
-                                        content: full_content,
-                                        stance: None,
-                                    };
-                                }
-                                Ok(None) => break, // Stream ended naturally
-                                Err(_) => {
-                                    let _ = window.emit(
-                                        "canvas-stream",
-                                        CanvasStreamEvent::DebateError {
-                                            session_id: session_id.clone(),
-                                            debate_id: debate_id.clone(),
-                                            model_id: model_id.clone(),
-                                            error: "Stream idle timeout (60s)".to_string(),
-                                            round_number: round_num,
-                                        },
-                                    );
-                                    return DebateResponse {
-                                        model_id,
-                                        model_name,
-                                        content: full_content,
-                                        stance: None,
-                                    };
-                                }
-                            }
-                        }
-
-                        let _ = window.emit(
-                            "canvas-stream",
-                            CanvasStreamEvent::ModelComplete {
-                                session_id: session_id.clone(),
-                                debate_id: debate_id.clone(),
-                                model_id: model_id.clone(),
-                                round_number: round_num,
-                            },
-                        );
-
-                        DebateResponse {
-                            model_id,
-                            model_name,
-                            content: full_content,
-                            stance: None,
-                        }
-                    }
-                    Err(e) => {
-                        let _ = window.emit(
-                            "canvas-stream",
-                            CanvasStreamEvent::DebateError {
-                                session_id: session_id.clone(),
-                                debate_id: debate_id.clone(),
-                                model_id: model_id.clone(),
-                                error: e.to_string(),
-                                round_number: round_num,
-                            },
-                        );
-                        let _ = window.emit(
-                            "canvas-stream",
-                            CanvasStreamEvent::ModelComplete {
-                                session_id: session_id.clone(),
-                                debate_id: debate_id.clone(),
-                                model_id: model_id.clone(),
-                                round_number: round_num,
-                            },
-                        );
-                        DebateResponse {
-                            model_id,
-                            model_name,
-                            content: e.to_string(),
-                            stance: None,
-                        }
-                    }
-                }
-            });
-        }
-
-        // Collect all model responses from this round
-        let mut round_responses = Vec::new();
-        while let Some(result) = join_set.join_next().await {
-            if let Ok(response) = result {
-                round_responses.push(response);
-            }
-        }
-
-        // Save round
-        let round = DebateRound {
-            round_number: round_num,
-            topic: request.prompt,
-            responses: round_responses,
-            created_at: Utc::now(),
-        };
-        debate_state.rounds.push(round);
-
-        let persisted = {
-            let mut store = canvas_store_arc.write().await;
-            match store.update_debate(&session_id, &debate_state) {
-                Ok(()) => true,
-                Err(error) => {
-                    emit_debate_persist_error(
-                        &window,
-                        &session_id,
-                        &debate_id,
-                        round_num,
-                        &debate_state,
-                        &error,
-                    );
-                    false
-                }
-            }
-        };
-
-        if persisted {
-            let _ = window.emit(
-                "canvas-stream",
-                CanvasStreamEvent::DebateComplete {
-                    session_id,
-                    debate_id,
-                },
-            );
-        }
-    });
-
-    Ok(())
-}
-
-/// Same contract as `emit_persistence_error` but for debate rounds, which
-/// don't have a single tile/model — a round can involve several models at
-/// once. Emits a `DebateError` per participating model in the round that
-/// failed to persist so the frontend has something concrete to render.
-fn emit_debate_persist_error(
-    window: &tauri::Window,
-    session_id: &str,
-    debate_id: &str,
-    round_number: u32,
-    debate_state: &Debate,
-    error: &anyhow::Error,
-) {
-    log::error!(
-        "Failed to persist debate '{}' round {} for session '{}': {}",
-        debate_id,
-        round_number,
-        session_id,
-        error
-    );
-
-    let model_ids: Vec<String> = debate_state
-        .rounds
-        .last()
-        .map(|round| round.responses.iter().map(|r| r.model_id.clone()).collect())
-        .unwrap_or_default();
-
-    let message = format!("Failed to save debate round: {}", error);
-
-    if model_ids.is_empty() {
-        let _ = window.emit(
-            "canvas-stream",
-            CanvasStreamEvent::DebateError {
-                session_id: session_id.to_string(),
-                debate_id: debate_id.to_string(),
-                model_id: "system".to_string(),
-                error: message,
-                round_number,
-            },
-        );
-        return;
-    }
-
-    for model_id in model_ids {
-        let _ = window.emit(
-            "canvas-stream",
-            CanvasStreamEvent::DebateError {
-                session_id: session_id.to_string(),
-                debate_id: debate_id.to_string(),
-                model_id,
-                error: message.clone(),
-                round_number,
-            },
-        );
-    }
-}

From 0b26864a4c32abbfcb076bf86a2a466125b2b4d5 Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 14:44:32 +0800
Subject: [PATCH 06/30] refactor: extract canvas::session

Move session CRUD, tile/node position updates, viewport, auto_arrange,
and export_to_note into canvas::session. mod.rs is now a thin surface:
module wiring plus glob re-exports from shared/streaming/debate/session,
with context.rs holding the twin/note prompt-assembly internals used by
streaming.
---
 frontend/src-tauri/src/commands/canvas/mod.rs | 331 ++----------------
 .../src-tauri/src/commands/canvas/session.rs  | 311 ++++++++++++++++
 2 files changed, 331 insertions(+), 311 deletions(-)
 create mode 100644 frontend/src-tauri/src/commands/canvas/session.rs

diff --git a/frontend/src-tauri/src/commands/canvas/mod.rs b/frontend/src-tauri/src/commands/canvas/mod.rs
index 4c7e2f6..69460de 100644
--- a/frontend/src-tauri/src/commands/canvas/mod.rs
+++ b/frontend/src-tauri/src/commands/canvas/mod.rs
@@ -1,17 +1,22 @@
-use crate::commands::commit_note_write;
-use crate::models::canvas::{
-    AvailableModel, CanvasSession, CanvasViewport, LLMNodePositionUpdate, ResponseStatus,
-    SessionCreate, SessionMeta, SessionUpdate, TilePosition, TilePositionUpdate,
-};
-use crate::models::note::{NoteCreate, NoteStatus};
-use crate::models::twin::TraceEventType;
-use crate::AppState;
-use serde_json::json;
-use std::collections::HashMap;
-use tauri::State;
+//! Multi-LLM canvas: the `#[tauri::command]` surface for canvas sessions,
+//! prompt streaming, model debates, and twin/note context assembly.
+//!
+//! Split into focused submodules (Task 4.1):
+//! - `shared` — model-routing helpers and the trace-append helper used by
+//!   every command handler below.
+//! - `context` — note/twin context-prompt assembly, including the twin
+//!   Simulation identity gate.
+//! - `streaming` — `send_prompt`, `add_models_to_tile`, `regenerate_response`
+//!   and their per-model stream task helpers.
+//! - `debate` — `start_debate`, `continue_debate`, and debate streaming.
+//! - `session` — session CRUD, tile/node positions, viewport, auto-arrange,
+//!   and note export.
+//!
+//! Command names and signatures are unchanged from the pre-split
+//! `canvas.rs` — `main.rs`'s `generate_handler!` list still resolves them
+//! via the glob re-exports below.
 
 mod shared;
-use shared::append_canvas_trace;
 
 mod context;
 
@@ -21,304 +26,8 @@ pub use streaming::*;
 mod debate;
 pub use debate::*;
 
+mod session;
+pub use session::*;
+
 #[cfg(test)]
 mod test_support;
-
-/// List all canvas sessions
-#[tauri::command]
-pub async fn list_sessions(state: State<'_, AppState>) -> Result<Vec<SessionMeta>, String> {
-    let mut store = state.canvas_store.write().await;
-    store.list_sessions().map_err(|e| e.to_string())
-}
-
-/// Get a single session by ID
-#[tauri::command]
-pub async fn get_session(id: String, state: State<'_, AppState>) -> Result<CanvasSession, String> {
-    let mut store = state.canvas_store.write().await;
-    store.get_session(&id).map_err(|e| e.to_string())
-}
-
-/// Create a new canvas session
-#[tauri::command]
-pub async fn create_session(
-    session: SessionCreate,
-    state: State<'_, AppState>,
-) -> Result<CanvasSession, String> {
-    let mut store = state.canvas_store.write().await;
-    let created = store.create_session(session).map_err(|e| e.to_string())?;
-    drop(store);
-
-    append_canvas_trace(
-        state.twin_store.clone(),
-        &created.id,
-        TraceEventType::SessionCreated,
-        json!({
-            "title": created.title.clone(),
-            "description": created.description.clone(),
-            "tags": created.tags.clone(),
-            "status": created.status.clone(),
-        }),
-    )
-    .await;
-
-    Ok(created)
-}
-
-/// Update a canvas session
-#[tauri::command]
-pub async fn update_session(
-    id: String,
-    update: SessionUpdate,
-    state: State<'_, AppState>,
-) -> Result<CanvasSession, String> {
-    let mut store = state.canvas_store.write().await;
-    let updated = store
-        .update_session(&id, update)
-        .map_err(|e| e.to_string())?;
-    drop(store);
-
-    append_canvas_trace(
-        state.twin_store.clone(),
-        &updated.id,
-        TraceEventType::SessionUpdated,
-        json!({
-            "title": updated.title.clone(),
-            "description": updated.description.clone(),
-            "tags": updated.tags.clone(),
-            "status": updated.status.clone(),
-            "viewport": updated.viewport.clone(),
-            "pinned_note_ids": updated.pinned_note_ids.clone(),
-        }),
-    )
-    .await;
-
-    Ok(updated)
-}
-
-/// Delete a canvas session
-#[tauri::command]
-pub async fn delete_session(id: String, state: State<'_, AppState>) -> Result<(), String> {
-    let mut store = state.canvas_store.write().await;
-    store.delete_session(&id).map_err(|e| e.to_string())?;
-    drop(store);
-
-    append_canvas_trace(
-        state.twin_store.clone(),
-        &id,
-        TraceEventType::SessionDeleted,
-        json!({
-            "session_id": id,
-        }),
-    )
-    .await;
-
-    Ok(())
-}
-
-/// Get list of available LLM models
-#[tauri::command]
-pub async fn get_available_models(
-    state: State<'_, AppState>,
-) -> Result<Vec<AvailableModel>, String> {
-    let openrouter = state.openrouter.read().await;
-    openrouter
-        .get_available_models()
-        .await
-        .map_err(|e| e.to_string())
-}
-
-/// Update a tile's position
-#[tauri::command]
-pub async fn update_tile_position(
-    session_id: String,
-    tile_id: String,
-    position: TilePositionUpdate,
-    state: State<'_, AppState>,
-) -> Result<(), String> {
-    let mut store = state.canvas_store.write().await;
-    store
-        .update_tile_position(&session_id, &tile_id, position)
-        .map_err(|e| e.to_string())?;
-    Ok(())
-}
-
-/// Delete a prompt tile and its children
-#[tauri::command]
-pub async fn delete_tile(
-    session_id: String,
-    tile_id: String,
-    state: State<'_, AppState>,
-) -> Result<(), String> {
-    let mut store = state.canvas_store.write().await;
-    store
-        .delete_tile(&session_id, &tile_id)
-        .map_err(|e| e.to_string())?;
-    drop(store);
-
-    append_canvas_trace(
-        state.twin_store.clone(),
-        &session_id,
-        TraceEventType::TileDeleted,
-        json!({
-            "tile_id": tile_id,
-        }),
-    )
-    .await;
-
-    Ok(())
-}
-
-/// Delete a single model response from a tile
-#[tauri::command]
-pub async fn delete_response(
-    session_id: String,
-    tile_id: String,
-    model_id: String,
-    state: State<'_, AppState>,
-) -> Result<(), String> {
-    let mut store = state.canvas_store.write().await;
-    store
-        .delete_response(&session_id, &tile_id, &model_id)
-        .map_err(|e| e.to_string())?;
-    drop(store);
-
-    append_canvas_trace(
-        state.twin_store.clone(),
-        &session_id,
-        TraceEventType::ResponseDeleted,
-        json!({
-            "tile_id": tile_id,
-            "model_id": model_id,
-        }),
-    )
-    .await;
-
-    Ok(())
-}
-
-/// Update viewport zoom/pan state
-#[tauri::command]
-pub async fn update_viewport(
-    session_id: String,
-    viewport: CanvasViewport,
-    state: State<'_, AppState>,
-) -> Result<(), String> {
-    let mut store = state.canvas_store.write().await;
-    store
-        .update_viewport(&session_id, viewport)
-        .map_err(|e| e.to_string())
-}
-
-/// Update an LLM response node's position
-#[tauri::command]
-pub async fn update_llm_node_position(
-    session_id: String,
-    tile_id: String,
-    model_id: String,
-    position: LLMNodePositionUpdate,
-    state: State<'_, AppState>,
-) -> Result<(), String> {
-    let mut store = state.canvas_store.write().await;
-    store
-        .update_llm_node_position(&session_id, &tile_id, &model_id, position)
-        .map_err(|e| e.to_string())
-}
-
-/// Auto-arrange all nodes (batch position update)
-#[tauri::command]
-pub async fn auto_arrange(
-    session_id: String,
-    positions: HashMap<String, TilePosition>,
-    state: State<'_, AppState>,
-) -> Result<(), String> {
-    let mut store = state.canvas_store.write().await;
-    store
-        .batch_update_positions(&session_id, positions)
-        .map_err(|e| e.to_string())
-}
-
-/// Export canvas session to a note (returns note info)
-#[tauri::command]
-pub async fn export_to_note(
-    session_id: String,
-    state: State<'_, AppState>,
-) -> Result<serde_json::Value, String> {
-    let mut store = state.canvas_store.write().await;
-    let session = store.get_session(&session_id).map_err(|e| e.to_string())?;
-    drop(store);
-
-    // Build markdown content from session
-    let mut content = format!("# {}\n\n", session.title);
-
-    if let Some(desc) = &session.description {
-        content.push_str(&format!("{}\n\n", desc));
-    }
-
-    for tile in &session.prompt_tiles {
-        content.push_str(&format!("## Prompt\n\n{}\n\n", tile.prompt));
-
-        for (model_id, response) in &tile.responses {
-            if response.status == ResponseStatus::Completed {
-                content.push_str(&format!(
-                    "### {} ({})\n\n{}\n\n",
-                    response.model_name, model_id, response.content
-                ));
-            }
-        }
-    }
-
-    for debate in &session.debates {
-        content.push_str("## Debate\n\n");
-        for round in &debate.rounds {
-            content.push_str(&format!(
-                "### Round {} - {}\n\n",
-                round.round_number, round.topic
-            ));
-            for resp in &round.responses {
-                content.push_str(&format!(
-                    "**{} ({}):**\n\n{}\n\n",
-                    resp.model_name, resp.model_id, resp.content
-                ));
-            }
-        }
-    }
-
-    // Create note via knowledge store
-    let mut ks = state.knowledge_store.write().await;
-
-    let note = ks
-        .create_note(NoteCreate {
-            title: session.title.clone(),
-            content,
-            relative_path: None,
-            aliases: Vec::new(),
-            status: NoteStatus::Evidence,
-            tags: session.tags.clone(),
-            schema_version: crate::models::note::CURRENT_NOTE_SCHEMA_VERSION,
-            migration_source: None,
-            optimizer_managed: false,
-            properties: HashMap::new(),
-        })
-        .map_err(|e| e.to_string())?;
-
-    drop(ks);
-
-    commit_note_write(state.inner(), &note.id, "note_exported").await?;
-
-    append_canvas_trace(
-        state.twin_store.clone(),
-        &session_id,
-        TraceEventType::NoteExported,
-        json!({
-            "note_id": note.id.clone(),
-            "title": note.title.clone(),
-        }),
-    )
-    .await;
-
-    Ok(serde_json::json!({
-        "note_id": note.id,
-        "title": note.title,
-        "updated": false,
-    }))
-}
diff --git a/frontend/src-tauri/src/commands/canvas/session.rs b/frontend/src-tauri/src/commands/canvas/session.rs
new file mode 100644
index 0000000..82ce30e
--- /dev/null
+++ b/frontend/src-tauri/src/commands/canvas/session.rs
@@ -0,0 +1,311 @@
+use super::shared::append_canvas_trace;
+use crate::commands::commit_note_write;
+use crate::models::canvas::{
+    AvailableModel, CanvasSession, CanvasViewport, LLMNodePositionUpdate, ResponseStatus,
+    SessionCreate, SessionMeta, SessionUpdate, TilePosition, TilePositionUpdate,
+};
+use crate::models::note::{NoteCreate, NoteStatus};
+use crate::models::twin::TraceEventType;
+use crate::AppState;
+use serde_json::json;
+use std::collections::HashMap;
+use tauri::State;
+
+/// List all canvas sessions
+#[tauri::command]
+pub async fn list_sessions(state: State<'_, AppState>) -> Result<Vec<SessionMeta>, String> {
+    let mut store = state.canvas_store.write().await;
+    store.list_sessions().map_err(|e| e.to_string())
+}
+
+/// Get a single session by ID
+#[tauri::command]
+pub async fn get_session(id: String, state: State<'_, AppState>) -> Result<CanvasSession, String> {
+    let mut store = state.canvas_store.write().await;
+    store.get_session(&id).map_err(|e| e.to_string())
+}
+
+/// Create a new canvas session
+#[tauri::command]
+pub async fn create_session(
+    session: SessionCreate,
+    state: State<'_, AppState>,
+) -> Result<CanvasSession, String> {
+    let mut store = state.canvas_store.write().await;
+    let created = store.create_session(session).map_err(|e| e.to_string())?;
+    drop(store);
+
+    append_canvas_trace(
+        state.twin_store.clone(),
+        &created.id,
+        TraceEventType::SessionCreated,
+        json!({
+            "title": created.title.clone(),
+            "description": created.description.clone(),
+            "tags": created.tags.clone(),
+            "status": created.status.clone(),
+        }),
+    )
+    .await;
+
+    Ok(created)
+}
+
+/// Update a canvas session
+#[tauri::command]
+pub async fn update_session(
+    id: String,
+    update: SessionUpdate,
+    state: State<'_, AppState>,
+) -> Result<CanvasSession, String> {
+    let mut store = state.canvas_store.write().await;
+    let updated = store
+        .update_session(&id, update)
+        .map_err(|e| e.to_string())?;
+    drop(store);
+
+    append_canvas_trace(
+        state.twin_store.clone(),
+        &updated.id,
+        TraceEventType::SessionUpdated,
+        json!({
+            "title": updated.title.clone(),
+            "description": updated.description.clone(),
+            "tags": updated.tags.clone(),
+            "status": updated.status.clone(),
+            "viewport": updated.viewport.clone(),
+            "pinned_note_ids": updated.pinned_note_ids.clone(),
+        }),
+    )
+    .await;
+
+    Ok(updated)
+}
+
+/// Delete a canvas session
+#[tauri::command]
+pub async fn delete_session(id: String, state: State<'_, AppState>) -> Result<(), String> {
+    let mut store = state.canvas_store.write().await;
+    store.delete_session(&id).map_err(|e| e.to_string())?;
+    drop(store);
+
+    append_canvas_trace(
+        state.twin_store.clone(),
+        &id,
+        TraceEventType::SessionDeleted,
+        json!({
+            "session_id": id,
+        }),
+    )
+    .await;
+
+    Ok(())
+}
+
+/// Get list of available LLM models
+#[tauri::command]
+pub async fn get_available_models(
+    state: State<'_, AppState>,
+) -> Result<Vec<AvailableModel>, String> {
+    let openrouter = state.openrouter.read().await;
+    openrouter
+        .get_available_models()
+        .await
+        .map_err(|e| e.to_string())
+}
+
+/// Update a tile's position
+#[tauri::command]
+pub async fn update_tile_position(
+    session_id: String,
+    tile_id: String,
+    position: TilePositionUpdate,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    let mut store = state.canvas_store.write().await;
+    store
+        .update_tile_position(&session_id, &tile_id, position)
+        .map_err(|e| e.to_string())?;
+    Ok(())
+}
+
+/// Delete a prompt tile and its children
+#[tauri::command]
+pub async fn delete_tile(
+    session_id: String,
+    tile_id: String,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    let mut store = state.canvas_store.write().await;
+    store
+        .delete_tile(&session_id, &tile_id)
+        .map_err(|e| e.to_string())?;
+    drop(store);
+
+    append_canvas_trace(
+        state.twin_store.clone(),
+        &session_id,
+        TraceEventType::TileDeleted,
+        json!({
+            "tile_id": tile_id,
+        }),
+    )
+    .await;
+
+    Ok(())
+}
+
+/// Delete a single model response from a tile
+#[tauri::command]
+pub async fn delete_response(
+    session_id: String,
+    tile_id: String,
+    model_id: String,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    let mut store = state.canvas_store.write().await;
+    store
+        .delete_response(&session_id, &tile_id, &model_id)
+        .map_err(|e| e.to_string())?;
+    drop(store);
+
+    append_canvas_trace(
+        state.twin_store.clone(),
+        &session_id,
+        TraceEventType::ResponseDeleted,
+        json!({
+            "tile_id": tile_id,
+            "model_id": model_id,
+        }),
+    )
+    .await;
+
+    Ok(())
+}
+
+/// Update viewport zoom/pan state
+#[tauri::command]
+pub async fn update_viewport(
+    session_id: String,
+    viewport: CanvasViewport,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    let mut store = state.canvas_store.write().await;
+    store
+        .update_viewport(&session_id, viewport)
+        .map_err(|e| e.to_string())
+}
+
+/// Update an LLM response node's position
+#[tauri::command]
+pub async fn update_llm_node_position(
+    session_id: String,
+    tile_id: String,
+    model_id: String,
+    position: LLMNodePositionUpdate,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    let mut store = state.canvas_store.write().await;
+    store
+        .update_llm_node_position(&session_id, &tile_id, &model_id, position)
+        .map_err(|e| e.to_string())
+}
+
+/// Auto-arrange all nodes (batch position update)
+#[tauri::command]
+pub async fn auto_arrange(
+    session_id: String,
+    positions: HashMap<String, TilePosition>,
+    state: State<'_, AppState>,
+) -> Result<(), String> {
+    let mut store = state.canvas_store.write().await;
+    store
+        .batch_update_positions(&session_id, positions)
+        .map_err(|e| e.to_string())
+}
+
+/// Export canvas session to a note (returns note info)
+#[tauri::command]
+pub async fn export_to_note(
+    session_id: String,
+    state: State<'_, AppState>,
+) -> Result<serde_json::Value, String> {
+    let mut store = state.canvas_store.write().await;
+    let session = store.get_session(&session_id).map_err(|e| e.to_string())?;
+    drop(store);
+
+    // Build markdown content from session
+    let mut content = format!("# {}\n\n", session.title);
+
+    if let Some(desc) = &session.description {
+        content.push_str(&format!("{}\n\n", desc));
+    }
+
+    for tile in &session.prompt_tiles {
+        content.push_str(&format!("## Prompt\n\n{}\n\n", tile.prompt));
+
+        for (model_id, response) in &tile.responses {
+            if response.status == ResponseStatus::Completed {
+                content.push_str(&format!(
+                    "### {} ({})\n\n{}\n\n",
+                    response.model_name, model_id, response.content
+                ));
+            }
+        }
+    }
+
+    for debate in &session.debates {
+        content.push_str("## Debate\n\n");
+        for round in &debate.rounds {
+            content.push_str(&format!(
+                "### Round {} - {}\n\n",
+                round.round_number, round.topic
+            ));
+            for resp in &round.responses {
+                content.push_str(&format!(
+                    "**{} ({}):**\n\n{}\n\n",
+                    resp.model_name, resp.model_id, resp.content
+                ));
+            }
+        }
+    }
+
+    // Create note via knowledge store
+    let mut ks = state.knowledge_store.write().await;
+
+    let note = ks
+        .create_note(NoteCreate {
+            title: session.title.clone(),
+            content,
+            relative_path: None,
+            aliases: Vec::new(),
+            status: NoteStatus::Evidence,
+            tags: session.tags.clone(),
+            schema_version: crate::models::note::CURRENT_NOTE_SCHEMA_VERSION,
+            migration_source: None,
+            optimizer_managed: false,
+            properties: HashMap::new(),
+        })
+        .map_err(|e| e.to_string())?;
+
+    drop(ks);
+
+    commit_note_write(state.inner(), &note.id, "note_exported").await?;
+
+    append_canvas_trace(
+        state.twin_store.clone(),
+        &session_id,
+        TraceEventType::NoteExported,
+        json!({
+            "note_id": note.id.clone(),
+            "title": note.title.clone(),
+        }),
+    )
+    .await;
+
+    Ok(serde_json::json!({
+        "note_id": note.id,
+        "title": note.title,
+        "updated": false,
+    }))
+}

From e0b50cf3409797d0c16a356b8e5bd8871025d158 Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 14:49:00 +0800
Subject: [PATCH 07/30] fix: drop redundant #![cfg(test)] in
 canvas::test_support

mod.rs already gates the module declaration with #[cfg(test)], so the
inner attribute duplicated it and tripped a new clippy error (43 vs the
42-error baseline). Removing it restores the baseline count.
---
 frontend/src-tauri/src/commands/canvas/test_support.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend/src-tauri/src/commands/canvas/test_support.rs b/frontend/src-tauri/src/commands/canvas/test_support.rs
index a6d3af2..48987ee 100644
--- a/frontend/src-tauri/src/commands/canvas/test_support.rs
+++ b/frontend/src-tauri/src/commands/canvas/test_support.rs
@@ -1,7 +1,7 @@
 //! Test-only builder helpers shared by more than one canvas submodule's test
 //! suite (currently `context` and `streaming`). Kept separate from either
 //! module so neither has to duplicate `build_tile`/`build_response`.
-#![cfg(test)]
+//! Gated by the `#[cfg(test)] mod test_support;` declaration in `mod.rs`.
 
 use crate::models::canvas::{
     ContextMode, ModelResponse, PromptTile, PromptType, ResponseStatus, TilePosition,

From c15254835c2e0f7feadf86e67ad82744232663a5 Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 15:12:41 +0800
Subject: [PATCH 08/30] refactor: convert twin_store.rs to twin/mod.rs (prep
 for split)

Renames the services::twin_store module to services::twin (pure move,
no logic change) so Task 4.2's domain submodules can live alongside it.
Updates the 6 external reference sites (main.rs AppState import,
commands/settings.rs, commands/mod.rs test helper, canvas
shared/streaming/context) to the new module path.
---
 frontend/src-tauri/src/commands/canvas/context.rs              | 2 +-
 frontend/src-tauri/src/commands/canvas/shared.rs               | 2 +-
 frontend/src-tauri/src/commands/canvas/streaming.rs            | 2 +-
 frontend/src-tauri/src/commands/mod.rs                         | 2 +-
 frontend/src-tauri/src/commands/settings.rs                    | 2 +-
 frontend/src-tauri/src/main.rs                                 | 2 +-
 frontend/src-tauri/src/services/mod.rs                         | 2 +-
 frontend/src-tauri/src/services/{twin_store.rs => twin/mod.rs} | 0
 8 files changed, 7 insertions(+), 7 deletions(-)
 rename frontend/src-tauri/src/services/{twin_store.rs => twin/mod.rs} (100%)

diff --git a/frontend/src-tauri/src/commands/canvas/context.rs b/frontend/src-tauri/src/commands/canvas/context.rs
index 04b104b..d3bf12e 100644
--- a/frontend/src-tauri/src/commands/canvas/context.rs
+++ b/frontend/src-tauri/src/commands/canvas/context.rs
@@ -11,7 +11,7 @@ use crate::models::twin::{
 use crate::services::ollama::OllamaService;
 use crate::services::openrouter::{ChatMessage, OpenRouterService};
 use crate::services::retrieval::RetrievalResult;
-use crate::services::twin_store::{parse_twin_prediction, TwinStore};
+use crate::services::twin::{parse_twin_prediction, TwinStore};
 use crate::AppState;
 use std::collections::{HashMap, HashSet};
 use std::sync::Arc;
diff --git a/frontend/src-tauri/src/commands/canvas/shared.rs b/frontend/src-tauri/src/commands/canvas/shared.rs
index c4c4dcf..decb367 100644
--- a/frontend/src-tauri/src/commands/canvas/shared.rs
+++ b/frontend/src-tauri/src/commands/canvas/shared.rs
@@ -1,7 +1,7 @@
 use crate::models::canvas::{CanvasSession, ContextMode, PromptType};
 use crate::models::settings::UserSettings;
 use crate::models::twin::TraceEventType;
-use crate::services::twin_store::TwinStore;
+use crate::services::twin::TwinStore;
 use std::sync::Arc;
 use tokio::sync::RwLock;
 
diff --git a/frontend/src-tauri/src/commands/canvas/streaming.rs b/frontend/src-tauri/src/commands/canvas/streaming.rs
index 0d4f4f7..0fe482d 100644
--- a/frontend/src-tauri/src/commands/canvas/streaming.rs
+++ b/frontend/src-tauri/src/commands/canvas/streaming.rs
@@ -9,7 +9,7 @@ use crate::models::canvas::{
 use crate::models::twin::{
     DecisionEpisodeCreate, PrimitiveDecisionAssessment, ReflectionCardCreate, TraceEventType,
 };
-use crate::services::twin_store::TwinStore;
+use crate::services::twin::TwinStore;
 use crate::AppState;
 use chrono::Utc;
 use futures::StreamExt;
diff --git a/frontend/src-tauri/src/commands/mod.rs b/frontend/src-tauri/src/commands/mod.rs
index 2b94c50..55f6747 100644
--- a/frontend/src-tauri/src/commands/mod.rs
+++ b/frontend/src-tauri/src/commands/mod.rs
@@ -487,7 +487,7 @@ mod commit_note_write_tests {
     use crate::services::search::SearchService;
     use crate::services::settings::SettingsService;
     use crate::services::topic_hub::normalize_topic_key;
-    use crate::services::twin_store::TwinStore;
+    use crate::services::twin::TwinStore;
     use crate::services::vault_optimizer::VaultOptimizerService;
     use crate::AppState;
     use std::sync::Arc;
diff --git a/frontend/src-tauri/src/commands/settings.rs b/frontend/src-tauri/src/commands/settings.rs
index a9bc074..851d9fa 100644
--- a/frontend/src-tauri/src/commands/settings.rs
+++ b/frontend/src-tauri/src/commands/settings.rs
@@ -72,7 +72,7 @@ pub async fn update_settings(
         rebuild_all_indexes(state.inner()).await?;
         if let Some(new_twin_path) = new_twin_path {
             let mut twin_store = state.twin_store.write().await;
-            *twin_store = crate::services::twin_store::TwinStore::new(new_twin_path);
+            *twin_store = crate::services::twin::TwinStore::new(new_twin_path);
         }
         log::info!("Services rebuilt for new vault path");
     }
diff --git a/frontend/src-tauri/src/main.rs b/frontend/src-tauri/src/main.rs
index 5b3e906..c606f02 100644
--- a/frontend/src-tauri/src/main.rs
+++ b/frontend/src-tauri/src/main.rs
@@ -21,7 +21,7 @@ use services::{
     retrieval::RetrievalService,
     search::SearchService,
     settings::SettingsService,
-    twin_store::TwinStore,
+    twin::TwinStore,
     vault_optimizer::{OptimizerTick, VaultOptimizerService},
 };
 use std::sync::Arc;
diff --git a/frontend/src-tauri/src/services/mod.rs b/frontend/src-tauri/src/services/mod.rs
index 5f45528..3e3c20c 100644
--- a/frontend/src-tauri/src/services/mod.rs
+++ b/frontend/src-tauri/src/services/mod.rs
@@ -18,7 +18,7 @@ pub mod settings;
 pub mod similarity;
 pub mod texttiling;
 pub mod topic_hub;
-pub mod twin_store;
+pub mod twin;
 pub mod utf8_chunk;
 pub mod vault_optimizer;
 pub mod yake;
diff --git a/frontend/src-tauri/src/services/twin_store.rs b/frontend/src-tauri/src/services/twin/mod.rs
similarity index 100%
rename from frontend/src-tauri/src/services/twin_store.rs
rename to frontend/src-tauri/src/services/twin/mod.rs

From 50641d01d38964e17ea4812b67e424b677f02197 Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 15:47:40 +0800
Subject: [PATCH 09/30] refactor: extract twin::shared

Moves the quarantine/load-or-quarantine file helpers and cross-cutting
text/payload utilities (lexical_terms, excerpt, payload_string family,
event-text extraction) into services/twin/shared.rs. These are used by
every remaining domain (records, constitution, decisions, digest,
traces) via `pub(super)` visibility, so mod.rs gains `use shared::*;`
for its still-inline code. Verbatim move; corrupt-file quarantine test
suite (Task 1.5 coverage) moves with load_or_quarantine since it
exercises the shared helper across every domain's listing loop.
---
 frontend/src-tauri/src/services/twin/mod.rs   | 9943 ++++++++---------
 .../src-tauri/src/services/twin/shared.rs     |  600 +
 2 files changed, 5296 insertions(+), 5247 deletions(-)
 create mode 100644 frontend/src-tauri/src/services/twin/shared.rs

diff --git a/frontend/src-tauri/src/services/twin/mod.rs b/frontend/src-tauri/src/services/twin/mod.rs
index b626ad5..195ee13 100644
--- a/frontend/src-tauri/src/services/twin/mod.rs
+++ b/frontend/src-tauri/src/services/twin/mod.rs
@@ -28,16 +28,19 @@ use std::path::{Path, PathBuf};
 use std::time::{SystemTime, UNIX_EPOCH};
 use walkdir::WalkDir;
 
-const DEFAULT_EVAL_PERCENTAGE: u8 = 10;
-const DEFAULT_HOLDOUT_PERCENTAGE: u8 = 10;
-const TWIN_INFERENCE_VERSION: &str = "local-signal-v1";
+mod shared;
+
+use shared::*;
+
 const AUTO_PROMOTE_CONFIDENCE: f32 = 0.75;
 const AUTO_PROMOTE_SUPPORT_COUNT: usize = 3;
-const EXCERPT_MAX_CHARS: usize = 220;
+const TWIN_INFERENCE_VERSION: &str = "local-signal-v1";
 const MAX_TWIN_CANDIDATE_CONTEXT_RECORDS: usize = 8;
 const MAX_TWIN_APPROVED_CONTEXT_RECORDS: usize = 12;
 const MAX_TWIN_APPROVED_FALLBACK_RECORDS: usize = 3;
 const MAX_MEMORY_DIGEST_ITEMS: usize = 5;
+const DEFAULT_EVAL_PERCENTAGE: u8 = 10;
+const DEFAULT_HOLDOUT_PERCENTAGE: u8 = 10;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 enum ExportSplit {
@@ -46,2220 +49,1825 @@ enum ExportSplit {
     Holdout,
 }
 
-#[derive(Debug)]
-pub struct TwinStore {
-    root_path: PathBuf,
-    traces_path: PathBuf,
-    records_path: PathBuf,
-    decisions_path: PathBuf,
-    reflections_path: PathBuf,
-    constitution_path: PathBuf,
-    action_gaps_path: PathBuf,
-    setup_path: PathBuf,
-    decision_mirror_config_path: PathBuf,
-    digest_path: PathBuf,
-    exports_path: PathBuf,
-    trace_cache: HashMap<String, SessionTrace>,
-    record_cache: HashMap<String, UserRecord>,
-    records_cache_ready: bool,
-}
-
-impl TwinStore {
-    pub fn new(root_path: PathBuf) -> Self {
-        let traces_path = root_path.join("traces");
-        let records_path = root_path.join("records");
-        let decisions_path = root_path.join("decisions");
-        let reflections_path = root_path.join("reflections");
-        let constitution_path = root_path.join("constitution");
-        let action_gaps_path = root_path.join("action_gaps");
-        let setup_path = root_path.join("constitution_setup.json");
-        let decision_mirror_config_path = root_path.join("decision_mirror_config.json");
-        let digest_path = root_path.join("memory_digest.json");
-        let exports_path = root_path.join("exports");
-
-        std::fs::create_dir_all(&traces_path).ok();
-        std::fs::create_dir_all(&records_path).ok();
-        std::fs::create_dir_all(&decisions_path).ok();
-        std::fs::create_dir_all(&reflections_path).ok();
-        std::fs::create_dir_all(&constitution_path).ok();
-        std::fs::create_dir_all(&action_gaps_path).ok();
-        std::fs::create_dir_all(&exports_path).ok();
-
-        Self {
-            root_path,
-            traces_path,
-            records_path,
-            decisions_path,
-            reflections_path,
-            constitution_path,
-            action_gaps_path,
-            setup_path,
-            decision_mirror_config_path,
-            digest_path,
-            exports_path,
-            trace_cache: HashMap::new(),
-            record_cache: HashMap::new(),
-            records_cache_ready: false,
-        }
-    }
+fn resolve_event_evidence(
+    trace: &SessionTrace,
+    event: &TraceEvent,
+    evidence_ref: &EvidenceRef,
+) -> ResolvedEvidenceRef {
+    let prompt_excerpt = first_payload_string(
+        &event.payload,
+        &[
+            &["prompt"],
+            &["response", "prompt"],
+            &["evidence", "prompt"],
+            &["ranked_responses", "0", "response", "prompt"],
+        ],
+    )
+    .map(|value| excerpt(&value));
 
-    pub fn append_trace_event(
-        &mut self,
-        session_id: &str,
-        event_type: TraceEventType,
-        payload: serde_json::Value,
-    ) -> Result<TraceEvent> {
-        Self::validate_file_id(session_id)?;
-        let now = Utc::now();
-        let event = TraceEvent {
-            id: uuid::Uuid::new_v4().to_string(),
-            event_type,
-            created_at: now,
-            payload,
-        };
+    let response_excerpt = first_payload_string(
+        &event.payload,
+        &[
+            &["content"],
+            &["response", "response_content"],
+            &["response", "response_excerpt"],
+            &["evidence", "response_content"],
+            &["ranked_responses", "0", "response", "response_content"],
+            &["ranked_responses", "0", "response_excerpt"],
+        ],
+    )
+    .map(|value| excerpt(&value));
 
-        let trace = self.get_or_create_trace_mut(session_id)?;
-        trace.updated_at = now;
-        trace.events.push(event.clone());
-        let trace = trace.clone();
-        self.write_trace_file(&trace)?;
+    let model_name = first_payload_string(
+        &event.payload,
+        &[
+            &["model_name"],
+            &["response", "model_name"],
+            &["evidence", "model_name"],
+            &["ranked_responses", "0", "response", "model_name"],
+        ],
+    );
 
-        Ok(event)
+    ResolvedEvidenceRef {
+        trace_id: evidence_ref.trace_id.clone(),
+        event_id: event.id.clone(),
+        session_id: trace.session_id.clone(),
+        tile_id: evidence_ref
+            .tile_id
+            .clone()
+            .or_else(|| extract_event_tile_id(&event.payload)),
+        model_id: evidence_ref
+            .model_id
+            .clone()
+            .or_else(|| extract_event_model_id(&event.payload)),
+        event_type: event.event_type.clone(),
+        created_at: event.created_at,
+        note: evidence_ref.note.clone(),
+        summary: Some(event_summary(
+            event,
+            prompt_excerpt.as_deref(),
+            response_excerpt.as_deref(),
+        )),
+        prompt_excerpt,
+        response_excerpt,
+        model_name,
+        source_type: evidence_ref.source_type.clone(),
+        source_id: evidence_ref.source_id.clone(),
+        source_label: evidence_ref.source_label.clone(),
+        excerpt: evidence_ref.excerpt.clone(),
+        speaker_role: evidence_ref.speaker_role.clone(),
+        payload: event.payload.clone(),
     }
+}
 
-    pub fn get_session_trace(&mut self, session_id: &str) -> Result<SessionTrace> {
-        Self::validate_file_id(session_id)?;
-        if let Some(trace) = self.trace_cache.get(session_id) {
-            return Ok(trace.clone());
+fn event_summary(
+    event: &TraceEvent,
+    prompt_excerpt: Option<&str>,
+    response_excerpt: Option<&str>,
+) -> String {
+    match &event.event_type {
+        TraceEventType::PromptSubmitted => {
+            format!(
+                "Prompt submitted: {}",
+                prompt_excerpt.unwrap_or("no prompt excerpt")
+            )
         }
-
-        let path = self.trace_file_path(session_id);
-        if !path.exists() {
-            let trace = SessionTrace::new(session_id);
-            self.trace_cache
-                .insert(session_id.to_string(), trace.clone());
-            return Ok(trace);
+        TraceEventType::ResponseCompleted => {
+            format!(
+                "Response completed: {}",
+                response_excerpt.unwrap_or("no response excerpt")
+            )
         }
-
-        let trace = self.read_trace_file(&path)?;
-        self.trace_cache
-            .insert(session_id.to_string(), trace.clone());
-        Ok(trace)
+        TraceEventType::FeedbackRecorded => {
+            let feedback_type = payload_string(&event.payload, &["feedback_type"])
+                .unwrap_or_else(|| "feedback".to_string());
+            format!("{} feedback recorded", feedback_type)
+        }
+        TraceEventType::RankingRecorded => "Response ranking recorded".to_string(),
+        TraceEventType::InsightCaptured => "Explicit twin insight captured".to_string(),
+        TraceEventType::ModelsAdded => "Additional models added for comparison".to_string(),
+        TraceEventType::DebateStarted => "Model debate started".to_string(),
+        TraceEventType::DebateContinued => "Model debate continued".to_string(),
+        TraceEventType::NoteExported => {
+            let title =
+                payload_string(&event.payload, &["title"]).unwrap_or_else(|| "note".to_string());
+            format!("Canvas exported to note: {}", title)
+        }
+        TraceEventType::NoteCanonicalPromoted => "Note promoted to canonical".to_string(),
+        TraceEventType::NoteCreated => "Note created".to_string(),
+        TraceEventType::NoteUpdated => "Note updated".to_string(),
+        _ => format!("{:?}", &event.event_type),
     }
+}
 
-    pub fn list_user_records(&mut self) -> Result<Vec<UserRecord>> {
-        self.ensure_record_cache()?;
-        let mut records: Vec<UserRecord> = self.record_cache.values().cloned().collect();
-        records.sort_by(|a, b| b.updated_at.cmp(&a.updated_at));
-        Ok(records)
-    }
+#[derive(Debug, Clone)]
+struct InferredRecordDraft {
+    inference_key: String,
+    signal_family: String,
+    kind: UserRecordKind,
+    content: String,
+    evidence_refs: Vec<EvidenceRef>,
+    evidence_event_ids: Vec<String>,
+    support_count: usize,
+    confidence: f32,
+}
 
-    pub fn get_user_record(&mut self, id: &str) -> Result<UserRecord> {
-        Self::validate_file_id(id)?;
-        if let Some(record) = self.record_cache.get(id) {
-            return Ok(record.clone());
+#[derive(Debug, Default)]
+struct SignalAccumulator {
+    evidence_refs: Vec<EvidenceRef>,
+    evidence_event_ids: HashSet<String>,
+}
+
+impl SignalAccumulator {
+    fn add_event(&mut self, trace: &SessionTrace, event: &TraceEvent) {
+        if !self.evidence_event_ids.insert(event.id.clone()) {
+            return;
         }
 
-        let path = self.record_file_path(id);
-        let record = self.read_record_file(&path)?;
-        self.record_cache.insert(id.to_string(), record.clone());
-        Ok(record)
+        self.evidence_refs.push(EvidenceRef {
+            trace_id: trace.id.clone(),
+            event_id: event.id.clone(),
+            session_id: trace.session_id.clone(),
+            tile_id: extract_event_tile_id(&event.payload),
+            model_id: extract_event_model_id(&event.payload),
+            note: evidence_note(event),
+            source_type: Some("behavior".to_string()),
+            source_id: Some(event.id.clone()),
+            source_label: evidence_note(event),
+            excerpt: Some(excerpt(&event_text(event))),
+            speaker_role: None,
+        });
     }
+}
 
-    pub fn get_decision_mirror_config(&self) -> Result<DecisionMirrorConfig> {
-        if !self.decision_mirror_config_path.exists() {
-            return Ok(DecisionMirrorConfig::default());
-        }
+fn infer_behavioral_records(traces: &[SessionTrace]) -> Vec<InferredRecordDraft> {
+    let mut signals: HashMap<String, SignalAccumulator> = HashMap::new();
 
-        let content =
-            std::fs::read_to_string(&self.decision_mirror_config_path).with_context(|| {
-                format!(
-                    "Failed to read decision mirror config {}",
-                    self.decision_mirror_config_path.display()
-                )
-            })?;
-        let mut config: DecisionMirrorConfig =
-            serde_json::from_str(&content).context("Failed to parse decision mirror config")?;
-        config.weights = clamp_decision_mirror_weights(config.weights);
-        Ok(config)
-    }
+    for trace in traces {
+        for event in &trace.events {
+            match &event.event_type {
+                TraceEventType::PromptSubmitted => {
+                    let prompt = payload_string(&event.payload, &["prompt"]).unwrap_or_default();
+                    if event
+                        .payload
+                        .get("parent_tile_id")
+                        .is_some_and(|value| !value.is_null())
+                    {
+                        add_signal(&mut signals, "reasoning.iterative_deepening", trace, event);
+                    }
+                    if text_contains_any(
+                        &prompt,
+                        &["think harder", "revisit", "improve your previous answer"],
+                    ) {
+                        add_signal(&mut signals, "reasoning.iterative_deepening", trace, event);
+                    }
+                    if text_contains_any(
+                        &prompt,
+                        &[
+                            "implement",
+                            "fix",
+                            "test",
+                            "build",
+                            "file",
+                            "branch",
+                            "worktree",
+                        ],
+                    ) {
+                        add_signal(
+                            &mut signals,
+                            "preference.implementation_detail",
+                            trace,
+                            event,
+                        );
+                    }
+                    if payload_string(&event.payload, &["context_mode"])
+                        .is_some_and(|mode| mode == "knowledge_search" || mode == "semantic")
+                    {
+                        add_signal(&mut signals, "preference.grounded_context", trace, event);
+                    }
+                    if value_contains_key(&event.payload, "twin_domain") {
+                        add_signal(&mut signals, "fact.twin_domain_metadata", trace, event);
+                    }
+                }
+                TraceEventType::FeedbackRecorded => {
+                    let feedback_type =
+                        payload_string(&event.payload, &["feedback_type"]).unwrap_or_default();
+                    let text = event_text(event);
 
-    pub fn update_decision_mirror_config(
-        &self,
-        update: DecisionMirrorConfigUpdate,
-    ) -> Result<DecisionMirrorConfig> {
-        let mut config = self.get_decision_mirror_config()?;
-        if let Some(preset) = update.preset {
-            config.weights = DecisionMirrorWeights::for_preset(&preset);
-            config.preset = preset;
-        }
-        if let Some(weights) = update.weights {
-            config.weights = clamp_decision_mirror_weights(weights);
-        }
-        if let Some(advanced_enabled) = update.advanced_enabled {
-            config.advanced_enabled = advanced_enabled;
+                    match feedback_type.as_str() {
+                        "accept" => {
+                            if looks_structured(&text) {
+                                add_signal(
+                                    &mut signals,
+                                    "preference.structured_answers",
+                                    trace,
+                                    event,
+                                );
+                            }
+                            if looks_evidence_backed(&text) {
+                                add_signal(
+                                    &mut signals,
+                                    "preference.evidence_backed_detail",
+                                    trace,
+                                    event,
+                                );
+                            }
+                            if looks_implementation_detailed(&text) {
+                                add_signal(
+                                    &mut signals,
+                                    "preference.implementation_detail",
+                                    trace,
+                                    event,
+                                );
+                            }
+                        }
+                        "reject" => {
+                            add_signal(&mut signals, "preference.rejects_mismatch", trace, event);
+                        }
+                        "correction" => {
+                            add_signal(&mut signals, "preference.rejects_mismatch", trace, event);
+                            add_signal(&mut signals, "reasoning.corrects_ai_outputs", trace, event);
+                        }
+                        _ => {}
+                    }
+                }
+                TraceEventType::RankingRecorded => {
+                    add_signal(&mut signals, "reasoning.model_comparison", trace, event);
+                    let text = event_text(event);
+                    if looks_structured(&text) {
+                        add_signal(&mut signals, "preference.structured_answers", trace, event);
+                    }
+                    if looks_evidence_backed(&text) {
+                        add_signal(
+                            &mut signals,
+                            "preference.evidence_backed_detail",
+                            trace,
+                            event,
+                        );
+                    }
+                    if looks_implementation_detailed(&text) {
+                        add_signal(
+                            &mut signals,
+                            "preference.implementation_detail",
+                            trace,
+                            event,
+                        );
+                    }
+                }
+                TraceEventType::InsightCaptured => {
+                    add_signal(
+                        &mut signals,
+                        "reasoning.captures_self_knowledge",
+                        trace,
+                        event,
+                    );
+                }
+                TraceEventType::ModelsAdded => {
+                    add_signal(&mut signals, "reasoning.model_comparison", trace, event);
+                }
+                TraceEventType::DebateStarted | TraceEventType::DebateContinued => {
+                    add_signal(&mut signals, "reasoning.model_comparison", trace, event);
+                    add_signal(&mut signals, "reasoning.uses_debate", trace, event);
+                }
+                TraceEventType::NoteExported => {
+                    add_signal(
+                        &mut signals,
+                        "reasoning.curates_evidence_notes",
+                        trace,
+                        event,
+                    );
+                }
+                TraceEventType::NoteCanonicalPromoted => {
+                    add_signal(&mut signals, "reasoning.canonical_validation", trace, event);
+                }
+                TraceEventType::NoteCreated | TraceEventType::NoteUpdated => {
+                    if value_contains_key(&event.payload, "twin_domain") {
+                        add_signal(&mut signals, "fact.twin_domain_metadata", trace, event);
+                    }
+                    if payload_string(&event.payload, &["status"])
+                        .is_some_and(|status| status == "canonical")
+                    {
+                        add_signal(&mut signals, "reasoning.canonical_validation", trace, event);
+                    }
+                }
+                _ => {}
+            }
         }
-
-        self.write_decision_mirror_config_file(&config)?;
-        Ok(config)
-    }
-
-    pub fn reset_decision_mirror_config(&self) -> Result<DecisionMirrorConfig> {
-        let config = DecisionMirrorConfig::default();
-        self.write_decision_mirror_config_file(&config)?;
-        Ok(config)
     }
 
-    pub fn create_user_record(&mut self, create: UserRecordCreate) -> Result<UserRecord> {
-        self.ensure_record_cache()?;
-
-        let now = Utc::now();
-        let promotion_state = create
-            .promotion_state
-            .unwrap_or_else(|| PromotionState::default_for_origin(&create.origin));
+    let mut drafts = signals
+        .into_iter()
+        .filter_map(|(key, accumulator)| {
+            let support_count = accumulator.evidence_refs.len();
+            if support_count == 0 {
+                return None;
+            }
 
-        let record = UserRecord {
-            id: uuid::Uuid::new_v4().to_string(),
-            kind: create.kind,
-            content: create.content,
-            evidence_refs: create.evidence_refs,
-            confidence: create.confidence.clamp(0.0, 1.0),
-            origin: create.origin,
-            promotion_state,
-            created_at: now,
-            updated_at: now,
-            valid_from: create.valid_from,
-            valid_until: create.valid_until,
-            links: create.links,
-            metadata: create.metadata,
-        };
+            let (kind, signal_family, content) = signal_definition(&key)?;
+            let mut evidence_event_ids = accumulator
+                .evidence_event_ids
+                .into_iter()
+                .collect::<Vec<_>>();
+            evidence_event_ids.sort();
 
-        self.record_cache.insert(record.id.clone(), record.clone());
-        self.write_record_file(&record)?;
+            Some(InferredRecordDraft {
+                inference_key: key,
+                signal_family: signal_family.to_string(),
+                kind,
+                content: content.to_string(),
+                confidence: confidence_for_support(support_count),
+                support_count,
+                evidence_refs: accumulator.evidence_refs,
+                evidence_event_ids,
+            })
+        })
+        .collect::<Vec<_>>();
 
-        Ok(record)
-    }
+    drafts.sort_by(|a, b| a.inference_key.cmp(&b.inference_key));
+    drafts
+}
 
-    pub fn update_user_record(&mut self, id: &str, update: UserRecordUpdate) -> Result<UserRecord> {
-        self.ensure_record_cache()?;
-        let mut record = self.get_user_record(id)?;
+fn add_signal(
+    signals: &mut HashMap<String, SignalAccumulator>,
+    key: &str,
+    trace: &SessionTrace,
+    event: &TraceEvent,
+) {
+    signals
+        .entry(key.to_string())
+        .or_default()
+        .add_event(trace, event);
+}
 
-        if let Some(content) = update.content {
-            record.content = content;
-        }
-        if let Some(confidence) = update.confidence {
-            record.confidence = confidence.clamp(0.0, 1.0);
-        }
-        if let Some(promotion_state) = update.promotion_state {
-            record.promotion_state = promotion_state;
-        }
-        if let Some(valid_from) = update.valid_from {
-            record.valid_from = Some(valid_from);
-        }
-        if let Some(valid_until) = update.valid_until {
-            record.valid_until = Some(valid_until);
-        }
-        if let Some(links) = update.links {
-            record.links = links;
-        }
-        if let Some(metadata) = update.metadata {
-            record.metadata = metadata;
-        }
+fn signal_definition(key: &str) -> Option<(UserRecordKind, &'static str, &'static str)> {
+    match key {
+        "fact.twin_domain_metadata" => Some((
+            UserRecordKind::Fact,
+            "twin_domain",
+            "Uses twin_domain metadata to separate captured knowledge by the domain it belongs to.",
+        )),
+        "preference.structured_answers" => Some((
+            UserRecordKind::Preference,
+            "explicit_feedback",
+            "Prefers structured answers with headings, lists, or clear steps when judging model output.",
+        )),
+        "preference.evidence_backed_detail" => Some((
+            UserRecordKind::Preference,
+            "explicit_feedback",
+            "Prefers evidence-backed implementation detail over generic summary.",
+        )),
+        "preference.implementation_detail" => Some((
+            UserRecordKind::Preference,
+            "passive_prompting",
+            "Prefers answers that include concrete implementation details such as files, commands, tests, or code.",
+        )),
+        "preference.grounded_context" => Some((
+            UserRecordKind::Preference,
+            "passive_prompting",
+            "Uses existing notes as grounding context when asking models to reason.",
+        )),
+        "preference.rejects_mismatch" => Some((
+            UserRecordKind::Preference,
+            "explicit_feedback",
+            "Rejects or corrects responses that do not match their knowledge instead of saving them as truth.",
+        )),
+        "reasoning.corrects_ai_outputs" => Some((
+            UserRecordKind::ReasoningPattern,
+            "explicit_feedback",
+            "Provides corrections when model output conflicts with what they know.",
+        )),
+        "reasoning.iterative_deepening" => Some((
+            UserRecordKind::ReasoningPattern,
+            "branching",
+            "Revisits answers through branches or think-harder passes before treating them as settled.",
+        )),
+        "reasoning.model_comparison" => Some((
+            UserRecordKind::ReasoningPattern,
+            "model_selection",
+            "Compares multiple model outputs before selecting what matches their thinking.",
+        )),
+        "reasoning.uses_debate" => Some((
+            UserRecordKind::ReasoningPattern,
+            "debate_selection",
+            "Uses model debate or disagreement to test alternatives before deciding what to keep.",
+        )),
+        "reasoning.captures_self_knowledge" => Some((
+            UserRecordKind::ReasoningPattern,
+            "explicit_feedback",
+            "Captures durable facts, preferences, or reasoning patterns as explicit twin records.",
+        )),
+        "reasoning.curates_evidence_notes" => Some((
+            UserRecordKind::ReasoningPattern,
+            "note_export",
+            "Turns useful canvas work into durable evidence notes.",
+        )),
+        "reasoning.canonical_validation" => Some((
+            UserRecordKind::ReasoningPattern,
+            "canonical_promotion",
+            "Promotes knowledge to canonical notes after review or repeated validation.",
+        )),
+        _ => None,
+    }
+}
 
-        record.updated_at = Utc::now();
-        self.record_cache.insert(record.id.clone(), record.clone());
-        self.write_record_file(&record)?;
+fn confidence_for_support(support_count: usize) -> f32 {
+    (0.45 + support_count as f32 * 0.10).min(0.95)
+}
 
-        Ok(record)
+fn build_inference_metadata(
+    draft: &InferredRecordDraft,
+    auto_promoted: bool,
+) -> HashMap<String, Value> {
+    json!({
+        "inference_key": draft.inference_key,
+        "inference_version": TWIN_INFERENCE_VERSION,
+        "signal_family": draft.signal_family,
+        "support_count": draft.support_count,
+        "evidence_event_ids": draft.evidence_event_ids,
+        "auto_promoted": auto_promoted,
+    })
+    .as_object()
+    .cloned()
+    .unwrap_or_default()
+    .into_iter()
+    .collect()
+}
+
+fn merge_promotion_history(
+    existing: HashMap<String, Value>,
+    mut next: HashMap<String, Value>,
+) -> HashMap<String, Value> {
+    for (key, value) in existing {
+        next.entry(key).or_insert(value);
     }
+    next
+}
 
-    pub fn run_twin_inference(&mut self) -> Result<TwinInferenceRunSummary> {
-        self.ensure_record_cache()?;
-        let traces = self.list_session_traces()?;
-        let scanned_events = traces.iter().map(|trace| trace.events.len()).sum::<usize>();
-        let drafts = infer_behavioral_records(&traces);
+fn append_promotion_history(
+    metadata: &mut HashMap<String, Value>,
+    from: &PromotionState,
+    to: &PromotionState,
+    rationale: Option<&str>,
+    automatic: bool,
+) {
+    let mut history = metadata
+        .get("promotion_history")
+        .and_then(Value::as_array)
+        .cloned()
+        .unwrap_or_default();
 
-        let mut existing_by_key = HashMap::new();
-        let mut rejected_keys = HashSet::new();
-        for record in self.record_cache.values() {
-            if let Some(inference_key) = record
-                .metadata
-                .get("inference_key")
-                .and_then(Value::as_str)
-                .map(ToOwned::to_owned)
-            {
-                existing_by_key.insert(inference_key.clone(), record.id.clone());
-                if record.promotion_state == PromotionState::Rejected {
-                    rejected_keys.insert(inference_key);
-                }
-            }
-        }
+    history.push(json!({
+        "from": from,
+        "to": to,
+        "at": Utc::now(),
+        "rationale": rationale,
+        "automatic": automatic,
+    }));
+    metadata.insert("promotion_history".to_string(), Value::Array(history));
+}
 
-        let mut created_records = 0_usize;
-        let mut updated_records = 0_usize;
-        let mut auto_promoted_records = 0_usize;
-        let mut candidate_records = 0_usize;
-        let mut skipped_rejected_records = 0_usize;
+fn promotion_state_sort_key(state: &PromotionState) -> u8 {
+    match state {
+        PromotionState::AutoPromoted => 0,
+        PromotionState::Candidate => 1,
+        PromotionState::Endorsed => 2,
+        PromotionState::Rejected => 3,
+        PromotionState::Private => 4,
+        PromotionState::NoTrain => 5,
+    }
+}
 
-        for draft in drafts {
-            let desired_state = if draft.confidence >= AUTO_PROMOTE_CONFIDENCE
-                && draft.support_count >= AUTO_PROMOTE_SUPPORT_COUNT
-            {
-                PromotionState::AutoPromoted
-            } else {
-                PromotionState::Candidate
-            };
-            let mut metadata =
-                build_inference_metadata(&draft, desired_state == PromotionState::AutoPromoted);
+fn twin_context_record(record: &UserRecord, source_label: &str) -> TwinContextRecord {
+    TwinContextRecord {
+        id: record.id.clone(),
+        kind: record.kind.clone(),
+        content: record.content.clone(),
+        confidence: record.confidence,
+        promotion_state: record.promotion_state.clone(),
+        evidence_count: record.evidence_refs.len(),
+        source_label: Some(source_label.to_string()),
+    }
+}
 
-            if let Some(existing_id) = existing_by_key.get(&draft.inference_key).cloned() {
-                let mut record = self.get_user_record(&existing_id)?;
-                let previous_state = record.promotion_state.clone();
-                let is_rejected_key = rejected_keys.contains(&draft.inference_key);
+fn twin_record_relevance(record: &UserRecord, query_terms: &HashSet<String>) -> usize {
+    if query_terms.is_empty() {
+        return 0;
+    }
 
-                record.kind = draft.kind.clone();
-                record.content = draft.content.clone();
-                record.evidence_refs = draft.evidence_refs.clone();
-                record.confidence = draft.confidence;
-                record.origin = RecordOrigin::Inferred;
+    let mut haystack = record.content.clone();
+    for evidence in &record.evidence_refs {
+        if let Some(note) = &evidence.note {
+            haystack.push(' ');
+            haystack.push_str(note);
+        }
+    }
+    for value in record.metadata.values() {
+        haystack.push(' ');
+        haystack.push_str(&value.to_string());
+    }
 
-                if is_rejected_key {
-                    metadata.insert("auto_promoted".to_string(), Value::Bool(false));
-                    record.promotion_state = PromotionState::Rejected;
-                    skipped_rejected_records += 1;
-                } else if matches!(
-                    record.promotion_state,
-                    PromotionState::Candidate | PromotionState::AutoPromoted
-                ) {
-                    record.promotion_state = desired_state.clone();
-                }
+    let record_terms = lexical_terms(&haystack);
+    query_terms.intersection(&record_terms).count()
+}
 
-                metadata = merge_promotion_history(record.metadata.clone(), metadata);
-                if previous_state != record.promotion_state {
-                    append_promotion_history(
-                        &mut metadata,
-                        &previous_state,
-                        &record.promotion_state,
-                        Some("local signal inference threshold"),
-                        true,
-                    );
-                }
+fn looks_structured(text: &str) -> bool {
+    text.contains("\n- ")
+        || text.contains("\n* ")
+        || text.contains("\n1. ")
+        || text.contains("##")
+        || text.contains("```")
+}
 
-                record.metadata = metadata;
-                record.updated_at = Utc::now();
-                self.record_cache.insert(record.id.clone(), record.clone());
-                self.write_record_file(&record)?;
-                updated_records += 1;
-            } else {
-                let mut metadata = metadata;
-                if desired_state == PromotionState::AutoPromoted {
-                    append_promotion_history(
-                        &mut metadata,
-                        &PromotionState::Candidate,
-                        &PromotionState::AutoPromoted,
-                        Some("confidence >= 0.75 and support_count >= 3"),
-                        true,
-                    );
-                }
-
-                self.create_user_record(UserRecordCreate {
-                    kind: draft.kind,
-                    content: draft.content,
-                    evidence_refs: draft.evidence_refs,
-                    confidence: draft.confidence,
-                    origin: RecordOrigin::Inferred,
-                    promotion_state: Some(desired_state),
-                    valid_from: None,
-                    valid_until: None,
-                    links: Vec::new(),
-                    metadata,
-                })?;
-                created_records += 1;
-            }
-        }
+fn looks_evidence_backed(text: &str) -> bool {
+    text_contains_any(
+        text,
+        &[
+            "evidence",
+            "source",
+            "according",
+            "because",
+            "verify",
+            "verified",
+            "test",
+            "logs",
+            "tradeoff",
+        ],
+    )
+}
 
-        for record in self.record_cache.values() {
-            if record.origin != RecordOrigin::Inferred {
-                continue;
-            }
-            match record.promotion_state {
-                PromotionState::AutoPromoted => auto_promoted_records += 1,
-                PromotionState::Candidate => candidate_records += 1,
-                _ => {}
-            }
-        }
+fn looks_implementation_detailed(text: &str) -> bool {
+    text_contains_any(
+        text,
+        &[
+            ".rs",
+            ".js",
+            ".vue",
+            "frontend/",
+            "src/",
+            "cargo ",
+            "npm ",
+            "test",
+            "function ",
+            "```",
+            "command",
+            "file",
+        ],
+    )
+}
 
-        Ok(TwinInferenceRunSummary {
-            inference_version: TWIN_INFERENCE_VERSION.to_string(),
-            scanned_traces: traces.len(),
-            scanned_events,
-            created_records,
-            updated_records,
-            auto_promoted_records,
-            candidate_records,
-            skipped_rejected_records,
-            generated_at: Utc::now(),
-        })
-    }
+fn clean_setup_entries(entries: Vec<String>) -> Vec<String> {
+    let mut seen = HashSet::new();
+    entries
+        .into_iter()
+        .map(|entry| entry.trim().to_string())
+        .filter(|entry| !entry.is_empty())
+        .filter(|entry| seen.insert(entry.to_lowercase()))
+        .collect()
+}
 
-    pub fn get_twin_review(&mut self) -> Result<Vec<TwinReviewRecord>> {
-        let records = self.list_user_records()?;
-        let mut review = Vec::with_capacity(records.len());
+fn clean_optional_setup_entry(entry: Option<String>) -> Option<String> {
+    entry
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+}
 
-        for record in records {
-            let evidence = self.resolve_evidence_refs(&record.evidence_refs)?;
-            review.push(TwinReviewRecord {
-                evidence_count: record.evidence_refs.len(),
-                latest_evidence: evidence.into_iter().max_by_key(|item| item.created_at),
-                record,
-            });
-        }
+fn constitution_key(dimension: &str, claim: &str) -> String {
+    format!(
+        "{}::{}",
+        dimension.trim().to_lowercase(),
+        normalize_key_text(claim)
+    )
+}
 
-        review.sort_by(|a, b| {
-            promotion_state_sort_key(&a.record.promotion_state)
-                .cmp(&promotion_state_sort_key(&b.record.promotion_state))
-                .then_with(|| b.record.updated_at.cmp(&a.record.updated_at))
-        });
+fn action_gap_key(stated_value: &str, revealed_behavior: &str) -> String {
+    format!(
+        "{}::{}",
+        normalize_key_text(stated_value),
+        normalize_key_text(revealed_behavior)
+    )
+}
 
-        Ok(review)
-    }
+fn normalize_key_text(text: &str) -> String {
+    text.split_whitespace()
+        .collect::<Vec<_>>()
+        .join(" ")
+        .to_lowercase()
+}
 
-    pub fn select_context_records(
-        &mut self,
-        query: &str,
-    ) -> Result<(Vec<TwinContextRecord>, Vec<TwinContextRecord>)> {
-        self.ensure_record_cache()?;
+fn constitution_allows_record(record: &UserRecord) -> bool {
+    !matches!(
+        record.promotion_state,
+        PromotionState::Rejected | PromotionState::Private | PromotionState::NoTrain
+    ) && record.kind != UserRecordKind::Fact
+}
 
-        let query_terms = lexical_terms(query);
-        let mut approved = Vec::new();
-        let mut approved_fallback = Vec::new();
-        let mut candidates = Vec::new();
+fn behavior_event_for_constitution(event_type: &TraceEventType) -> bool {
+    matches!(
+        event_type,
+        TraceEventType::PromptSubmitted
+            | TraceEventType::FeedbackRecorded
+            | TraceEventType::RankingRecorded
+            | TraceEventType::InsightCaptured
+            | TraceEventType::DebateStarted
+            | TraceEventType::DebateContinued
+            | TraceEventType::NoteExported
+            | TraceEventType::NoteCanonicalPromoted
+            | TraceEventType::DecisionEpisodeCreated
+            | TraceEventType::OutcomeFollowUpRecorded
+    )
+}
 
-        for record in self.record_cache.values() {
-            match record.promotion_state {
-                PromotionState::Endorsed | PromotionState::AutoPromoted => {
-                    let relevance = twin_record_relevance(record, &query_terms);
-                    if relevance > 0 {
-                        approved.push((relevance, twin_context_record(record, "approved")));
-                    } else {
-                        approved_fallback.push(twin_context_record(record, "approved"));
-                    }
-                }
-                PromotionState::Candidate => {
-                    let relevance = twin_record_relevance(record, &query_terms);
-                    if relevance > 0 {
-                        candidates.push((
-                            relevance,
-                            record.updated_at,
-                            twin_context_record(record, "candidate"),
-                        ));
-                    }
-                }
-                PromotionState::Rejected | PromotionState::Private | PromotionState::NoTrain => {}
-            }
+fn constitution_status_from_record(record: &UserRecord) -> ConstitutionStatus {
+    let support_count = record.evidence_refs.len();
+    match record.promotion_state {
+        PromotionState::AutoPromoted | PromotionState::Endorsed
+            if support_count >= AUTO_PROMOTE_SUPPORT_COUNT =>
+        {
+            ConstitutionStatus::Active
         }
-
-        approved.sort_by(|a, b| {
-            b.0.cmp(&a.0).then_with(|| {
-                b.1.confidence
-                    .partial_cmp(&a.1.confidence)
-                    .unwrap_or(std::cmp::Ordering::Equal)
-                    .then_with(|| b.1.evidence_count.cmp(&a.1.evidence_count))
-            })
-        });
-
-        let approved: Vec<TwinContextRecord> = if approved.is_empty() {
-            // Never assemble an empty behavioral context just because the
-            // query shares no keywords with any approved record.
-            approved_fallback.sort_by(|a, b| {
-                b.confidence
-                    .partial_cmp(&a.confidence)
-                    .unwrap_or(std::cmp::Ordering::Equal)
-                    .then_with(|| b.evidence_count.cmp(&a.evidence_count))
-            });
-            approved_fallback
-                .into_iter()
-                .take(MAX_TWIN_APPROVED_FALLBACK_RECORDS)
-                .collect()
-        } else {
-            approved
-                .into_iter()
-                .take(MAX_TWIN_APPROVED_CONTEXT_RECORDS)
-                .map(|(_, record)| record)
-                .collect()
-        };
-
-        candidates.sort_by(|a, b| {
-            b.0.cmp(&a.0).then_with(|| b.1.cmp(&a.1)).then_with(|| {
-                b.2.confidence
-                    .partial_cmp(&a.2.confidence)
-                    .unwrap_or(std::cmp::Ordering::Equal)
-            })
-        });
-
-        Ok((
-            approved,
-            candidates
-                .into_iter()
-                .take(MAX_TWIN_CANDIDATE_CONTEXT_RECORDS)
-                .map(|(_, _, record)| record)
-                .collect(),
-        ))
+        _ => ConstitutionStatus::Candidate,
     }
+}
 
-    pub fn resolve_user_record_evidence(&mut self, id: &str) -> Result<Vec<ResolvedEvidenceRef>> {
-        let record = self.get_user_record(id)?;
-        self.resolve_evidence_refs(&record.evidence_refs)
-    }
+fn constitution_context_allowed(status: &ConstitutionStatus) -> bool {
+    matches!(
+        status,
+        ConstitutionStatus::Active | ConstitutionStatus::Candidate | ConstitutionStatus::Softened
+    )
+}
 
-    pub fn set_user_record_promotion(
-        &mut self,
-        id: &str,
-        promotion_state: PromotionState,
-        rationale: Option<String>,
-    ) -> Result<UserRecord> {
-        self.ensure_record_cache()?;
-        let mut record = self.get_user_record(id)?;
-        let previous_state = record.promotion_state.clone();
-        let now = Utc::now();
-
-        record.promotion_state = promotion_state.clone();
-        record.updated_at = now;
+fn constitution_status_for_action(action: &MemoryDigestAction) -> ConstitutionStatus {
+    match action {
+        MemoryDigestAction::Keep => ConstitutionStatus::Active,
+        MemoryDigestAction::Soften => ConstitutionStatus::Softened,
+        MemoryDigestAction::NotMe => ConstitutionStatus::NotMe,
+        MemoryDigestAction::Private => ConstitutionStatus::Private,
+        MemoryDigestAction::NoTrain => ConstitutionStatus::NoTrain,
+        MemoryDigestAction::Reject => ConstitutionStatus::Rejected,
+    }
+}
 
-        append_promotion_history(
-            &mut record.metadata,
-            &previous_state,
-            &promotion_state,
-            rationale.as_deref(),
-            false,
-        );
+fn constitution_status_sort_key(status: &ConstitutionStatus) -> u8 {
+    match status {
+        ConstitutionStatus::Active => 0,
+        ConstitutionStatus::Candidate => 1,
+        ConstitutionStatus::Softened => 2,
+        ConstitutionStatus::NotMe => 3,
+        ConstitutionStatus::Private => 4,
+        ConstitutionStatus::NoTrain => 5,
+        ConstitutionStatus::Rejected => 6,
+    }
+}
 
-        if promotion_state == PromotionState::Rejected {
-            record
-                .metadata
-                .insert("reverted_at".to_string(), json!(now));
-            record
-                .metadata
-                .insert("revert_reason".to_string(), json!(rationale));
-            record
-                .metadata
-                .insert("auto_promoted".to_string(), Value::Bool(false));
+fn infer_constitution_dimension(content: &str, kind: &UserRecordKind) -> String {
+    let lower = content.to_lowercase();
+    if text_contains_any(&lower, &["taste", "aesthetic", "style", "design", "feel"]) {
+        "taste".to_string()
+    } else if text_contains_any(
+        &lower,
+        &["constraint", "deadline", "budget", "time", "cost"],
+    ) {
+        "constraints".to_string()
+    } else if text_contains_any(&lower, &["somatic", "gut", "body", "energy", "fatigue"]) {
+        "somatic".to_string()
+    } else if text_contains_any(&lower, &["value", "principle", "mission", "care about"]) {
+        "values".to_string()
+    } else {
+        match kind {
+            UserRecordKind::Preference => "preferences".to_string(),
+            UserRecordKind::ReasoningPattern => "reasoning".to_string(),
+            UserRecordKind::Fact => "facts".to_string(),
         }
-
-        self.record_cache.insert(record.id.clone(), record.clone());
-        self.write_record_file(&record)?;
-
-        Ok(record)
     }
+}
 
-    pub fn record_decision_episode(
-        &mut self,
-        create: DecisionEpisodeCreate,
-    ) -> Result<DecisionEpisode> {
-        Self::validate_file_id(&create.id)?;
-        Self::validate_file_id(&create.session_id)?;
-        Self::validate_file_id(&create.tile_id)?;
+fn note_is_interview(note: &Note) -> bool {
+    note.properties
+        .get("source_type")
+        .or_else(|| note.properties.get("source"))
+        .and_then(Value::as_str)
+        .is_some_and(|value| value.eq_ignore_ascii_case("interview"))
+        || note
+            .tags
+            .iter()
+            .any(|tag| tag.eq_ignore_ascii_case("interview"))
+}
 
-        let now = Utc::now();
-        // A prediction is only attempted when there are at least two options
-        // to choose between; record why one will not arrive otherwise.
-        let prediction_status = if create.options.len() >= 2 {
-            Some("requested".to_string())
-        } else {
-            None
-        };
-        let episode = DecisionEpisode {
-            id: create.id,
-            session_id: create.session_id,
-            tile_id: create.tile_id,
-            decision: create.decision,
-            options: create.options,
-            stakes: create.stakes,
-            initial_leaning: create.initial_leaning,
-            selected_response: None,
-            chosen_option: None,
-            confidence: None,
-            review_date: create.review_date,
-            outcome: None,
-            regret_score: None,
-            lesson: None,
-            missed_something: None,
-            primitive_assessment: create.primitive_assessment,
-            twin_prediction: None,
-            prediction_status,
-            agreement: None,
-            correction_note: None,
-            context_version: create.context_version,
-            outcome_recorded_at: None,
-            created_at: now,
-            updated_at: now,
-        };
+#[derive(Debug, Clone)]
+struct InterviewTurn {
+    role: String,
+    content: String,
+}
 
-        self.write_decision_file(&episode)?;
-        self.append_trace_event(
-            &episode.session_id,
-            TraceEventType::DecisionEpisodeCreated,
-            json!({
-                "decision_episode_id": episode.id,
-                "tile_id": episode.tile_id,
-                "decision": episode.decision,
-                "options": episode.options,
-                "stakes": episode.stakes,
-                "initial_leaning": episode.initial_leaning,
-                "review_date": episode.review_date,
-                "primitive_assessment": episode.primitive_assessment,
-            }),
-        )?;
+enum InterviewExtraction {
+    Unlabeled,
+    Labeled {
+        interviewer_turns: Vec<InterviewTurn>,
+        interviewee_turns: Vec<InterviewTurn>,
+    },
+}
 
-        Ok(episode)
+fn extract_interview_note_evidence(note: &Note) -> InterviewExtraction {
+    let turns = extract_markdown_interview_turns(&note.content)
+        .or_else(|| extract_colon_labeled_interview_turns(&note.content));
+    let Some(turns) = turns else {
+        return InterviewExtraction::Unlabeled;
+    };
+    let interviewer_turns = turns
+        .iter()
+        .filter(|turn| turn.role == "user")
+        .cloned()
+        .collect::<Vec<_>>();
+    let interviewee_turns = turns
+        .into_iter()
+        .filter(|turn| turn.role == "interviewee")
+        .collect::<Vec<_>>();
+    if interviewer_turns.is_empty() || interviewee_turns.is_empty() {
+        return InterviewExtraction::Unlabeled;
+    }
+    InterviewExtraction::Labeled {
+        interviewer_turns,
+        interviewee_turns,
     }
+}
 
-    pub fn list_decision_episodes(&self) -> Result<Vec<DecisionEpisode>> {
-        let mut episodes = Vec::new();
-        if !self.decisions_path.exists() {
-            return Ok(episodes);
+fn extract_markdown_interview_turns(content: &str) -> Option<Vec<InterviewTurn>> {
+    let mut turns = Vec::new();
+    let mut current_role: Option<String> = None;
+    let mut current_content = String::new();
+    for line in content.lines() {
+        let trimmed = line.trim();
+        if let Some(role) = markdown_message_role(trimmed) {
+            flush_interview_turn(&mut turns, &mut current_role, &mut current_content);
+            current_role = Some(role);
+            continue;
         }
-
-        for entry in WalkDir::new(&self.decisions_path)
-            .min_depth(1)
-            .max_depth(1)
-            .into_iter()
-            .filter_map(|entry| entry.ok())
-        {
-            let path = entry.path();
-            if path.extension().is_some_and(|ext| ext == "json") {
-                if let Some(episode) =
-                    load_or_quarantine::<DecisionEpisode>(path, "decision episode")
-                {
-                    episodes.push(episode);
-                }
-            }
+        if current_role.is_some() {
+            current_content.push_str(line);
+            current_content.push('\n');
         }
-
-        episodes.sort_by(|a, b| b.updated_at.cmp(&a.updated_at));
-        Ok(episodes)
     }
+    flush_interview_turn(&mut turns, &mut current_role, &mut current_content);
+    if turns.len() >= 2 {
+        Some(turns)
+    } else {
+        None
+    }
+}
 
-    /// Select past decided episodes as verbatim behavioral cases for twin
-    /// context. Correction notes (recorded when a sealed prediction missed)
-    /// break ties between equally relevant cases but never outrank a more
-    /// relevant case.
-    pub fn select_decision_cases(
-        &self,
-        query: &str,
-        exclude_episode_id: Option<&str>,
-        max: usize,
-    ) -> Result<Vec<DecisionEpisode>> {
-        if max == 0 {
-            return Ok(Vec::new());
-        }
-
-        let query_terms = lexical_terms(query);
-        let mut scored = Vec::new();
-        let mut fallback = Vec::new();
+fn markdown_message_role(line: &str) -> Option<String> {
+    let lower = line.to_lowercase();
+    if !(lower.starts_with("### message") || lower.starts_with("## message")) {
+        return None;
+    }
+    if lower.contains("interviewee") || lower.contains("participant") {
+        Some("interviewee".to_string())
+    } else if lower.contains("user")
+        || lower.contains("interviewer")
+        || lower.contains("researcher")
+    {
+        Some("user".to_string())
+    } else {
+        None
+    }
+}
 
-        for episode in self.list_decision_episodes()? {
-            if episode.chosen_option.is_none() {
-                continue;
-            }
-            if exclude_episode_id.is_some_and(|id| id == episode.id) {
-                continue;
-            }
-            let score = decision_case_relevance(&episode, &query_terms);
-            if score > 0 {
-                scored.push((score, episode));
-            } else {
-                fallback.push(episode);
+fn extract_colon_labeled_interview_turns(content: &str) -> Option<Vec<InterviewTurn>> {
+    let mut turns = Vec::new();
+    for line in content.lines() {
+        let Some((speaker, body)) = line.split_once(':') else {
+            continue;
+        };
+        let speaker = speaker.trim().to_lowercase();
+        let role = match speaker.as_str() {
+            "interviewer" | "researcher" | "moderator" | "facilitator" | "me" | "user" => "user",
+            "interviewee" | "participant" | "respondent" | "customer" | "student" | "teacher" => {
+                "interviewee"
             }
+            _ => continue,
+        };
+        let content = body.trim();
+        if !content.is_empty() {
+            turns.push(InterviewTurn {
+                role: role.to_string(),
+                content: content.to_string(),
+            });
         }
+    }
+    if turns.len() >= 2 {
+        Some(turns)
+    } else {
+        None
+    }
+}
 
-        if scored.is_empty() {
-            // No keyword overlap at all: include the most recent decided
-            // cases rather than an empty behavioral context.
-            fallback.sort_by(|a, b| b.updated_at.cmp(&a.updated_at));
-            fallback.truncate(max.min(2));
-            return Ok(fallback);
-        }
-
-        scored.sort_by(|a, b| {
-            b.0.cmp(&a.0)
-                .then_with(|| {
-                    b.1.correction_note
-                        .is_some()
-                        .cmp(&a.1.correction_note.is_some())
-                })
-                .then_with(|| b.1.updated_at.cmp(&a.1.updated_at))
-        });
-
-        Ok(scored
-            .into_iter()
-            .take(max)
-            .map(|(_, episode)| episode)
-            .collect())
+fn flush_interview_turn(
+    turns: &mut Vec<InterviewTurn>,
+    current_role: &mut Option<String>,
+    current_content: &mut String,
+) {
+    let Some(role) = current_role.take() else {
+        return;
+    };
+    let content = current_content.trim().to_string();
+    current_content.clear();
+    if content.is_empty() {
+        return;
     }
+    turns.push(InterviewTurn { role, content });
+}
 
-    pub fn update_decision_outcome(
-        &mut self,
-        id: &str,
-        update: DecisionOutcomeUpdate,
-    ) -> Result<DecisionEpisode> {
-        Self::validate_file_id(id)?;
-        let path = self.decision_file_path(id);
-        let mut episode = self.read_decision_file(&path)?;
+fn constitution_claim_from_interviewer_turn(content: &str) -> Option<(String, String)> {
+    let lower = content.to_lowercase();
+    if text_contains_any(
+        &lower,
+        &[
+            "concrete example",
+            "compare",
+            "why",
+            "how do you",
+            "what makes",
+            "walk me through",
+        ],
+    ) {
+        return Some((
+            "reasoning".to_string(),
+            "Uses interview questions to probe for concrete examples and comparisons before treating claims as useful.".to_string(),
+        ));
+    }
+    None
+}
 
-        if let Some(selected_response) = update.selected_response {
-            episode.selected_response = Some(selected_response);
-        }
-        if let Some(chosen_option) = update.chosen_option {
-            // Canonicalize label/case variants ("b", "Option 2", extra
-            // whitespace) against the recorded options; unmatched free text
-            // is kept as-is (legacy and "other" outcomes stay recordable).
-            let canonical = match_option_index(&chosen_option, &episode.options)
-                .map(|index| episode.options[index].clone())
-                .unwrap_or(chosen_option);
-            episode.chosen_option = Some(canonical);
-        }
-        if let Some(confidence) = update.confidence {
-            episode.confidence = Some(confidence.clamp(0.0, 1.0));
-        }
-        if let Some(review_date) = update.review_date {
-            episode.review_date = Some(review_date);
-        }
-        if let Some(outcome) = update.outcome {
-            episode.outcome = Some(outcome);
-        }
-        if let Some(regret_score) = update.regret_score {
-            episode.regret_score = Some(regret_score.min(10));
-        }
-        if let Some(lesson) = update.lesson {
-            episode.lesson = Some(lesson);
-        }
-        if let Some(missed_something) = update.missed_something {
-            episode.missed_something = Some(missed_something);
-        }
-        if let Some(primitive_assessment) = update.primitive_assessment {
-            episode.primitive_assessment = primitive_assessment;
-        }
-        if let Some(correction_note) = update.correction_note {
-            episode.correction_note = Some(correction_note);
-        }
+fn looks_like_research_finding(content: &str) -> bool {
+    content.split_whitespace().count() >= 8
+        && text_contains_any(
+            content,
+            &[
+                "need", "want", "trust", "frustrat", "prefer", "hard", "easy", "useful", "demo",
+                "workflow",
+            ],
+        )
+}
 
-        if episode.outcome_recorded_at.is_none()
-            && (episode.chosen_option.is_some() || episode.outcome.is_some())
-        {
-            episode.outcome_recorded_at = Some(Utc::now());
-        }
+fn constitution_claim_from_note(note: &Note) -> Option<(String, String)> {
+    if note.is_topic_hub() {
+        return None;
+    }
+    let content = note.content.trim();
+    if content.len() < 24 {
+        return None;
+    }
+    let lower = content.to_lowercase();
+    if !text_contains_any(
+        &lower,
+        &[
+            "i prefer",
+            "i need",
+            "i value",
+            "my reasoning",
+            "works for me",
+            "not me",
+            "i reject",
+            "i decide",
+        ],
+    ) {
+        return None;
+    }
+    if text_contains_any(&lower, &["prefer"]) {
+        Some((
+            "preferences".to_string(),
+            format!("Note-backed preference: {}", excerpt(content)),
+        ))
+    } else {
+        Some((
+            "reasoning".to_string(),
+            format!("Note-backed reasoning pattern: {}", excerpt(content)),
+        ))
+    }
+}
 
-        // Agreement is recomputed whenever both sides exist, so a corrected
-        // chosen_option keeps the stored agreement current. Only predictions
-        // sealed before the outcome was first recorded count.
-        if let (Some(chosen), Some(prediction)) = (&episode.chosen_option, &episode.twin_prediction)
-        {
-            let recorded_at = episode.outcome_recorded_at.unwrap_or_else(Utc::now);
-            if prediction.sealed_at <= recorded_at {
-                episode.agreement = Some(compute_agreement(prediction, chosen, &episode.options));
-            }
-        }
+fn note_evidence_ref(
+    note: &Note,
+    source_type: &str,
+    source_label: &str,
+    speaker_role: Option<&str>,
+    content: &str,
+) -> EvidenceRef {
+    EvidenceRef {
+        trace_id: format!("note-{}", note.id),
+        event_id: note.id.clone(),
+        session_id: "vault-note".to_string(),
+        tile_id: None,
+        model_id: None,
+        note: Some(note.title.clone()),
+        source_type: Some(source_type.to_string()),
+        source_id: Some(note.id.clone()),
+        source_label: Some(source_label.to_string()),
+        excerpt: Some(excerpt(content.trim())),
+        speaker_role: speaker_role.map(ToOwned::to_owned),
+    }
+}
 
-        episode.updated_at = Utc::now();
-        self.write_decision_file(&episode)?;
-        self.append_trace_event(
-            &episode.session_id,
-            TraceEventType::OutcomeFollowUpRecorded,
-            json!({
-                "decision_episode_id": episode.id,
-                "tile_id": episode.tile_id,
-                "selected_response": episode.selected_response,
-                "chosen_option": episode.chosen_option,
-                "confidence": episode.confidence,
-                "review_date": episode.review_date,
-                "outcome": episode.outcome,
-                "regret_score": episode.regret_score,
-                "lesson": episode.lesson,
-                "missed_something": episode.missed_something,
-                "primitive_assessment": episode.primitive_assessment,
-                "agreement": episode.agreement,
-                "correction_note": episode.correction_note,
-                "prediction_context_version": episode
-                    .twin_prediction
-                    .as_ref()
-                    .map(|prediction| prediction.context_version.clone()),
-            }),
-        )?;
+fn distill_constitution_setup_from_notes(notes: &[Note]) -> ConstitutionSetup {
+    let mut setup = ConstitutionSetup::default();
+    let mut saw_interview_question = false;
+    let mut saw_values_question = false;
+    let mut saw_tradeoff_question = false;
+    let mut saw_risk_question = false;
+    let mut saw_concrete_question = false;
+    let mut saw_followup_question = false;
+    let mut saw_user_note_preference = false;
+    let mut interviewer_question_count = 0_usize;
 
-        Ok(episode)
-    }
+    for note in notes {
+        if note.is_topic_hub() {
+            continue;
+        }
 
-    /// Seal a twin prediction onto an episode. Refuses (as a logged no-op
-    /// returning the unchanged episode) when the outcome is already recorded
-    /// or a prediction already exists, so `sealed_at` always precedes the
-    /// outcome structurally. The trace payload never contains the predicted
-    /// option — the trace viewer must not leak a sealed prediction.
-    pub fn attach_twin_prediction(
-        &mut self,
-        episode_id: &str,
-        draft: TwinPredictionDraft,
-        model_id: &str,
-        context_version: &str,
-    ) -> Result<DecisionEpisode> {
-        Self::validate_file_id(episode_id)?;
-        let path = self.decision_file_path(episode_id);
-        let mut episode = self.read_decision_file(&path)?;
-
-        if episode.chosen_option.is_some() {
-            log::warn!(
-                "Twin prediction for episode {} arrived after the outcome was recorded; discarding",
-                episode_id
-            );
-            episode.prediction_status = Some("outcome_recorded_first".to_string());
-            episode.updated_at = Utc::now();
-            self.write_decision_file(&episode)?;
-            return Ok(episode);
+        if note_is_interview(note) {
+            if let InterviewExtraction::Labeled {
+                interviewer_turns, ..
+            } = extract_interview_note_evidence(note)
+            {
+                for turn in interviewer_turns {
+                    let lower = turn.content.to_lowercase();
+                    if turn.content.split_whitespace().count() < 5 {
+                        continue;
+                    }
+                    saw_interview_question = true;
+                    interviewer_question_count += 1;
+                    if text_contains_any(&lower, &["value", "cultural", "drives your decision"]) {
+                        saw_values_question = true;
+                    }
+                    if text_contains_any(&lower, &["trade off", "trade-off", "balance"]) {
+                        saw_tradeoff_question = true;
+                    }
+                    if text_contains_any(&lower, &["risk", "comfortable taking", "actively avoid"])
+                    {
+                        saw_risk_question = true;
+                    }
+                    if text_contains_any(
+                        &lower,
+                        &[
+                            "example",
+                            "walk us through",
+                            "walk through",
+                            "concrete",
+                            "top two",
+                        ],
+                    ) {
+                        saw_concrete_question = true;
+                    }
+                    if text_contains_any(
+                        &lower,
+                        &["following up", "if i understand", "drill", "how would"],
+                    ) {
+                        saw_followup_question = true;
+                    }
+                }
+            }
+            continue;
         }
-        if episode.twin_prediction.is_some() {
-            log::warn!(
-                "Episode {} already has a sealed twin prediction; ignoring duplicate",
-                episode_id
-            );
-            return Ok(episode);
+
+        if let Some((dimension, claim)) = constitution_claim_from_note(note) {
+            saw_user_note_preference = true;
+            match dimension.as_str() {
+                "preferences" => push_unique(&mut setup.tastes, claim),
+                "constraints" => push_unique(&mut setup.constraints, claim),
+                "action_tendency" => push_unique(&mut setup.action_tendencies, claim),
+                _ => push_unique(&mut setup.values, claim),
+            }
         }
+    }
 
-        let prediction = TwinPrediction {
-            predicted_option: draft.predicted_option,
-            matched_option_index: draft.matched_option_index,
-            confidence: draft.confidence,
-            rationale: draft.rationale,
-            parse_mode: draft.parse_mode.clone(),
-            model_id: model_id.to_string(),
-            context_version: context_version.to_string(),
-            sealed_at: Utc::now(),
-        };
-        let sealed_at = prediction.sealed_at;
-        episode.twin_prediction = Some(prediction);
-        episode.prediction_status = Some("sealed".to_string());
-        episode.updated_at = Utc::now();
-        self.write_decision_file(&episode)?;
+    if saw_interview_question {
+        push_unique(
+            &mut setup.constraints,
+            "Keeps interviewee answers as research evidence rather than treating them as the user's own Constitution.".to_string(),
+        );
+        push_unique(
+            &mut setup.constraints,
+            "Requires speaker-labelled evidence before extracting Constitution or research findings.".to_string(),
+        );
+    }
+    if saw_values_question {
+        push_unique(
+            &mut setup.values,
+            "Probes for the values and cultural assumptions behind decisions, not only the visible decision outcome.".to_string(),
+        );
+    }
+    if saw_tradeoff_question {
+        push_unique(
+            &mut setup.values,
+            "Treats important choices as tradeoffs between innovation, stability, impact, and institutional responsibility.".to_string(),
+        );
+    }
+    if saw_risk_question {
+        push_unique(
+            &mut setup.constraints,
+            "Separates acceptable experiments from risks that harm people, courses, or institutional trust.".to_string(),
+        );
+    }
+    if saw_concrete_question {
+        push_unique(
+            &mut setup.tastes,
+            "Prefers concrete walkthroughs, examples, and decision stories over abstract positioning.".to_string(),
+        );
+    }
+    if saw_followup_question || (interviewer_question_count > 1 && saw_concrete_question) {
+        push_unique(
+            &mut setup.action_tendencies,
+            "Uses follow-up questions to move from broad narrative into specific decisions, assumptions, criteria, and consequences.".to_string(),
+        );
+    }
+    if saw_user_note_preference {
+        push_unique(
+            &mut setup.action_tendencies,
+            "Turns user-authored note evidence into reviewable Constitution candidates instead of accepting it silently.".to_string(),
+        );
+    }
 
-        self.append_trace_event(
-            &episode.session_id,
-            TraceEventType::TwinPredictionSealed,
-            json!({
-                "decision_episode_id": episode.id,
-                "tile_id": episode.tile_id,
-                "model_id": model_id,
-                "context_version": context_version,
-                "parse_mode": draft.parse_mode,
-                "sealed_at": sealed_at,
-            }),
-        )?;
+    setup
+}
 
-        Ok(episode)
+fn constitution_setup_entry_count(setup: &ConstitutionSetup) -> usize {
+    setup.values.len()
+        + setup.tastes.len()
+        + setup.constraints.len()
+        + setup.somatic_cues.len()
+        + setup.action_tendencies.len()
+}
+
+fn constitution_setup_claims(setup: &ConstitutionSetup) -> HashSet<String> {
+    setup
+        .values
+        .iter()
+        .chain(setup.tastes.iter())
+        .chain(setup.constraints.iter())
+        .chain(setup.somatic_cues.iter())
+        .chain(setup.action_tendencies.iter())
+        .map(|entry| entry.trim().to_string())
+        .filter(|entry| !entry.is_empty())
+        .collect()
+}
+
+fn push_unique(entries: &mut Vec<String>, entry: String) {
+    let normalized = entry.trim();
+    if normalized.is_empty() {
+        return;
+    }
+    if !entries
+        .iter()
+        .any(|existing| existing.eq_ignore_ascii_case(normalized))
+    {
+        entries.push(normalized.to_string());
     }
+}
 
-    /// Record that the hidden prediction call failed, so exported episodes
-    /// distinguish "no prediction because the call failed" from "agreed to
-    /// not predict" — silent gaps would inflate measured accuracy.
-    pub fn mark_twin_prediction_failed(&mut self, episode_id: &str) -> Result<()> {
-        Self::validate_file_id(episode_id)?;
-        let path = self.decision_file_path(episode_id);
-        let mut episode = self.read_decision_file(&path)?;
-        if episode.twin_prediction.is_some() || episode.chosen_option.is_some() {
-            return Ok(());
+fn constitution_item_is_vault_derived(item: &ConstitutionItem) -> bool {
+    matches!(
+        item.source.as_deref(),
+        Some("note_inference")
+            | Some("interview_behavior_inference")
+            | Some("interview_research_inference")
+    ) || item.evidence_refs.iter().any(|evidence| {
+        matches!(
+            evidence.source_type.as_deref(),
+            Some("note") | Some("interview-question") | Some("interview-answer")
+        )
+    })
+}
+
+fn record_is_vault_derived(record: &UserRecord) -> bool {
+    record.metadata.get("source_note_id").is_some()
+        || matches!(
+            record.metadata.get("source_type").and_then(Value::as_str),
+            Some("interview_answer") | Some("note")
+        )
+        || record.evidence_refs.iter().any(|evidence| {
+            matches!(
+                evidence.source_type.as_deref(),
+                Some("note") | Some("interview-question") | Some("interview-answer")
+            )
+        })
+}
+
+fn split_action_gap_claim(content: &str) -> Option<(String, String)> {
+    let lowered = content.to_lowercase();
+    for separator in [" but ", " however ", " yet ", " although "] {
+        if let Some(index) = lowered.find(separator) {
+            let left = content[..index].trim();
+            let right = content[index + separator.len()..].trim();
+            if left.len() >= 8 && right.len() >= 8 {
+                return Some((left.to_string(), right.to_string()));
+            }
         }
-        episode.prediction_status = Some("failed".to_string());
-        episode.updated_at = Utc::now();
-        self.write_decision_file(&episode)
     }
+    None
+}
 
-    pub fn record_reflection_card(
-        &mut self,
-        create: ReflectionCardCreate,
-    ) -> Result<ReflectionCard> {
-        Self::validate_file_id(&create.decision_episode_id)?;
-        Self::validate_file_id(&create.session_id)?;
-        Self::validate_file_id(&create.tile_id)?;
-
-        let config = self.get_decision_mirror_config()?;
-        let mut evidence_packet = match create.evidence_packet.clone() {
-            Some(packet) => packet,
-            None => self.build_decision_evidence_packet(
-                &create.cited_note_ids,
-                &create.cited_user_record_ids,
-                &create.cited_constitution_item_ids,
-                &create.cited_action_gap_ids,
-                &config,
-            )?,
-        };
-        if evidence_packet.config_snapshot.is_none() {
-            evidence_packet.config_snapshot = Some(config.clone());
-        }
-        let scores = score_reflection_card(
-            &create.content,
-            &create.cited_note_ids,
-            &create.cited_user_record_ids,
-            &create.cited_constitution_item_ids,
-            &create.cited_action_gap_ids,
-            &config,
-        );
-        let card = ReflectionCard {
-            id: uuid::Uuid::new_v4().to_string(),
-            decision_episode_id: create.decision_episode_id,
-            session_id: create.session_id,
-            tile_id: create.tile_id,
-            model_id: create.model_id,
-            content: create.content,
-            cited_note_ids: create.cited_note_ids,
-            cited_user_record_ids: create.cited_user_record_ids,
-            cited_constitution_item_ids: create.cited_constitution_item_ids,
-            cited_action_gap_ids: create.cited_action_gap_ids,
-            scores,
-            evidence_packet,
-            created_at: Utc::now(),
-        };
-
-        self.write_reflection_file(&card)?;
-        self.append_trace_event(
-            &card.session_id,
-            TraceEventType::ReflectionCardRecorded,
-            json!({
-                "reflection_card_id": card.id,
-                "decision_episode_id": card.decision_episode_id,
-                "tile_id": card.tile_id,
-                "model_id": card.model_id,
-                "cited_note_ids": card.cited_note_ids,
-                "cited_user_record_ids": card.cited_user_record_ids,
-                "cited_constitution_item_ids": card.cited_constitution_item_ids,
-                "cited_action_gap_ids": card.cited_action_gap_ids,
-                "scores": card.scores,
-                "evidence_packet": card.evidence_packet,
-            }),
-        )?;
-
-        Ok(card)
-    }
-
-    fn build_decision_evidence_packet(
-        &mut self,
-        cited_note_ids: &[String],
-        cited_user_record_ids: &[String],
-        cited_constitution_item_ids: &[String],
-        cited_action_gap_ids: &[String],
-        config: &DecisionMirrorConfig,
-    ) -> Result<DecisionEvidencePacket> {
-        self.ensure_record_cache()?;
-        let weights = &config.weights;
-        let mut selected_sources = Vec::new();
-
-        for id in cited_note_ids {
-            selected_sources.push(DecisionEvidenceSource {
-                source_type: "note".to_string(),
-                id: id.clone(),
-                label: format!("Note {}", id),
-                weight: weights.notes_weight,
-                reason: "Selected by vault retrieval for this decision".to_string(),
-            });
-        }
-
-        for id in cited_user_record_ids {
-            if let Ok(record) = self.get_user_record(id) {
-                let (source_type, weight) = match &record.promotion_state {
-                    PromotionState::Endorsed | PromotionState::AutoPromoted => {
-                        ("approved_record", weights.approved_records_weight)
-                    }
-                    PromotionState::Candidate => {
-                        ("candidate_record", weights.candidate_records_weight)
-                    }
-                    PromotionState::Rejected
-                    | PromotionState::Private
-                    | PromotionState::NoTrain => {
-                        continue;
-                    }
-                };
-                selected_sources.push(DecisionEvidenceSource {
-                    source_type: source_type.to_string(),
-                    id: record.id,
-                    label: excerpt(&record.content),
-                    weight,
-                    reason: format!(
-                        "{} user record selected for live twin context",
-                        promotion_state_label(&record.promotion_state)
-                    ),
-                });
-            }
-        }
-
-        for id in cited_constitution_item_ids {
-            let label = self
-                .read_constitution_file(&self.constitution_file_path(id))
-                .ok()
-                .map(|item| excerpt(&item.claim))
-                .unwrap_or_else(|| format!("Constitution {}", id));
-            selected_sources.push(DecisionEvidenceSource {
-                source_type: "constitution_item".to_string(),
-                id: id.clone(),
-                label,
-                weight: weights.constitution_weight,
-                reason: "Higher-order constitution item selected for decision framing".to_string(),
-            });
-        }
-
-        for id in cited_action_gap_ids {
-            let label = self
-                .read_action_gap_file(&self.action_gap_file_path(id))
-                .ok()
-                .map(|gap| excerpt(&gap.decision_risk))
-                .unwrap_or_else(|| format!("Action Gap {}", id));
-            selected_sources.push(DecisionEvidenceSource {
-                source_type: "action_gap".to_string(),
-                id: id.clone(),
-                label,
-                weight: weights.action_gaps_weight,
-                reason: "Action gap selected as decision risk context".to_string(),
-            });
-        }
-
-        let mut excluded_private_count = self
-            .record_cache
-            .values()
-            .filter(|record| record.promotion_state == PromotionState::Private)
-            .count();
-        let mut excluded_rejected_count = self
-            .record_cache
-            .values()
-            .filter(|record| record.promotion_state == PromotionState::Rejected)
-            .count();
-        let mut excluded_no_train_count = self
-            .record_cache
-            .values()
-            .filter(|record| record.promotion_state == PromotionState::NoTrain)
-            .count();
-
-        for item in self.list_constitution_items()? {
-            match item.status {
-                ConstitutionStatus::Private => excluded_private_count += 1,
-                ConstitutionStatus::Rejected | ConstitutionStatus::NotMe => {
-                    excluded_rejected_count += 1
-                }
-                ConstitutionStatus::NoTrain => excluded_no_train_count += 1,
-                ConstitutionStatus::Candidate
-                | ConstitutionStatus::Active
-                | ConstitutionStatus::Softened => {}
-            }
-        }
-        for gap in self.list_action_gaps()? {
-            match gap.status {
-                ConstitutionStatus::Private => excluded_private_count += 1,
-                ConstitutionStatus::Rejected | ConstitutionStatus::NotMe => {
-                    excluded_rejected_count += 1
-                }
-                ConstitutionStatus::NoTrain => excluded_no_train_count += 1,
-                ConstitutionStatus::Candidate
-                | ConstitutionStatus::Active
-                | ConstitutionStatus::Softened => {}
-            }
-        }
-
-        Ok(DecisionEvidencePacket {
-            selected_sources,
-            excluded_private_count,
-            excluded_rejected_count,
-            excluded_no_train_count,
-            created_at: Some(Utc::now()),
-            config_snapshot: Some(config.clone()),
-        })
-    }
-
-    pub fn list_memory_digest(&mut self) -> Result<Vec<MemoryDigestItem>> {
-        self.ensure_record_cache()?;
-        let mut existing = self.read_memory_digest_file()?;
-        let mut existing_by_id = existing
-            .iter()
-            .cloned()
-            .map(|item| (item.id.clone(), item))
-            .collect::<HashMap<_, _>>();
-        let now = Utc::now();
-        let records = self
-            .record_cache
-            .values()
-            .filter(|record| memory_digest_trigger(record).is_some())
-            .cloned()
-            .collect::<Vec<_>>();
-        let mut clusters: HashMap<String, Vec<UserRecord>> = HashMap::new();
-
-        for record in records {
-            clusters
-                .entry(memory_digest_cluster_key(&record))
-                .or_default()
-                .push(record);
-        }
-
-        for mut records in clusters.into_values() {
-            records.sort_by(|a, b| {
-                b.evidence_refs
-                    .len()
-                    .cmp(&a.evidence_refs.len())
-                    .then_with(|| {
-                        b.confidence
-                            .partial_cmp(&a.confidence)
-                            .unwrap_or(std::cmp::Ordering::Equal)
-                    })
-                    .then_with(|| b.updated_at.cmp(&a.updated_at))
-            });
-            let primary = match records.first() {
-                Some(record) => record,
-                None => continue,
-            };
-            let item_id = stable_digest_id(&records);
-            if existing_by_id.contains_key(&item_id) {
-                continue;
-            }
-
-            let record_ids = records
-                .iter()
-                .map(|record| record.id.clone())
-                .collect::<Vec<_>>();
-            let evidence_count = records
-                .iter()
-                .map(|record| record.evidence_refs.len())
-                .sum::<usize>();
-            let confidence = records
-                .iter()
-                .map(|record| record.confidence)
-                .fold(0.0_f32, f32::max);
-            let trigger_reason = if records.len() > 1 {
-                format!("{} related patterns clustered for review", records.len())
-            } else {
-                memory_digest_trigger(primary)
-                    .unwrap_or("pattern needs review")
-                    .to_string()
-            };
-            let latest_evidence = self
-                .resolve_evidence_refs(&primary.evidence_refs)
-                .ok()
-                .and_then(|mut refs| refs.drain(..).next());
-            let item = MemoryDigestItem {
-                id: item_id.clone(),
-                pattern: primary.content.clone(),
-                evidence_count,
-                confidence,
-                trigger_reason,
-                latest_evidence,
-                record_ids,
-                state: MemoryDigestState::Pending,
-                created_at: now,
-                updated_at: now,
-            };
-            existing_by_id.insert(item_id, item);
-        }
-
-        existing = existing_by_id.into_values().collect();
-        existing.sort_by(|a, b| {
-            digest_state_sort_key(&a.state)
-                .cmp(&digest_state_sort_key(&b.state))
-                .then_with(|| b.evidence_count.cmp(&a.evidence_count))
-                .then_with(|| {
-                    b.confidence
-                        .partial_cmp(&a.confidence)
-                        .unwrap_or(std::cmp::Ordering::Equal)
-                })
-                .then_with(|| b.updated_at.cmp(&a.updated_at))
-        });
-        self.write_memory_digest_file(&existing)?;
-
-        Ok(existing
-            .into_iter()
-            .filter(|item| item.state == MemoryDigestState::Pending)
-            .take(MAX_MEMORY_DIGEST_ITEMS)
-            .collect())
-    }
-
-    pub fn review_memory_digest_item(
-        &mut self,
-        id: &str,
-        request: MemoryDigestReviewRequest,
-    ) -> Result<MemoryDigestItem> {
-        Self::validate_file_id(id)?;
-        let mut items = self.read_memory_digest_file()?;
-        if !items.iter().any(|item| item.id == id) {
-            let _ = self.list_memory_digest()?;
-            items = self.read_memory_digest_file()?;
-        }
-
-        let item_index = items
-            .iter()
-            .position(|item| item.id == id)
-            .ok_or_else(|| anyhow::anyhow!("Memory digest item not found: {}", id))?;
-        let mut item = items[item_index].clone();
-        item.state = memory_digest_state_for_action(&request.action);
-        item.updated_at = Utc::now();
-        items[item_index] = item.clone();
-        self.write_memory_digest_file(&items)?;
-
-        for record_id in &item.record_ids {
-            if self.get_user_record(record_id).is_err() {
-                continue;
-            }
-
-            let promotion_state = match request.action {
-                MemoryDigestAction::Keep => Some(PromotionState::Endorsed),
-                MemoryDigestAction::Soften => Some(PromotionState::Candidate),
-                MemoryDigestAction::NotMe | MemoryDigestAction::Reject => {
-                    Some(PromotionState::Rejected)
-                }
-                MemoryDigestAction::Private => Some(PromotionState::Private),
-                MemoryDigestAction::NoTrain => Some(PromotionState::NoTrain),
-            };
-
-            if let Some(state) = promotion_state {
-                let _ = self.set_user_record_promotion(
-                    record_id,
-                    state,
-                    request
-                        .rationale
-                        .clone()
-                        .or_else(|| Some(format!("Memory digest action: {:?}", request.action))),
-                );
-            }
-
-            if request.action == MemoryDigestAction::Soften {
-                if let Ok(record) = self.get_user_record(record_id) {
-                    let _ = self.update_user_record(
-                        record_id,
-                        UserRecordUpdate {
-                            confidence: Some((record.confidence * 0.85).max(0.35)),
-                            ..UserRecordUpdate::default()
-                        },
-                    );
-                }
-            }
-        }
-
-        Ok(item)
-    }
-
-    pub fn list_decision_episodes_with_reflections(
-        &self,
-    ) -> Result<Vec<DecisionEpisodeWithReflections>> {
-        let cards = self.list_reflection_cards()?;
-        let mut cards_by_episode: HashMap<String, Vec<ReflectionCard>> = HashMap::new();
-        for card in cards {
-            cards_by_episode
-                .entry(card.decision_episode_id.clone())
-                .or_default()
-                .push(card);
-        }
-
-        let mut episodes = self
-            .list_decision_episodes()?
-            .into_iter()
-            .map(|mut episode| {
-                let mut reflection_cards = cards_by_episode.remove(&episode.id).unwrap_or_default();
-                reflection_cards.sort_by(|a, b| b.created_at.cmp(&a.created_at));
-                let feedback_events = self.decision_feedback_events(&episode).unwrap_or_default();
-                // A sealed prediction must never cross IPC before the outcome
-                // is recorded; the UI only learns that one exists.
-                let prediction_sealed =
-                    episode.twin_prediction.is_some() && episode.chosen_option.is_none();
-                if prediction_sealed {
-                    episode.twin_prediction = None;
-                }
-                DecisionEpisodeWithReflections {
-                    episode,
-                    reflection_cards,
-                    feedback_events,
-                    prediction_sealed,
-                }
-            })
-            .collect::<Vec<_>>();
-        episodes.sort_by(|a, b| b.episode.updated_at.cmp(&a.episode.updated_at));
-        Ok(episodes)
-    }
-
-    pub fn list_constitution_items(&self) -> Result<Vec<ConstitutionItem>> {
-        let mut items = Vec::new();
-        if !self.constitution_path.exists() {
-            return Ok(items);
-        }
-
-        for entry in WalkDir::new(&self.constitution_path)
-            .min_depth(1)
-            .max_depth(1)
-            .into_iter()
-            .filter_map(|entry| entry.ok())
-        {
-            let path = entry.path();
-            if path.extension().is_some_and(|ext| ext == "json") {
-                if let Some(item) =
-                    load_or_quarantine::<ConstitutionItem>(path, "constitution item")
-                {
-                    items.push(item);
-                }
-            }
-        }
-
-        items.sort_by(|a, b| {
-            constitution_status_sort_key(&a.status)
-                .cmp(&constitution_status_sort_key(&b.status))
-                .then_with(|| {
-                    b.priority
-                        .partial_cmp(&a.priority)
-                        .unwrap_or(std::cmp::Ordering::Equal)
-                })
-                .then_with(|| b.updated_at.cmp(&a.updated_at))
-        });
-        Ok(items)
+fn constitution_item_relevance(item: &ConstitutionItem, query_terms: &HashSet<String>) -> usize {
+    if query_terms.is_empty() {
+        return 0;
     }
-
-    pub fn create_constitution_item(
-        &self,
-        create: ConstitutionItemCreate,
-    ) -> Result<ConstitutionItem> {
-        let now = Utc::now();
-        let item = ConstitutionItem {
-            id: uuid::Uuid::new_v4().to_string(),
-            claim: create.claim,
-            dimension: create.dimension,
-            scope: create.scope,
-            priority: create.priority.clamp(0.0, 1.0),
-            confidence: create.confidence.clamp(0.0, 1.0),
-            status: create.status,
-            evidence_refs: create.evidence_refs,
-            tensions: create.tensions,
-            linked_record_ids: create.linked_record_ids,
-            source: create.source,
-            created_at: now,
-            updated_at: now,
-        };
-        self.write_constitution_file(&item)?;
-        Ok(item)
+    let mut haystack = format!("{} {} {}", item.claim, item.dimension, item.scope.join(" "));
+    for tension in &item.tensions {
+        haystack.push(' ');
+        haystack.push_str(tension);
     }
+    let item_terms = lexical_terms(&haystack);
+    query_terms.intersection(&item_terms).count()
+}
 
-    pub fn update_constitution_item(
-        &self,
-        id: &str,
-        update: ConstitutionItemUpdate,
-    ) -> Result<ConstitutionItem> {
-        Self::validate_file_id(id)?;
-        let path = self.constitution_file_path(id);
-        let mut item = self.read_constitution_file(&path)?;
-        if let Some(claim) = update.claim {
-            item.claim = claim;
-        }
-        if let Some(dimension) = update.dimension {
-            item.dimension = dimension;
-        }
-        if let Some(scope) = update.scope {
-            item.scope = scope;
-        }
-        if let Some(priority) = update.priority {
-            item.priority = priority.clamp(0.0, 1.0);
-        }
-        if let Some(confidence) = update.confidence {
-            item.confidence = confidence.clamp(0.0, 1.0);
-        }
-        if let Some(status) = update.status {
-            item.status = status;
-        }
-        if let Some(tensions) = update.tensions {
-            item.tensions = tensions;
-        }
-        item.updated_at = Utc::now();
-        self.write_constitution_file(&item)?;
-        Ok(item)
+fn action_gap_relevance(gap: &ActionGap, query_terms: &HashSet<String>) -> usize {
+    if query_terms.is_empty() {
+        return 0;
     }
-
-    pub fn review_constitution_item(
-        &mut self,
-        id: &str,
-        request: ConstitutionReviewRequest,
-    ) -> Result<ConstitutionItem> {
-        Self::validate_file_id(id)?;
-        let mut item = self.read_constitution_file(&self.constitution_file_path(id))?;
-        item.status = constitution_status_for_action(&request.action);
-        item.updated_at = Utc::now();
-        self.write_constitution_file(&item)?;
-        self.append_trace_event(
-            "constitution-review",
-            TraceEventType::ConstitutionItemReviewed,
-            json!({
-                "constitution_item_id": item.id,
-                "action": request.action,
-                "rationale": request.rationale,
-            }),
-        )?;
-        Ok(item)
+    let mut haystack = format!(
+        "{} {} {}",
+        gap.stated_value, gap.revealed_behavior, gap.decision_risk
+    );
+    if let Some(driver) = &gap.driver_hypothesis {
+        haystack.push(' ');
+        haystack.push_str(driver);
     }
-
-    pub fn list_action_gaps(&self) -> Result<Vec<ActionGap>> {
-        let mut gaps = Vec::new();
-        if !self.action_gaps_path.exists() {
-            return Ok(gaps);
-        }
-
-        for entry in WalkDir::new(&self.action_gaps_path)
-            .min_depth(1)
-            .max_depth(1)
-            .into_iter()
-            .filter_map(|entry| entry.ok())
-        {
-            let path = entry.path();
-            if path.extension().is_some_and(|ext| ext == "json") {
-                if let Some(gap) = load_or_quarantine::<ActionGap>(path, "action gap") {
-                    gaps.push(gap);
-                }
-            }
-        }
-
-        gaps.sort_by(|a, b| {
-            constitution_status_sort_key(&a.status)
-                .cmp(&constitution_status_sort_key(&b.status))
-                .then_with(|| {
-                    b.confidence
-                        .partial_cmp(&a.confidence)
-                        .unwrap_or(std::cmp::Ordering::Equal)
-                })
-                .then_with(|| b.updated_at.cmp(&a.updated_at))
-        });
-        Ok(gaps)
+    if let Some(signal) = &gap.somatic_taste_signal {
+        haystack.push(' ');
+        haystack.push_str(signal);
     }
+    let gap_terms = lexical_terms(&haystack);
+    query_terms.intersection(&gap_terms).count()
+}
 
-    pub fn create_action_gap(&self, create: ActionGapCreate) -> Result<ActionGap> {
-        let now = Utc::now();
-        let gap = ActionGap {
-            id: uuid::Uuid::new_v4().to_string(),
-            stated_value: create.stated_value,
-            revealed_behavior: create.revealed_behavior,
-            driver_hypothesis: create.driver_hypothesis,
-            somatic_taste_signal: create.somatic_taste_signal,
-            decision_risk: create.decision_risk,
-            evidence_refs: create.evidence_refs,
-            linked_record_ids: create.linked_record_ids,
-            confidence: create.confidence.clamp(0.0, 1.0),
-            status: create.status,
-            created_at: now,
-            updated_at: now,
-        };
-        self.write_action_gap_file(&gap)?;
-        Ok(gap)
+fn clamp_decision_mirror_weights(mut weights: DecisionMirrorWeights) -> DecisionMirrorWeights {
+    weights.notes_weight = clamp_weight(weights.notes_weight);
+    weights.approved_records_weight = clamp_weight(weights.approved_records_weight);
+    weights.candidate_records_weight = clamp_weight(weights.candidate_records_weight);
+    weights.constitution_weight = clamp_weight(weights.constitution_weight);
+    weights.action_gaps_weight = clamp_weight(weights.action_gaps_weight);
+    weights.recency_weight = clamp_weight(weights.recency_weight);
+    weights.evidence_count_weight = clamp_weight(weights.evidence_count_weight);
+    weights.outcome_history_weight = clamp_weight(weights.outcome_history_weight);
+    weights.contradiction_weight = clamp_weight(weights.contradiction_weight);
+    weights.breadth_weight = clamp_weight(weights.breadth_weight);
+    weights.depth_weight = clamp_weight(weights.depth_weight);
+    weights.evidence_grounding_weight = clamp_weight(weights.evidence_grounding_weight);
+    weights.blind_spot_weight = clamp_weight(weights.blind_spot_weight);
+    weights.counter_position_weight = clamp_weight(weights.counter_position_weight);
+    weights.actionability_weight = clamp_weight(weights.actionability_weight);
+    weights.uncertainty_weight = clamp_weight(weights.uncertainty_weight);
+    weights.privacy_weight = clamp_weight(weights.privacy_weight);
+    weights.unsupported_penalty_weight = clamp_weight(weights.unsupported_penalty_weight);
+    weights
+}
+
+fn clamp_weight(weight: f32) -> f32 {
+    if weight.is_finite() {
+        weight.clamp(0.0, 3.0)
+    } else {
+        1.0
     }
+}
 
-    pub fn review_action_gap(
-        &mut self,
-        id: &str,
-        request: ConstitutionReviewRequest,
-    ) -> Result<ActionGap> {
-        Self::validate_file_id(id)?;
-        let mut gap = self.read_action_gap_file(&self.action_gap_file_path(id))?;
-        gap.status = constitution_status_for_action(&request.action);
-        gap.updated_at = Utc::now();
-        self.write_action_gap_file(&gap)?;
-        self.append_trace_event(
-            "constitution-review",
-            TraceEventType::ActionGapReviewed,
-            json!({
-                "action_gap_id": gap.id,
-                "action": request.action,
-                "rationale": request.rationale,
-            }),
-        )?;
-        Ok(gap)
+fn promotion_state_label(state: &PromotionState) -> &'static str {
+    match state {
+        PromotionState::Candidate => "Candidate",
+        PromotionState::AutoPromoted => "Auto-promoted",
+        PromotionState::Endorsed => "Endorsed",
+        PromotionState::Rejected => "Rejected",
+        PromotionState::Private => "Private",
+        PromotionState::NoTrain => "No-train",
     }
+}
 
-    pub fn get_constitution_setup(&self) -> Result<ConstitutionSetup> {
-        if !self.setup_path.exists() {
-            return Ok(ConstitutionSetup::default());
-        }
+fn score_reflection_card(
+    content: &str,
+    cited_note_ids: &[String],
+    cited_user_record_ids: &[String],
+    cited_constitution_item_ids: &[String],
+    cited_action_gap_ids: &[String],
+    config: &DecisionMirrorConfig,
+) -> ReflectionScores {
+    let lower = content.to_lowercase();
+    let section_checks: &[&[&str]] = &[
+        &["decision frame", "actual decision"],
+        &["reasoning pattern", "likely reasoning", "default pattern"],
+        &["evidence", "vault", "record"],
+        &["blind spot", "missing", "underweighting"],
+        &["counter-position", "counter position", "counterargument"],
+        &["recommendation", "would do next"],
+        &["confidence", "uncertain", "would change my mind"],
+        &["next action", "smallest", "follow-up"],
+    ];
+    let present_sections = section_checks
+        .iter()
+        .filter(|aliases| aliases.iter().any(|alias| lower.contains(alias)))
+        .count();
+    let breadth_score = present_sections as f32 / section_checks.len() as f32;
 
-        let content = std::fs::read_to_string(&self.setup_path).with_context(|| {
-            format!(
-                "Failed to read constitution setup file: {}",
-                self.setup_path.display()
-            )
-        })?;
-        serde_json::from_str(&content).with_context(|| {
-            format!(
-                "Failed to parse constitution setup file: {}",
-                self.setup_path.display()
-            )
-        })
-    }
+    let word_count = content.split_whitespace().count() as f32;
+    let depth_score = ((word_count / 450.0).min(1.0) * 0.5)
+        + (phrase_score(
+            &lower,
+            &[
+                "because",
+                "tradeoff",
+                "evidence",
+                "alternative",
+                "would change",
+                "unsupported",
+            ],
+        ) * 0.5);
 
-    pub fn save_constitution_setup(
-        &mut self,
-        mut setup: ConstitutionSetup,
-    ) -> Result<ConstitutionSetup> {
-        setup.twin_name = clean_optional_setup_entry(setup.twin_name);
-        setup.twin_role = clean_optional_setup_entry(setup.twin_role);
-        setup.source_boundaries = clean_setup_entries(setup.source_boundaries);
-        setup.values = clean_setup_entries(setup.values);
-        setup.tastes = clean_setup_entries(setup.tastes);
-        setup.constraints = clean_setup_entries(setup.constraints);
-        setup.somatic_cues = clean_setup_entries(setup.somatic_cues);
-        setup.action_tendencies = clean_setup_entries(setup.action_tendencies);
-        setup.updated_at = Some(Utc::now());
-        self.write_pretty_json(&self.setup_path, &setup)?;
+    let evidence_grounding_score = if !cited_note_ids.is_empty()
+        || !cited_user_record_ids.is_empty()
+        || !cited_constitution_item_ids.is_empty()
+        || !cited_action_gap_ids.is_empty()
+    {
+        1.0
+    } else if lower.contains("evidence")
+        || lower.contains("note")
+        || lower.contains("record")
+        || lower.contains("based on")
+    {
+        0.5
+    } else {
+        0.0
+    };
 
-        let event = self.append_trace_event(
-            "constitution-setup",
-            TraceEventType::ConstitutionSetupSaved,
-            json!({
-                "twin_name": setup.twin_name,
-                "twin_role": setup.twin_role,
-                "source_boundaries": setup.source_boundaries,
-                "values": setup.values,
-                "tastes": setup.tastes,
-                "constraints": setup.constraints,
-                "somatic_cues": setup.somatic_cues,
-                "action_tendencies": setup.action_tendencies,
-            }),
-        )?;
-        let evidence_ref = EvidenceRef {
-            trace_id: "constitution-setup".to_string(),
-            event_id: event.id,
-            session_id: "constitution-setup".to_string(),
-            tile_id: None,
-            model_id: None,
-            note: Some("Guided Twin setup".to_string()),
-            source_type: Some("setup".to_string()),
-            source_id: Some("constitution-setup".to_string()),
-            source_label: Some("Guided Twin setup".to_string()),
-            excerpt: None,
-            speaker_role: None,
-        };
+    let blind_spot_score = phrase_score(
+        &lower,
+        &[
+            "blind spot",
+            "missing",
+            "underweight",
+            "bias",
+            "avoid",
+            "overfit",
+        ],
+    );
+    let actionability_score = phrase_score(
+        &lower,
+        &["next action", "smallest", "experiment", "step", "by "],
+    );
+    let counterargument_score = phrase_score(
+        &lower,
+        &[
+            "counter",
+            "strongest argument",
+            "against",
+            "alternative frame",
+        ],
+    );
+    let uncertainty_score = phrase_score(
+        &lower,
+        &[
+            "hypothesis",
+            "may",
+            "seem",
+            "confidence",
+            "uncertain",
+            "would change",
+        ],
+    );
+    let privacy_score = 1.0;
+    let unsupported_claim_count = unsupported_self_claim_count(
+        &lower,
+        evidence_grounding_score,
+        cited_note_ids,
+        cited_user_record_ids,
+        cited_constitution_item_ids,
+        cited_action_gap_ids,
+    );
+    let (overall_score, weighted_breakdown) = weighted_reflection_score(
+        config,
+        &[
+            ("breadth", breadth_score),
+            ("depth", depth_score.min(1.0)),
+            ("evidence_grounding", evidence_grounding_score),
+            ("blind_spot", blind_spot_score),
+            ("counter_position", counterargument_score),
+            ("actionability", actionability_score),
+            ("uncertainty", uncertainty_score),
+            ("privacy", privacy_score),
+        ],
+        unsupported_claim_count,
+    );
 
-        self.seed_constitution_setup_items(&setup, evidence_ref)?;
-        Ok(setup)
+    ReflectionScores {
+        breadth_score,
+        depth_score: depth_score.min(1.0),
+        evidence_grounding_score,
+        blind_spot_score,
+        actionability_score,
+        counterargument_score,
+        uncertainty_score,
+        privacy_score,
+        unsupported_claim_count,
+        overall_score,
+        weighted_breakdown,
+    }
+}
+
+fn weighted_reflection_score(
+    config: &DecisionMirrorConfig,
+    scores: &[(&str, f32)],
+    unsupported_claim_count: u32,
+) -> (f32, HashMap<String, f32>) {
+    let weights = &config.weights;
+    let weight_for = |key: &str| match key {
+        "breadth" => weights.breadth_weight,
+        "depth" => weights.depth_weight,
+        "evidence_grounding" => weights.evidence_grounding_weight,
+        "blind_spot" => weights.blind_spot_weight,
+        "counter_position" => weights.counter_position_weight,
+        "actionability" => weights.actionability_weight,
+        "uncertainty" => weights.uncertainty_weight,
+        "privacy" => weights.privacy_weight,
+        _ => 1.0,
+    };
+
+    let mut weighted_breakdown = HashMap::new();
+    let mut weighted_sum = 0.0_f32;
+    let mut weight_sum = 0.0_f32;
+    for (key, score) in scores {
+        let weight = clamp_weight(weight_for(key));
+        let contribution = score.clamp(0.0, 1.0) * weight;
+        weighted_breakdown.insert((*key).to_string(), contribution);
+        weighted_sum += contribution;
+        weight_sum += weight;
     }
 
-    pub fn run_constitution_inference(&mut self) -> Result<ConstitutionInferenceSummary> {
-        self.run_constitution_inference_with_notes(&[])
+    let unsupported_penalty =
+        (unsupported_claim_count.min(5) as f32 / 5.0) * weights.unsupported_penalty_weight;
+    weighted_breakdown.insert("unsupported_penalty".to_string(), -unsupported_penalty);
+
+    if weight_sum <= 0.0 {
+        return (0.0, weighted_breakdown);
     }
 
-    pub fn run_constitution_inference_with_notes(
-        &mut self,
-        notes: &[Note],
-    ) -> Result<ConstitutionInferenceSummary> {
-        self.ensure_record_cache()?;
-        let current_note_ids = notes
-            .iter()
-            .map(|note| note.id.clone())
-            .collect::<HashSet<_>>();
-        let pruned_stale_records = self.prune_stale_note_records(&current_note_ids)?;
-        let distilled_setup = distill_constitution_setup_from_notes(notes);
-        let updated_setup_entries = constitution_setup_entry_count(&distilled_setup);
-        let pruned_stale_constitution_items = self
-            .prune_stale_note_constitution_items(&current_note_ids)?
-            + self.prune_stale_setup_constitution_items(&distilled_setup)?;
-        if updated_setup_entries > 0 || self.setup_path.exists() {
-            self.write_auto_constitution_setup(distilled_setup.clone())?;
-        }
-        self.ensure_record_cache()?;
-        let records = self
-            .record_cache
-            .values()
-            .filter(|record| constitution_allows_record(record))
-            .cloned()
-            .collect::<Vec<_>>();
-        let traces = self.list_session_traces()?;
-        let scanned_behavior_events = traces
-            .iter()
-            .flat_map(|trace| trace.events.iter())
-            .filter(|event| behavior_event_for_constitution(&event.event_type))
-            .count();
-        let decisions = self.list_decision_episodes()?;
-        let existing_items = self.list_constitution_items()?;
-        let existing_gaps = self.list_action_gaps()?;
-        let mut item_keys = existing_items
-            .iter()
-            .map(|item| constitution_key(&item.dimension, &item.claim))
-            .collect::<HashSet<_>>();
-        let mut gap_keys = existing_gaps
-            .iter()
-            .map(|gap| action_gap_key(&gap.stated_value, &gap.revealed_behavior))
-            .collect::<HashSet<_>>();
+    let overall = ((weighted_sum - unsupported_penalty) / weight_sum).clamp(0.0, 1.0);
+    (overall, weighted_breakdown)
+}
 
-        let mut created_constitution_items = 0_usize;
-        let mut created_action_gaps = 0_usize;
-        let mut auto_active_items = 0_usize;
-        let mut review_candidate_items = 0_usize;
-        let mut skipped_domain_claims = 0_usize;
-        let mut extracted_research_findings = 0_usize;
+fn phrase_score(content: &str, phrases: &[&str]) -> f32 {
+    let hits = phrases
+        .iter()
+        .filter(|phrase| content.contains(**phrase))
+        .count();
+    (hits as f32 / phrases.len().max(1) as f32).min(1.0)
+}
 
-        for record in &records {
-            let dimension = infer_constitution_dimension(&record.content, &record.kind);
-            let claim = record.content.trim().to_string();
-            if claim.is_empty() {
-                continue;
-            }
-            let key = constitution_key(&dimension, &claim);
-            if item_keys.insert(key) {
-                let status = constitution_status_from_record(record);
-                if status == ConstitutionStatus::Active {
-                    auto_active_items += 1;
-                } else if status == ConstitutionStatus::Candidate {
-                    review_candidate_items += 1;
-                }
-                let source = if record.origin == RecordOrigin::Inferred {
-                    "behavior_inference"
-                } else {
-                    "constitution_inference"
-                };
-                self.create_constitution_item(ConstitutionItemCreate {
-                    claim,
-                    dimension,
-                    scope: vec!["general".to_string()],
-                    priority: record.confidence,
-                    confidence: record.confidence,
-                    status,
-                    evidence_refs: record.evidence_refs.clone(),
-                    tensions: Vec::new(),
-                    linked_record_ids: vec![record.id.clone()],
-                    source: Some(source.to_string()),
-                })?;
-                created_constitution_items += 1;
-            }
+fn unsupported_self_claim_count(
+    lower: &str,
+    evidence_grounding_score: f32,
+    cited_note_ids: &[String],
+    cited_user_record_ids: &[String],
+    cited_constitution_item_ids: &[String],
+    cited_action_gap_ids: &[String],
+) -> u32 {
+    let has_structural_evidence = !cited_note_ids.is_empty()
+        || !cited_user_record_ids.is_empty()
+        || !cited_constitution_item_ids.is_empty()
+        || !cited_action_gap_ids.is_empty()
+        || evidence_grounding_score >= 0.5;
+    if has_structural_evidence {
+        return 0;
+    }
 
-            if let Some((stated_value, revealed_behavior)) = split_action_gap_claim(&record.content)
-            {
-                let key = action_gap_key(&stated_value, &revealed_behavior);
-                if gap_keys.insert(key) {
-                    self.create_action_gap(ActionGapCreate {
-                        stated_value,
-                        revealed_behavior,
-                        driver_hypothesis: Some(
-                            "Inferred from a contradiction-style user record".to_string(),
-                        ),
-                        somatic_taste_signal: None,
-                        decision_risk:
-                            "The user's endorsed intent may diverge from what they repeatedly do."
-                                .to_string(),
-                        evidence_refs: record.evidence_refs.clone(),
-                        linked_record_ids: vec![record.id.clone()],
-                        confidence: record.confidence,
-                        status: ConstitutionStatus::Candidate,
-                    })?;
-                    created_action_gaps += 1;
-                }
-            }
-        }
+    [
+        "you seem",
+        "you may",
+        "you often",
+        "you tend",
+        "your likely",
+        "based on your",
+        "you prefer",
+        "you avoid",
+    ]
+    .iter()
+    .map(|needle| lower.matches(needle).count() as u32)
+    .sum()
+}
 
-        for decision in &decisions {
-            let Some(initial_leaning) = decision.initial_leaning.as_ref() else {
-                continue;
-            };
-            let Some(chosen_option) = decision.chosen_option.as_ref() else {
-                continue;
-            };
-            if initial_leaning
-                .trim()
-                .eq_ignore_ascii_case(chosen_option.trim())
-            {
-                continue;
-            }
-            let stated_value = format!("Initial leaning: {}", initial_leaning.trim());
-            let revealed_behavior = format!("Chosen option: {}", chosen_option.trim());
-            let key = action_gap_key(&stated_value, &revealed_behavior);
-            if gap_keys.insert(key) {
-                self.create_action_gap(ActionGapCreate {
-                    stated_value,
-                    revealed_behavior,
-                    driver_hypothesis: Some("Inferred from a decision where final action diverged from initial leaning.".to_string()),
-                    somatic_taste_signal: decision.primitive_assessment.somatic_signal.clone(),
-                    decision_risk: "Grafyn should check whether future similar decisions repeat this gap.".to_string(),
-                    evidence_refs: self.decision_evidence_refs(&decision.id)?,
-                    linked_record_ids: Vec::new(),
-                    confidence: 0.68,
-                    status: ConstitutionStatus::Candidate,
-                })?;
-                created_action_gaps += 1;
-            }
-        }
+const PREDICTION_OPTION_MAX_CHARS: usize = 500;
 
-        for note in notes {
-            if note_is_interview(note) {
-                match extract_interview_note_evidence(note) {
-                    InterviewExtraction::Unlabeled => {
-                        skipped_domain_claims += 1;
-                    }
-                    InterviewExtraction::Labeled {
-                        interviewer_turns,
-                        interviewee_turns,
-                    } => {
-                        for turn in interviewer_turns {
-                            if let Some((dimension, claim)) =
-                                constitution_claim_from_interviewer_turn(&turn.content)
-                            {
-                                let key = constitution_key(&dimension, &claim);
-                                if item_keys.insert(key) {
-                                    self.create_constitution_item(ConstitutionItemCreate {
-                                        claim,
-                                        dimension,
-                                        scope: vec!["interview".to_string()],
-                                        priority: 0.62,
-                                        confidence: 0.62,
-                                        status: ConstitutionStatus::Candidate,
-                                        evidence_refs: vec![note_evidence_ref(
-                                            note,
-                                            "interview-question",
-                                            "Interviewer question",
-                                            Some("user"),
-                                            &turn.content,
-                                        )],
-                                        tensions: Vec::new(),
-                                        linked_record_ids: Vec::new(),
-                                        source: Some("interview_behavior_inference".to_string()),
-                                    })?;
-                                    created_constitution_items += 1;
-                                    review_candidate_items += 1;
-                                }
-                            }
-                        }
-                        for turn in interviewee_turns {
-                            if !looks_like_research_finding(&turn.content) {
-                                skipped_domain_claims += 1;
-                                continue;
-                            }
-                            if self.create_interview_research_record(note, &turn.content)? {
-                                extracted_research_findings += 1;
-                            }
-                        }
-                    }
-                }
-                continue;
-            }
+const PREDICTION_RATIONALE_MAX_CHARS: usize = 2000;
+
+/// Normalize an option string for comparison: trim, strip wrapping quotes,
+/// lowercase, collapse whitespace. Label forms ("Option 2", "B") are handled
+/// separately by `match_option_index` so meaningful digits survive.
+pub fn normalize_option(text: &str) -> String {
+    text.trim()
+        .trim_matches(|c: char| c == '"' || c == '\'' || c == '`')
+        .to_lowercase()
+        .split_whitespace()
+        .collect::<Vec<_>>()
+        .join(" ")
+}
+
+fn truncate_chars(text: &str, max_chars: usize) -> String {
+    if text.chars().count() <= max_chars {
+        text.to_string()
+    } else {
+        text.chars().take(max_chars).collect()
+    }
+}
 
-            if let Some((dimension, claim)) = constitution_claim_from_note(note) {
-                let key = constitution_key(&dimension, &claim);
-                if item_keys.insert(key) {
-                    self.create_constitution_item(ConstitutionItemCreate {
-                        claim,
-                        dimension,
-                        scope: vec!["note".to_string()],
-                        priority: 0.58,
-                        confidence: 0.58,
-                        status: ConstitutionStatus::Candidate,
-                        evidence_refs: vec![note_evidence_ref(
-                            note,
-                            "note",
-                            "Vault note",
-                            Some("user"),
-                            &note.content,
-                        )],
-                        tensions: Vec::new(),
-                        linked_record_ids: Vec::new(),
-                        source: Some("note_inference".to_string()),
-                    })?;
-                    created_constitution_items += 1;
-                    review_candidate_items += 1;
+fn match_option_index(text: &str, options: &[String]) -> Option<usize> {
+    let normalized = normalize_option(text);
+    if normalized.is_empty() {
+        return None;
+    }
+
+    // Label forms: "option 2" / "choice b" / bare "2" / bare "b".
+    let label = ["option", "choice"]
+        .iter()
+        .find_map(|prefix| normalized.strip_prefix(prefix))
+        .map(str::trim)
+        .unwrap_or(&normalized)
+        .trim_matches(|c: char| c == '.' || c == ')' || c == ':' || c.is_whitespace());
+    if label.len() == 1 {
+        if let Some(letter) = label.chars().next() {
+            if letter.is_ascii_lowercase() {
+                let index = (letter as usize) - ('a' as usize);
+                if index < options.len() {
+                    return Some(index);
                 }
-            } else {
-                skipped_domain_claims += 1;
             }
         }
-
-        let summary = ConstitutionInferenceSummary {
-            scanned_records: records.len(),
-            scanned_decisions: decisions.len(),
-            created_constitution_items,
-            created_action_gaps,
-            scanned_behavior_events,
-            scanned_notes: notes.len(),
-            scanned_interviews: notes.iter().filter(|note| note_is_interview(note)).count(),
-            auto_active_items,
-            review_candidate_items,
-            skipped_domain_claims,
-            extracted_research_findings,
-            pruned_stale_constitution_items,
-            pruned_stale_records,
-            updated_setup_entries,
-            generated_at: Utc::now(),
-        };
-        self.append_trace_event(
-            "constitution-inference",
-            TraceEventType::ConstitutionInferenceRun,
-            serde_json::to_value(&summary)?,
-        )?;
-        Ok(summary)
     }
-
-    fn create_interview_research_record(&mut self, note: &Note, content: &str) -> Result<bool> {
-        self.ensure_record_cache()?;
-        let finding = format!("Interview finding: {}", excerpt(content.trim()));
-        let existing = self.record_cache.values().any(|record| {
-            record.kind == UserRecordKind::Fact
-                && record.content == finding
-                && record.metadata.get("source_type").and_then(Value::as_str)
-                    == Some("interview_answer")
-        });
-        if existing {
-            return Ok(false);
+    // Bare number labels: humans count from 1.
+    if let Ok(number) = label.parse::<usize>() {
+        if (1..=options.len()).contains(&number) {
+            return Some(number - 1);
         }
+    }
 
-        self.create_user_record(UserRecordCreate {
-            kind: UserRecordKind::Fact,
-            content: finding,
-            evidence_refs: vec![note_evidence_ref(
-                note,
-                "interview-answer",
-                "Interviewee answer",
-                Some("interviewee"),
-                content,
-            )],
-            confidence: 0.66,
-            origin: RecordOrigin::Inferred,
-            promotion_state: Some(PromotionState::Candidate),
-            valid_from: None,
-            valid_until: None,
-            links: Vec::new(),
-            metadata: HashMap::from([
-                ("source_type".to_string(), json!("interview_answer")),
-                ("source_note_id".to_string(), json!(note.id.clone())),
-            ]),
-        })?;
-        Ok(true)
+    options
+        .iter()
+        .position(|option| normalize_option(option) == normalized)
+}
+
+fn sanitize_confidence(raw: Option<f64>) -> Option<f32> {
+    let value = raw?;
+    if !value.is_finite() {
+        return None;
     }
+    let value = if value > 2.0 && value <= 100.0 {
+        // Percent-style answer ("73" meaning 73%).
+        value / 100.0
+    } else {
+        // Near-misses like 1.2 are over-confident, not percentages.
+        value
+    };
+    Some(value.clamp(0.0, 1.0) as f32)
+}
 
-    fn write_auto_constitution_setup(&self, mut setup: ConstitutionSetup) -> Result<()> {
-        if let Ok(existing) = self.get_constitution_setup() {
-            setup.twin_name = existing.twin_name;
-            setup.twin_role = existing.twin_role;
-            setup.source_boundaries = existing.source_boundaries;
-        }
-        setup.twin_name = clean_optional_setup_entry(setup.twin_name);
-        setup.twin_role = clean_optional_setup_entry(setup.twin_role);
-        setup.source_boundaries = clean_setup_entries(setup.source_boundaries);
-        setup.values = clean_setup_entries(setup.values);
-        setup.tastes = clean_setup_entries(setup.tastes);
-        setup.constraints = clean_setup_entries(setup.constraints);
-        setup.somatic_cues = clean_setup_entries(setup.somatic_cues);
-        setup.action_tendencies = clean_setup_entries(setup.action_tendencies);
-        setup.updated_at = Some(Utc::now());
-        self.write_pretty_json(&self.setup_path, &setup)
+/// Extract the first balanced `{...}` span from `raw`, for best-effort JSON parsing of
+/// model output. Returns `None` if there's no opening brace, no closing brace, or the
+/// closing brace appears before the opening one (e.g. truncated/malformed model output
+/// like `"Option A} — but {incomplete"`) — guarding this instead of blindly slicing
+/// `&raw[start..=end]` is what prevents a panic on malformed input.
+fn extract_json_slice(raw: &str) -> Option<&str> {
+    let start = raw.find('{')?;
+    let end = raw.rfind('}')?;
+    if start > end {
+        return None;
     }
+    Some(&raw[start..=end])
+}
 
-    fn prune_stale_note_records(&mut self, current_note_ids: &HashSet<String>) -> Result<usize> {
-        self.ensure_record_cache()?;
-        let stale_ids = self
-            .record_cache
-            .values()
-            .filter(|record| record_is_vault_derived(record))
-            .filter(|record| {
-                record
-                    .metadata
-                    .get("source_note_id")
-                    .and_then(Value::as_str)
-                    .is_some_and(|source_note_id| !current_note_ids.contains(source_note_id))
-            })
-            .map(|record| record.id.clone())
-            .collect::<Vec<_>>();
+/// Parse the raw model output of a sealed-prediction call into a draft.
+/// Fallback chain: fenced/embedded strict JSON -> normalized string match
+/// against `options` -> raw text (manual adjudication later).
+pub fn parse_twin_prediction(raw: &str, options: &[String]) -> TwinPredictionDraft {
+    #[derive(serde::Deserialize)]
+    struct ParsedPrediction {
+        predicted_option: Option<String>,
+        option_index: Option<Value>,
+        confidence: Option<f64>,
+        rationale: Option<String>,
+    }
 
-        for id in &stale_ids {
-            self.record_cache.remove(id);
-            let path = self.records_path.join(format!("{}.json", id));
-            if path.exists() {
-                std::fs::remove_file(&path).with_context(|| {
-                    format!("Failed to remove stale Twin record: {}", path.display())
-                })?;
-            }
+    let json_slice = extract_json_slice(raw);
+
+    if let Some(slice) = json_slice {
+        if let Ok(parsed) = serde_json::from_str::<ParsedPrediction>(slice) {
+            let text = parsed.predicted_option.unwrap_or_default();
+            let text_index = match_option_index(&text, options);
+            let field_index = parsed.option_index.as_ref().and_then(|value| match value {
+                Value::Number(number) => number.as_u64().map(|n| n as usize),
+                Value::String(text) => text.trim().parse::<usize>().ok(),
+                _ => None,
+            });
+            // The prompt displays a 1-based option list, so prefer the
+            // 1-based reading; tolerate 0-based answers, and let the option
+            // text disambiguate when both readings are valid.
+            let field_index = field_index.and_then(|index| {
+                let one_based = index.checked_sub(1).filter(|i| *i < options.len());
+                let zero_based = Some(index).filter(|i| *i < options.len());
+                match (one_based, zero_based) {
+                    (Some(ob), Some(zb)) => match text_index {
+                        Some(text_idx) if text_idx == zb => Some(zb),
+                        _ => Some(ob),
+                    },
+                    (Some(ob), None) => Some(ob),
+                    (None, Some(zb)) => Some(zb),
+                    (None, None) => None,
+                }
+            });
+            // The option text is what the model actually said; a conflicting
+            // numeric index loses.
+            let matched_option_index = match (text_index, field_index) {
+                (Some(text_idx), _) => Some(text_idx),
+                (None, Some(field_idx)) if text.is_empty() => Some(field_idx),
+                _ => None,
+            };
+            let predicted_option = if text.is_empty() {
+                matched_option_index
+                    .map(|index| options[index].clone())
+                    .unwrap_or_else(|| truncate_chars(raw.trim(), PREDICTION_OPTION_MAX_CHARS))
+            } else {
+                truncate_chars(&text, PREDICTION_OPTION_MAX_CHARS)
+            };
+            return TwinPredictionDraft {
+                predicted_option,
+                matched_option_index,
+                confidence: sanitize_confidence(parsed.confidence),
+                rationale: parsed
+                    .rationale
+                    .map(|text| truncate_chars(&text, PREDICTION_RATIONALE_MAX_CHARS)),
+                parse_mode: "json".to_string(),
+            };
         }
+    }
 
-        Ok(stale_ids.len())
+    if let Some(index) = match_option_index(raw, options) {
+        return TwinPredictionDraft {
+            predicted_option: options[index].clone(),
+            matched_option_index: Some(index),
+            confidence: None,
+            rationale: None,
+            parse_mode: "string_match".to_string(),
+        };
+    }
+
+    TwinPredictionDraft {
+        predicted_option: truncate_chars(raw.trim(), PREDICTION_OPTION_MAX_CHARS),
+        matched_option_index: None,
+        confidence: None,
+        rationale: None,
+        parse_mode: "raw".to_string(),
     }
+}
 
-    fn prune_stale_note_constitution_items(
-        &self,
-        current_note_ids: &HashSet<String>,
-    ) -> Result<usize> {
-        let stale_items = self
-            .list_constitution_items()?
-            .into_iter()
-            .filter(|item| constitution_item_is_vault_derived(item))
-            .filter(|item| {
-                item.evidence_refs
-                    .iter()
-                    .filter_map(|evidence| evidence.source_id.as_deref())
-                    .any(|source_id| !current_note_ids.contains(source_id))
-            })
-            .collect::<Vec<_>>();
+fn compute_agreement(prediction: &TwinPrediction, chosen: &str, options: &[String]) -> bool {
+    let chosen_index = match_option_index(chosen, options);
+    match (prediction.matched_option_index, chosen_index) {
+        (Some(predicted), Some(chosen)) => predicted == chosen,
+        _ => normalize_option(&prediction.predicted_option) == normalize_option(chosen),
+    }
+}
 
-        for item in &stale_items {
-            let path = self.constitution_path.join(format!("{}.json", item.id));
-            if path.exists() {
-                std::fs::remove_file(&path).with_context(|| {
-                    format!(
-                        "Failed to remove stale Constitution item: {}",
-                        path.display()
-                    )
-                })?;
-            }
-        }
+fn decision_case_relevance(episode: &DecisionEpisode, query_terms: &HashSet<String>) -> usize {
+    if query_terms.is_empty() {
+        return 0;
+    }
 
-        Ok(stale_items.len())
+    let mut haystack = episode.decision.clone();
+    haystack.push(' ');
+    haystack.push_str(&episode.options.join(" "));
+    for text in [
+        episode.chosen_option.as_deref(),
+        episode.initial_leaning.as_deref(),
+        episode.lesson.as_deref(),
+        episode.outcome.as_deref(),
+        episode.correction_note.as_deref(),
+    ]
+    .into_iter()
+    .flatten()
+    {
+        haystack.push(' ');
+        haystack.push_str(text);
     }
 
-    fn prune_stale_setup_constitution_items(&self, setup: &ConstitutionSetup) -> Result<usize> {
-        let setup_claims = constitution_setup_claims(setup);
-        let stale_items = self
-            .list_constitution_items()?
-            .into_iter()
-            .filter(|item| item.source.as_deref() == Some("guided_setup"))
-            .filter(|item| !setup_claims.contains(item.claim.trim()))
-            .collect::<Vec<_>>();
+    let episode_terms = lexical_terms(&haystack);
+    query_terms.intersection(&episode_terms).count()
+}
 
-        for item in &stale_items {
-            let path = self.constitution_path.join(format!("{}.json", item.id));
-            if path.exists() {
-                std::fs::remove_file(&path).with_context(|| {
-                    format!(
-                        "Failed to remove stale setup Constitution item: {}",
-                        path.display()
-                    )
-                })?;
-            }
+fn memory_digest_trigger(record: &UserRecord) -> Option<&'static str> {
+    if record.kind == UserRecordKind::Fact {
+        return None;
+    }
+
+    match record.promotion_state {
+        PromotionState::Rejected | PromotionState::Private | PromotionState::NoTrain => None,
+        PromotionState::AutoPromoted
+            if record.evidence_refs.len() >= AUTO_PROMOTE_SUPPORT_COUNT =>
+        {
+            Some("3+ evidence points support this durable pattern")
+        }
+        PromotionState::Candidate if record.evidence_refs.len() >= AUTO_PROMOTE_SUPPORT_COUNT => {
+            Some("candidate pattern has enough evidence for review")
+        }
+        PromotionState::Candidate
+            if record.confidence >= AUTO_PROMOTE_CONFIDENCE && !record.evidence_refs.is_empty() =>
+        {
+            Some("high-confidence candidate pattern needs review")
+        }
+        PromotionState::Endorsed if stale_for_review(record) => {
+            Some("endorsed pattern may be stale")
         }
+        PromotionState::AutoPromoted => None,
+        PromotionState::Endorsed => None,
+        PromotionState::Candidate => None,
+    }
+}
 
-        Ok(stale_items.len())
+fn memory_digest_cluster_key(record: &UserRecord) -> String {
+    if let Some(signal_family) = record
+        .metadata
+        .get("signal_family")
+        .and_then(Value::as_str)
+        .filter(|value| !value.trim().is_empty())
+    {
+        return format!("{:?}::{}", record.kind, signal_family.trim().to_lowercase());
     }
 
-    pub fn select_constitution_context(
-        &self,
-        query: &str,
-    ) -> Result<(Vec<ConstitutionItem>, Vec<ActionGap>)> {
-        let query_terms = lexical_terms(query);
-        let mut items = self
-            .list_constitution_items()?
-            .into_iter()
-            .filter(|item| constitution_context_allowed(&item.status))
-            .map(|item| (constitution_item_relevance(&item, &query_terms), item))
-            .filter(|(score, item)| *score > 0 || item.status == ConstitutionStatus::Active)
-            .collect::<Vec<_>>();
-        items.sort_by(|a, b| {
-            b.0.cmp(&a.0)
-                .then_with(|| {
-                    b.1.priority
-                        .partial_cmp(&a.1.priority)
-                        .unwrap_or(std::cmp::Ordering::Equal)
-                })
-                .then_with(|| b.1.updated_at.cmp(&a.1.updated_at))
-        });
+    let mut terms = lexical_terms(&record.content)
+        .into_iter()
+        .collect::<Vec<_>>();
+    terms.sort();
+    terms.truncate(6);
+    if terms.is_empty() {
+        format!("{:?}::{}", record.kind, normalize_key_text(&record.content))
+    } else {
+        format!("{:?}::{}", record.kind, terms.join("-"))
+    }
+}
 
-        let mut gaps = self
-            .list_action_gaps()?
-            .into_iter()
-            .filter(|gap| constitution_context_allowed(&gap.status))
-            .map(|gap| (action_gap_relevance(&gap, &query_terms), gap))
-            .filter(|(score, gap)| *score > 0 || gap.status == ConstitutionStatus::Active)
-            .collect::<Vec<_>>();
-        gaps.sort_by(|a, b| {
-            b.0.cmp(&a.0)
-                .then_with(|| {
-                    b.1.confidence
-                        .partial_cmp(&a.1.confidence)
-                        .unwrap_or(std::cmp::Ordering::Equal)
-                })
-                .then_with(|| b.1.updated_at.cmp(&a.1.updated_at))
-        });
+fn stable_digest_id(records: &[UserRecord]) -> String {
+    let mut ids = records
+        .iter()
+        .map(|record| record.id.as_str())
+        .collect::<Vec<_>>();
+    ids.sort_unstable();
+    let mut hasher = DefaultHasher::new();
+    ids.hash(&mut hasher);
+    format!("digest-cluster-{:x}", hasher.finish())
+}
 
-        Ok((
-            items.into_iter().take(8).map(|(_, item)| item).collect(),
-            gaps.into_iter().take(4).map(|(_, gap)| gap).collect(),
-        ))
+fn stale_for_review(record: &UserRecord) -> bool {
+    Utc::now()
+        .signed_duration_since(record.updated_at)
+        .num_days()
+        >= 90
+}
+
+fn digest_state_sort_key(state: &MemoryDigestState) -> u8 {
+    match state {
+        MemoryDigestState::Pending => 0,
+        MemoryDigestState::Softened => 1,
+        MemoryDigestState::Kept => 2,
+        MemoryDigestState::NotMe => 3,
+        MemoryDigestState::Private => 4,
+        MemoryDigestState::NoTrain => 5,
+        MemoryDigestState::Rejected => 6,
     }
+}
 
-    pub fn export_bundle(&mut self, request: TwinExportRequest) -> Result<ExportBundle> {
-        self.ensure_record_cache()?;
+fn memory_digest_state_for_action(action: &MemoryDigestAction) -> MemoryDigestState {
+    match action {
+        MemoryDigestAction::Keep => MemoryDigestState::Kept,
+        MemoryDigestAction::Soften => MemoryDigestState::Softened,
+        MemoryDigestAction::NotMe => MemoryDigestState::NotMe,
+        MemoryDigestAction::Private => MemoryDigestState::Private,
+        MemoryDigestAction::NoTrain => MemoryDigestState::NoTrain,
+        MemoryDigestAction::Reject => MemoryDigestState::Rejected,
+    }
+}
 
-        let eval_percentage = request.eval_percentage.unwrap_or(DEFAULT_EVAL_PERCENTAGE);
-        let holdout_percentage = request
-            .holdout_percentage
-            .unwrap_or(DEFAULT_HOLDOUT_PERCENTAGE);
+pub struct TwinStore {
+    root_path: PathBuf,
+    traces_path: PathBuf,
+    records_path: PathBuf,
+    decisions_path: PathBuf,
+    reflections_path: PathBuf,
+    constitution_path: PathBuf,
+    action_gaps_path: PathBuf,
+    setup_path: PathBuf,
+    decision_mirror_config_path: PathBuf,
+    digest_path: PathBuf,
+    exports_path: PathBuf,
+    trace_cache: HashMap<String, SessionTrace>,
+    record_cache: HashMap<String, UserRecord>,
+    records_cache_ready: bool,
+}
 
-        if eval_percentage + holdout_percentage >= 100 {
-            anyhow::bail!("Eval and holdout percentages must total less than 100");
+impl TwinStore {
+    pub fn new(root_path: PathBuf) -> Self {
+        let traces_path = root_path.join("traces");
+        let records_path = root_path.join("records");
+        let decisions_path = root_path.join("decisions");
+        let reflections_path = root_path.join("reflections");
+        let constitution_path = root_path.join("constitution");
+        let action_gaps_path = root_path.join("action_gaps");
+        let setup_path = root_path.join("constitution_setup.json");
+        let decision_mirror_config_path = root_path.join("decision_mirror_config.json");
+        let digest_path = root_path.join("memory_digest.json");
+        let exports_path = root_path.join("exports");
+
+        std::fs::create_dir_all(&traces_path).ok();
+        std::fs::create_dir_all(&records_path).ok();
+        std::fs::create_dir_all(&decisions_path).ok();
+        std::fs::create_dir_all(&reflections_path).ok();
+        std::fs::create_dir_all(&constitution_path).ok();
+        std::fs::create_dir_all(&action_gaps_path).ok();
+        std::fs::create_dir_all(&exports_path).ok();
+
+        Self {
+            root_path,
+            traces_path,
+            records_path,
+            decisions_path,
+            reflections_path,
+            constitution_path,
+            action_gaps_path,
+            setup_path,
+            decision_mirror_config_path,
+            digest_path,
+            exports_path,
+            trace_cache: HashMap::new(),
+            record_cache: HashMap::new(),
+            records_cache_ready: false,
         }
+    }
 
-        let bundle_name = request.bundle_name.as_deref().unwrap_or("latest").trim();
-        if bundle_name.is_empty() {
-            anyhow::bail!("Bundle name cannot be empty");
+    fn write_pretty_json<T: Serialize>(&self, path: &Path, value: &T) -> Result<()> {
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent)
+                .with_context(|| format!("Failed to create directory: {}", parent.display()))?;
         }
-        Self::validate_file_id(bundle_name)?;
-
-        let output_dir = self.exports_path.join(bundle_name);
-        std::fs::create_dir_all(&output_dir).with_context(|| {
-            format!(
-                "Failed to create export directory: {}",
-                output_dir.display()
-            )
-        })?;
-
-        let approved_path = output_dir.join("approved_user_records.jsonl");
-        let candidate_path = output_dir.join("candidate_user_records.jsonl");
-        let rejected_path = output_dir.join("rejected_user_records.jsonl");
-        let train_path = output_dir.join("train.jsonl");
-        let eval_path = output_dir.join("eval.jsonl");
-        let holdout_path = output_dir.join("holdout.jsonl");
-        let benchmark_path = output_dir.join("decision_mirror_benchmark.jsonl");
-        let constitution_path = output_dir.join("constitution_items.jsonl");
-        let action_gaps_path = output_dir.join("action_gaps.jsonl");
-        let decision_episodes_path = output_dir.join("decision_episodes.jsonl");
-        let feedback_events_path = output_dir.join("feedback_events.jsonl");
-        let manifest_path = output_dir.join("manifest.json");
-
-        let mut records: Vec<UserRecord> = self.record_cache.values().cloned().collect();
-        records.sort_by(|a, b| a.id.cmp(&b.id));
-
-        let mut approved_lines = Vec::new();
-        let mut candidate_lines = Vec::new();
-        let mut rejected_lines = Vec::new();
-        let mut train_lines = Vec::new();
-        let mut eval_lines = Vec::new();
-        let mut holdout_lines = Vec::new();
-        let mut included_record_ids = Vec::new();
-        let mut private_or_no_train_record_ids = Vec::new();
 
-        for record in records {
-            let line = serde_json::to_string(&Self::record_to_export_value(&record))?;
+        let content = serde_json::to_string_pretty(value)?;
+        write_atomic(path, content.as_bytes())
+            .with_context(|| format!("Failed to write JSON file: {}", path.display()))
+    }
 
-            match record.promotion_state {
-                PromotionState::AutoPromoted | PromotionState::Endorsed => {
-                    included_record_ids.push(record.id.clone());
-                    approved_lines.push(line.clone());
-                    match Self::split_for_record(&record, eval_percentage, holdout_percentage) {
-                        ExportSplit::Train => train_lines.push(line),
-                        ExportSplit::Eval => eval_lines.push(line),
-                        ExportSplit::Holdout => holdout_lines.push(line),
-                    }
-                }
-                PromotionState::Candidate => {
-                    candidate_lines.push(line);
-                }
-                PromotionState::Rejected => {
-                    rejected_lines.push(line);
-                }
-                PromotionState::Private | PromotionState::NoTrain => {
-                    private_or_no_train_record_ids.push(record.id.clone());
-                }
-            }
+    fn validate_file_id(id: &str) -> Result<()> {
+        if id.is_empty() || id.contains('/') || id.contains('\\') || id.contains("..") {
+            anyhow::bail!("Invalid file id: {}", id);
         }
 
-        self.write_jsonl_file(&approved_path, &approved_lines)?;
-        self.write_jsonl_file(&candidate_path, &candidate_lines)?;
-        self.write_jsonl_file(&rejected_path, &rejected_lines)?;
-        self.write_jsonl_file(&train_path, &train_lines)?;
-        self.write_jsonl_file(&eval_path, &eval_lines)?;
-        self.write_jsonl_file(&holdout_path, &holdout_lines)?;
-        let decision_mirror_config = self.get_decision_mirror_config()?;
-        let benchmark_lines = self
-            .list_decision_episodes_with_reflections()?
-            .into_iter()
-            .map(|entry| {
-                serde_json::to_string(&json!({
-                    "variant": "decision_mirror",
-                    "baseline_variants": [
-                        "generic_llm",
-                        "persona_prompt",
-                        "vault_only_rag",
-                        "twin_rag",
-                        "decision_mirror"
-                    ],
-                    "config": decision_mirror_config.clone(),
-                    "episode": entry.episode,
-                    "reflection_cards": entry.reflection_cards,
-                }))
-            })
-            .collect::<std::result::Result<Vec<_>, _>>()?;
-        self.write_jsonl_file(&benchmark_path, &benchmark_lines)?;
-        let constitution_lines = self
-            .list_constitution_items()?
-            .into_iter()
-            .map(|item| serde_json::to_string(&item))
-            .collect::<std::result::Result<Vec<_>, _>>()?;
-        self.write_jsonl_file(&constitution_path, &constitution_lines)?;
-        let action_gap_lines = self
-            .list_action_gaps()?
-            .into_iter()
-            .map(|gap| serde_json::to_string(&gap))
-            .collect::<std::result::Result<Vec<_>, _>>()?;
-        self.write_jsonl_file(&action_gaps_path, &action_gap_lines)?;
-
-        // Decision episodes with sealed-prediction integrity: while an
-        // episode has no recorded choice, its prediction exports as a
-        // non-revealing stub so the bet cannot leak through an early export.
-        let decision_episode_lines = self
-            .list_decision_episodes()?
-            .into_iter()
-            .map(|episode| {
-                let still_sealed =
-                    episode.twin_prediction.is_some() && episode.chosen_option.is_none();
-                let mut value = serde_json::to_value(&episode)?;
-                if still_sealed {
-                    if let Some(object) = value.as_object_mut() {
-                        let stub = episode.twin_prediction.as_ref().map(|prediction| {
-                            serde_json::json!({
-                                "sealed": true,
-                                "sealed_at": prediction.sealed_at,
-                                "model_id": prediction.model_id,
-                                "context_version": prediction.context_version,
-                                "parse_mode": prediction.parse_mode,
-                            })
-                        });
-                        object.insert("twin_prediction".to_string(), stub.unwrap_or(Value::Null));
-                    }
-                }
-                serde_json::to_string(&value).map_err(anyhow::Error::from)
-            })
-            .collect::<Result<Vec<_>>>()?;
-        self.write_jsonl_file(&decision_episodes_path, &decision_episode_lines)?;
+        Ok(())
+    }
 
-        // Ranking / Matches-Me / insight raw material. Privacy rule: skip
-        // events that are evidence for records now marked Rejected, Private,
-        // or NoTrain.
-        let excluded_event_ids: HashSet<String> = self
-            .record_cache
-            .values()
-            .filter(|record| {
-                matches!(
-                    record.promotion_state,
-                    PromotionState::Rejected | PromotionState::Private | PromotionState::NoTrain
-                )
-            })
-            .flat_map(|record| {
-                record
-                    .evidence_refs
-                    .iter()
-                    .map(|evidence| evidence.event_id.clone())
-            })
-            .collect();
-        let feedback_event_lines = self
-            .list_session_traces()?
-            .into_iter()
-            .flat_map(|trace| {
-                let session_id = trace.session_id.clone();
-                let trace_id = trace.id.clone();
-                trace
-                    .events
-                    .into_iter()
-                    .filter(|event| {
-                        matches!(
-                            event.event_type,
-                            TraceEventType::FeedbackRecorded
-                                | TraceEventType::RankingRecorded
-                                | TraceEventType::InsightCaptured
-                        ) && !excluded_event_ids.contains(&event.id)
-                    })
-                    .map(move |event| {
-                        serde_json::to_string(&serde_json::json!({
-                            "session_id": session_id,
-                            "trace_id": trace_id,
-                            "event": event,
-                        }))
-                        .map_err(anyhow::Error::from)
-                    })
-                    .collect::<Vec<_>>()
-            })
-            .collect::<Result<Vec<_>>>()?;
-        self.write_jsonl_file(&feedback_events_path, &feedback_event_lines)?;
+    pub fn append_trace_event(
+        &mut self,
+        session_id: &str,
+        event_type: TraceEventType,
+        payload: serde_json::Value,
+    ) -> Result<TraceEvent> {
+        Self::validate_file_id(session_id)?;
+        let now = Utc::now();
+        let event = TraceEvent {
+            id: uuid::Uuid::new_v4().to_string(),
+            event_type,
+            created_at: now,
+            payload,
+        };
 
-        let manifest = serde_json::json!({
-            "bundle_schema_version": 2,
-            "generated_at": Utc::now(),
-            "root_path": self.root_path.display().to_string(),
-            "eval_percentage": eval_percentage,
-            "holdout_percentage": holdout_percentage,
-            "included_record_ids": included_record_ids,
-            "record_files": {
-                "approved_user_records": {
-                    "path": approved_path.display().to_string(),
-                    "count": approved_lines.len(),
-                },
-                "candidate_user_records": {
-                    "path": candidate_path.display().to_string(),
-                    "count": candidate_lines.len(),
-                },
-                "rejected_user_records": {
-                    "path": rejected_path.display().to_string(),
-                    "count": rejected_lines.len(),
-                },
-                "decision_mirror_benchmark": {
-                    "path": benchmark_path.display().to_string(),
-                    "count": benchmark_lines.len(),
-                },
-                "constitution_items": {
-                    "path": constitution_path.display().to_string(),
-                    "count": constitution_lines.len(),
-                },
-                "action_gaps": {
-                    "path": action_gaps_path.display().to_string(),
-                    "count": action_gap_lines.len(),
-                },
-                "decision_episodes": {
-                    "path": decision_episodes_path.display().to_string(),
-                    "count": decision_episode_lines.len(),
-                },
-                "feedback_events": {
-                    "path": feedback_events_path.display().to_string(),
-                    "count": feedback_event_lines.len(),
-                },
-            },
-            "excluded_counts": {
-                "private_or_no_train": private_or_no_train_record_ids.len(),
-            }
-        });
-        self.write_pretty_json(&manifest_path, &manifest)?;
+        let trace = self.get_or_create_trace_mut(session_id)?;
+        trace.updated_at = now;
+        trace.events.push(event.clone());
+        let trace = trace.clone();
+        self.write_trace_file(&trace)?;
 
-        Ok(ExportBundle {
-            output_dir: output_dir.display().to_string(),
-            approved_user_records: ExportFileSummary {
-                path: approved_path.display().to_string(),
-                count: approved_lines.len(),
-            },
-            candidate_user_records: ExportFileSummary {
-                path: candidate_path.display().to_string(),
-                count: candidate_lines.len(),
-            },
-            rejected_user_records: ExportFileSummary {
-                path: rejected_path.display().to_string(),
-                count: rejected_lines.len(),
-            },
-            decision_mirror_benchmark: ExportFileSummary {
-                path: benchmark_path.display().to_string(),
-                count: benchmark_lines.len(),
-            },
-            constitution_items: ExportFileSummary {
-                path: constitution_path.display().to_string(),
-                count: constitution_lines.len(),
-            },
-            action_gaps: ExportFileSummary {
-                path: action_gaps_path.display().to_string(),
-                count: action_gap_lines.len(),
-            },
-            decision_episodes: ExportFileSummary {
-                path: decision_episodes_path.display().to_string(),
-                count: decision_episode_lines.len(),
-            },
-            feedback_events: ExportFileSummary {
-                path: feedback_events_path.display().to_string(),
-                count: feedback_event_lines.len(),
-            },
-            train: ExportFileSummary {
-                path: train_path.display().to_string(),
-                count: train_lines.len(),
-            },
-            eval: ExportFileSummary {
-                path: eval_path.display().to_string(),
-                count: eval_lines.len(),
-            },
-            holdout: ExportFileSummary {
-                path: holdout_path.display().to_string(),
-                count: holdout_lines.len(),
-            },
-            manifest_path: manifest_path.display().to_string(),
-            included_records: train_lines.len() + eval_lines.len() + holdout_lines.len(),
-            excluded_records: private_or_no_train_record_ids.len(),
-        })
+        Ok(event)
+    }
+
+    pub fn get_session_trace(&mut self, session_id: &str) -> Result<SessionTrace> {
+        Self::validate_file_id(session_id)?;
+        if let Some(trace) = self.trace_cache.get(session_id) {
+            return Ok(trace.clone());
+        }
+
+        let path = self.trace_file_path(session_id);
+        if !path.exists() {
+            let trace = SessionTrace::new(session_id);
+            self.trace_cache
+                .insert(session_id.to_string(), trace.clone());
+            return Ok(trace);
+        }
+
+        let trace = self.read_trace_file(&path)?;
+        self.trace_cache
+            .insert(session_id.to_string(), trace.clone());
+        Ok(trace)
     }
 
-    fn list_session_traces(&mut self) -> Result<Vec<SessionTrace>> {
+    pub(super) fn list_session_traces(&mut self) -> Result<Vec<SessionTrace>> {
         for entry in WalkDir::new(&self.traces_path)
             .min_depth(1)
             .max_depth(1)
@@ -2279,7 +1887,10 @@ impl TwinStore {
         Ok(traces)
     }
 
-    fn resolve_evidence_refs(&mut self, refs: &[EvidenceRef]) -> Result<Vec<ResolvedEvidenceRef>> {
+    pub(super) fn resolve_evidence_refs(
+        &mut self,
+        refs: &[EvidenceRef],
+    ) -> Result<Vec<ResolvedEvidenceRef>> {
         let mut resolved = Vec::new();
         for evidence_ref in refs {
             let trace_id = if evidence_ref.trace_id.trim().is_empty() {
@@ -2320,200 +1931,389 @@ impl TwinStore {
             .expect("trace inserted"))
     }
 
-    fn ensure_record_cache(&mut self) -> Result<()> {
-        if self.records_cache_ready {
-            return Ok(());
+    pub(super) fn trace_file_path(&self, session_id: &str) -> PathBuf {
+        self.traces_path.join(format!("{}.json", session_id))
+    }
+
+    pub(super) fn read_trace_file(&self, path: &Path) -> Result<SessionTrace> {
+        let content = std::fs::read_to_string(path)
+            .with_context(|| format!("Failed to read trace file: {}", path.display()))?;
+        serde_json::from_str(&content)
+            .with_context(|| format!("Failed to parse trace file: {}", path.display()))
+    }
+
+    fn write_trace_file(&self, trace: &SessionTrace) -> Result<()> {
+        let path = self.trace_file_path(&trace.session_id);
+        self.write_pretty_json(&path, trace)
+    }
+
+    pub fn list_user_records(&mut self) -> Result<Vec<UserRecord>> {
+        self.ensure_record_cache()?;
+        let mut records: Vec<UserRecord> = self.record_cache.values().cloned().collect();
+        records.sort_by(|a, b| b.updated_at.cmp(&a.updated_at));
+        Ok(records)
+    }
+
+    pub fn get_user_record(&mut self, id: &str) -> Result<UserRecord> {
+        Self::validate_file_id(id)?;
+        if let Some(record) = self.record_cache.get(id) {
+            return Ok(record.clone());
         }
 
-        for entry in WalkDir::new(&self.records_path)
-            .min_depth(1)
-            .max_depth(1)
-            .into_iter()
-            .filter_map(|entry| entry.ok())
-        {
-            let path = entry.path();
-            if path.extension().is_some_and(|ext| ext == "json") {
-                if let Some(record) = load_or_quarantine::<UserRecord>(path, "record") {
-                    self.record_cache.insert(record.id.clone(), record);
+        let path = self.record_file_path(id);
+        let record = self.read_record_file(&path)?;
+        self.record_cache.insert(id.to_string(), record.clone());
+        Ok(record)
+    }
+
+    pub fn create_user_record(&mut self, create: UserRecordCreate) -> Result<UserRecord> {
+        self.ensure_record_cache()?;
+
+        let now = Utc::now();
+        let promotion_state = create
+            .promotion_state
+            .unwrap_or_else(|| PromotionState::default_for_origin(&create.origin));
+
+        let record = UserRecord {
+            id: uuid::Uuid::new_v4().to_string(),
+            kind: create.kind,
+            content: create.content,
+            evidence_refs: create.evidence_refs,
+            confidence: create.confidence.clamp(0.0, 1.0),
+            origin: create.origin,
+            promotion_state,
+            created_at: now,
+            updated_at: now,
+            valid_from: create.valid_from,
+            valid_until: create.valid_until,
+            links: create.links,
+            metadata: create.metadata,
+        };
+
+        self.record_cache.insert(record.id.clone(), record.clone());
+        self.write_record_file(&record)?;
+
+        Ok(record)
+    }
+
+    pub fn update_user_record(&mut self, id: &str, update: UserRecordUpdate) -> Result<UserRecord> {
+        self.ensure_record_cache()?;
+        let mut record = self.get_user_record(id)?;
+
+        if let Some(content) = update.content {
+            record.content = content;
+        }
+        if let Some(confidence) = update.confidence {
+            record.confidence = confidence.clamp(0.0, 1.0);
+        }
+        if let Some(promotion_state) = update.promotion_state {
+            record.promotion_state = promotion_state;
+        }
+        if let Some(valid_from) = update.valid_from {
+            record.valid_from = Some(valid_from);
+        }
+        if let Some(valid_until) = update.valid_until {
+            record.valid_until = Some(valid_until);
+        }
+        if let Some(links) = update.links {
+            record.links = links;
+        }
+        if let Some(metadata) = update.metadata {
+            record.metadata = metadata;
+        }
+
+        record.updated_at = Utc::now();
+        self.record_cache.insert(record.id.clone(), record.clone());
+        self.write_record_file(&record)?;
+
+        Ok(record)
+    }
+
+    pub fn run_twin_inference(&mut self) -> Result<TwinInferenceRunSummary> {
+        self.ensure_record_cache()?;
+        let traces = self.list_session_traces()?;
+        let scanned_events = traces.iter().map(|trace| trace.events.len()).sum::<usize>();
+        let drafts = infer_behavioral_records(&traces);
+
+        let mut existing_by_key = HashMap::new();
+        let mut rejected_keys = HashSet::new();
+        for record in self.record_cache.values() {
+            if let Some(inference_key) = record
+                .metadata
+                .get("inference_key")
+                .and_then(Value::as_str)
+                .map(ToOwned::to_owned)
+            {
+                existing_by_key.insert(inference_key.clone(), record.id.clone());
+                if record.promotion_state == PromotionState::Rejected {
+                    rejected_keys.insert(inference_key);
+                }
+            }
+        }
+
+        let mut created_records = 0_usize;
+        let mut updated_records = 0_usize;
+        let mut auto_promoted_records = 0_usize;
+        let mut candidate_records = 0_usize;
+        let mut skipped_rejected_records = 0_usize;
+
+        for draft in drafts {
+            let desired_state = if draft.confidence >= AUTO_PROMOTE_CONFIDENCE
+                && draft.support_count >= AUTO_PROMOTE_SUPPORT_COUNT
+            {
+                PromotionState::AutoPromoted
+            } else {
+                PromotionState::Candidate
+            };
+            let mut metadata =
+                build_inference_metadata(&draft, desired_state == PromotionState::AutoPromoted);
+
+            if let Some(existing_id) = existing_by_key.get(&draft.inference_key).cloned() {
+                let mut record = self.get_user_record(&existing_id)?;
+                let previous_state = record.promotion_state.clone();
+                let is_rejected_key = rejected_keys.contains(&draft.inference_key);
+
+                record.kind = draft.kind.clone();
+                record.content = draft.content.clone();
+                record.evidence_refs = draft.evidence_refs.clone();
+                record.confidence = draft.confidence;
+                record.origin = RecordOrigin::Inferred;
+
+                if is_rejected_key {
+                    metadata.insert("auto_promoted".to_string(), Value::Bool(false));
+                    record.promotion_state = PromotionState::Rejected;
+                    skipped_rejected_records += 1;
+                } else if matches!(
+                    record.promotion_state,
+                    PromotionState::Candidate | PromotionState::AutoPromoted
+                ) {
+                    record.promotion_state = desired_state.clone();
+                }
+
+                metadata = merge_promotion_history(record.metadata.clone(), metadata);
+                if previous_state != record.promotion_state {
+                    append_promotion_history(
+                        &mut metadata,
+                        &previous_state,
+                        &record.promotion_state,
+                        Some("local signal inference threshold"),
+                        true,
+                    );
+                }
+
+                record.metadata = metadata;
+                record.updated_at = Utc::now();
+                self.record_cache.insert(record.id.clone(), record.clone());
+                self.write_record_file(&record)?;
+                updated_records += 1;
+            } else {
+                let mut metadata = metadata;
+                if desired_state == PromotionState::AutoPromoted {
+                    append_promotion_history(
+                        &mut metadata,
+                        &PromotionState::Candidate,
+                        &PromotionState::AutoPromoted,
+                        Some("confidence >= 0.75 and support_count >= 3"),
+                        true,
+                    );
                 }
+
+                self.create_user_record(UserRecordCreate {
+                    kind: draft.kind,
+                    content: draft.content,
+                    evidence_refs: draft.evidence_refs,
+                    confidence: draft.confidence,
+                    origin: RecordOrigin::Inferred,
+                    promotion_state: Some(desired_state),
+                    valid_from: None,
+                    valid_until: None,
+                    links: Vec::new(),
+                    metadata,
+                })?;
+                created_records += 1;
             }
         }
 
-        self.records_cache_ready = true;
-        Ok(())
-    }
-
-    fn split_for_record(
-        record: &UserRecord,
-        eval_percentage: u8,
-        holdout_percentage: u8,
-    ) -> ExportSplit {
-        let key = format!(
-            "{}:{}:{}:{}",
-            record.id,
-            serde_json::to_string(&record.kind).unwrap_or_default(),
-            record.content,
-            record.updated_at
-        );
-        let bucket = Self::stable_bucket(&key);
-
-        if bucket < holdout_percentage {
-            ExportSplit::Holdout
-        } else if bucket < holdout_percentage + eval_percentage {
-            ExportSplit::Eval
-        } else {
-            ExportSplit::Train
+        for record in self.record_cache.values() {
+            if record.origin != RecordOrigin::Inferred {
+                continue;
+            }
+            match record.promotion_state {
+                PromotionState::AutoPromoted => auto_promoted_records += 1,
+                PromotionState::Candidate => candidate_records += 1,
+                _ => {}
+            }
         }
-    }
-
-    fn stable_bucket(key: &str) -> u8 {
-        let mut hasher = DefaultHasher::new();
-        key.hash(&mut hasher);
-        (hasher.finish() % 100) as u8
-    }
 
-    fn record_to_export_value(record: &UserRecord) -> serde_json::Value {
-        serde_json::json!({
-            "id": record.id,
-            "kind": record.kind,
-            "content": record.content,
-            "origin": record.origin,
-            "promotion_state": record.promotion_state,
-            "confidence": record.confidence,
-            "created_at": record.created_at,
-            "updated_at": record.updated_at,
-            "valid_from": record.valid_from,
-            "valid_until": record.valid_until,
-            "links": record.links,
-            "evidence_refs": record.evidence_refs,
-            "metadata": record.metadata,
+        Ok(TwinInferenceRunSummary {
+            inference_version: TWIN_INFERENCE_VERSION.to_string(),
+            scanned_traces: traces.len(),
+            scanned_events,
+            created_records,
+            updated_records,
+            auto_promoted_records,
+            candidate_records,
+            skipped_rejected_records,
+            generated_at: Utc::now(),
         })
     }
 
-    fn trace_file_path(&self, session_id: &str) -> PathBuf {
-        self.traces_path.join(format!("{}.json", session_id))
-    }
-
-    fn record_file_path(&self, record_id: &str) -> PathBuf {
-        self.records_path.join(format!("{}.json", record_id))
-    }
-
-    fn decision_file_path(&self, decision_id: &str) -> PathBuf {
-        self.decisions_path.join(format!("{}.json", decision_id))
-    }
-
-    fn reflection_file_path(&self, reflection_id: &str) -> PathBuf {
-        self.reflections_path
-            .join(format!("{}.json", reflection_id))
-    }
+    pub fn get_twin_review(&mut self) -> Result<Vec<TwinReviewRecord>> {
+        let records = self.list_user_records()?;
+        let mut review = Vec::with_capacity(records.len());
 
-    fn constitution_file_path(&self, item_id: &str) -> PathBuf {
-        self.constitution_path.join(format!("{}.json", item_id))
-    }
+        for record in records {
+            let evidence = self.resolve_evidence_refs(&record.evidence_refs)?;
+            review.push(TwinReviewRecord {
+                evidence_count: record.evidence_refs.len(),
+                latest_evidence: evidence.into_iter().max_by_key(|item| item.created_at),
+                record,
+            });
+        }
 
-    fn action_gap_file_path(&self, gap_id: &str) -> PathBuf {
-        self.action_gaps_path.join(format!("{}.json", gap_id))
-    }
+        review.sort_by(|a, b| {
+            promotion_state_sort_key(&a.record.promotion_state)
+                .cmp(&promotion_state_sort_key(&b.record.promotion_state))
+                .then_with(|| b.record.updated_at.cmp(&a.record.updated_at))
+        });
 
-    fn read_trace_file(&self, path: &Path) -> Result<SessionTrace> {
-        let content = std::fs::read_to_string(path)
-            .with_context(|| format!("Failed to read trace file: {}", path.display()))?;
-        serde_json::from_str(&content)
-            .with_context(|| format!("Failed to parse trace file: {}", path.display()))
+        Ok(review)
     }
 
-    fn read_record_file(&self, path: &Path) -> Result<UserRecord> {
-        let content = std::fs::read_to_string(path)
-            .with_context(|| format!("Failed to read record file: {}", path.display()))?;
-        serde_json::from_str(&content)
-            .with_context(|| format!("Failed to parse record file: {}", path.display()))
-    }
+    pub fn select_context_records(
+        &mut self,
+        query: &str,
+    ) -> Result<(Vec<TwinContextRecord>, Vec<TwinContextRecord>)> {
+        self.ensure_record_cache()?;
 
-    fn read_decision_file(&self, path: &Path) -> Result<DecisionEpisode> {
-        let content = std::fs::read_to_string(path)
-            .with_context(|| format!("Failed to read decision file: {}", path.display()))?;
-        serde_json::from_str(&content)
-            .with_context(|| format!("Failed to parse decision file: {}", path.display()))
-    }
+        let query_terms = lexical_terms(query);
+        let mut approved = Vec::new();
+        let mut approved_fallback = Vec::new();
+        let mut candidates = Vec::new();
 
-    fn read_constitution_file(&self, path: &Path) -> Result<ConstitutionItem> {
-        let content = std::fs::read_to_string(path)
-            .with_context(|| format!("Failed to read constitution file: {}", path.display()))?;
-        serde_json::from_str(&content)
-            .with_context(|| format!("Failed to parse constitution file: {}", path.display()))
-    }
+        for record in self.record_cache.values() {
+            match record.promotion_state {
+                PromotionState::Endorsed | PromotionState::AutoPromoted => {
+                    let relevance = twin_record_relevance(record, &query_terms);
+                    if relevance > 0 {
+                        approved.push((relevance, twin_context_record(record, "approved")));
+                    } else {
+                        approved_fallback.push(twin_context_record(record, "approved"));
+                    }
+                }
+                PromotionState::Candidate => {
+                    let relevance = twin_record_relevance(record, &query_terms);
+                    if relevance > 0 {
+                        candidates.push((
+                            relevance,
+                            record.updated_at,
+                            twin_context_record(record, "candidate"),
+                        ));
+                    }
+                }
+                PromotionState::Rejected | PromotionState::Private | PromotionState::NoTrain => {}
+            }
+        }
 
-    fn read_action_gap_file(&self, path: &Path) -> Result<ActionGap> {
-        let content = std::fs::read_to_string(path)
-            .with_context(|| format!("Failed to read action gap file: {}", path.display()))?;
-        serde_json::from_str(&content)
-            .with_context(|| format!("Failed to parse action gap file: {}", path.display()))
-    }
+        approved.sort_by(|a, b| {
+            b.0.cmp(&a.0).then_with(|| {
+                b.1.confidence
+                    .partial_cmp(&a.1.confidence)
+                    .unwrap_or(std::cmp::Ordering::Equal)
+                    .then_with(|| b.1.evidence_count.cmp(&a.1.evidence_count))
+            })
+        });
 
-    fn read_memory_digest_file(&self) -> Result<Vec<MemoryDigestItem>> {
-        if !self.digest_path.exists() {
-            return Ok(Vec::new());
-        }
+        let approved: Vec<TwinContextRecord> = if approved.is_empty() {
+            // Never assemble an empty behavioral context just because the
+            // query shares no keywords with any approved record.
+            approved_fallback.sort_by(|a, b| {
+                b.confidence
+                    .partial_cmp(&a.confidence)
+                    .unwrap_or(std::cmp::Ordering::Equal)
+                    .then_with(|| b.evidence_count.cmp(&a.evidence_count))
+            });
+            approved_fallback
+                .into_iter()
+                .take(MAX_TWIN_APPROVED_FALLBACK_RECORDS)
+                .collect()
+        } else {
+            approved
+                .into_iter()
+                .take(MAX_TWIN_APPROVED_CONTEXT_RECORDS)
+                .map(|(_, record)| record)
+                .collect()
+        };
 
-        let content = std::fs::read_to_string(&self.digest_path).with_context(|| {
-            format!(
-                "Failed to read memory digest file: {}",
-                self.digest_path.display()
-            )
-        })?;
-        serde_json::from_str(&content).with_context(|| {
-            format!(
-                "Failed to parse memory digest file: {}",
-                self.digest_path.display()
-            )
-        })
-    }
+        candidates.sort_by(|a, b| {
+            b.0.cmp(&a.0).then_with(|| b.1.cmp(&a.1)).then_with(|| {
+                b.2.confidence
+                    .partial_cmp(&a.2.confidence)
+                    .unwrap_or(std::cmp::Ordering::Equal)
+            })
+        });
 
-    fn write_decision_mirror_config_file(&self, config: &DecisionMirrorConfig) -> Result<()> {
-        self.write_pretty_json(&self.decision_mirror_config_path, config)
+        Ok((
+            approved,
+            candidates
+                .into_iter()
+                .take(MAX_TWIN_CANDIDATE_CONTEXT_RECORDS)
+                .map(|(_, _, record)| record)
+                .collect(),
+        ))
     }
 
-    fn write_trace_file(&self, trace: &SessionTrace) -> Result<()> {
-        let path = self.trace_file_path(&trace.session_id);
-        self.write_pretty_json(&path, trace)
+    pub fn resolve_user_record_evidence(&mut self, id: &str) -> Result<Vec<ResolvedEvidenceRef>> {
+        let record = self.get_user_record(id)?;
+        self.resolve_evidence_refs(&record.evidence_refs)
     }
 
-    fn write_record_file(&self, record: &UserRecord) -> Result<()> {
-        let path = self.record_file_path(&record.id);
-        self.write_pretty_json(&path, record)
-    }
+    pub fn set_user_record_promotion(
+        &mut self,
+        id: &str,
+        promotion_state: PromotionState,
+        rationale: Option<String>,
+    ) -> Result<UserRecord> {
+        self.ensure_record_cache()?;
+        let mut record = self.get_user_record(id)?;
+        let previous_state = record.promotion_state.clone();
+        let now = Utc::now();
 
-    fn write_decision_file(&self, episode: &DecisionEpisode) -> Result<()> {
-        let path = self.decision_file_path(&episode.id);
-        self.write_pretty_json(&path, episode)
-    }
+        record.promotion_state = promotion_state.clone();
+        record.updated_at = now;
 
-    fn write_reflection_file(&self, card: &ReflectionCard) -> Result<()> {
-        let path = self.reflection_file_path(&card.id);
-        self.write_pretty_json(&path, card)
-    }
+        append_promotion_history(
+            &mut record.metadata,
+            &previous_state,
+            &promotion_state,
+            rationale.as_deref(),
+            false,
+        );
 
-    fn write_constitution_file(&self, item: &ConstitutionItem) -> Result<()> {
-        let path = self.constitution_file_path(&item.id);
-        self.write_pretty_json(&path, item)
-    }
+        if promotion_state == PromotionState::Rejected {
+            record
+                .metadata
+                .insert("reverted_at".to_string(), json!(now));
+            record
+                .metadata
+                .insert("revert_reason".to_string(), json!(rationale));
+            record
+                .metadata
+                .insert("auto_promoted".to_string(), Value::Bool(false));
+        }
 
-    fn write_action_gap_file(&self, gap: &ActionGap) -> Result<()> {
-        let path = self.action_gap_file_path(&gap.id);
-        self.write_pretty_json(&path, gap)
-    }
+        self.record_cache.insert(record.id.clone(), record.clone());
+        self.write_record_file(&record)?;
 
-    fn write_memory_digest_file(&self, items: &[MemoryDigestItem]) -> Result<()> {
-        self.write_pretty_json(&self.digest_path, &items)
+        Ok(record)
     }
 
-    fn list_reflection_cards(&self) -> Result<Vec<ReflectionCard>> {
-        let mut cards = Vec::new();
-        if !self.reflections_path.exists() {
-            return Ok(cards);
+    pub(super) fn ensure_record_cache(&mut self) -> Result<()> {
+        if self.records_cache_ready {
+            return Ok(());
         }
 
-        for entry in WalkDir::new(&self.reflections_path)
+        for entry in WalkDir::new(&self.records_path)
             .min_depth(1)
             .max_depth(1)
             .into_iter()
@@ -2521,2076 +2321,2065 @@ impl TwinStore {
         {
             let path = entry.path();
             if path.extension().is_some_and(|ext| ext == "json") {
-                if let Some(card) = load_or_quarantine::<ReflectionCard>(path, "reflection card") {
-                    cards.push(card);
+                if let Some(record) = load_or_quarantine::<UserRecord>(path, "record") {
+                    self.record_cache.insert(record.id.clone(), record);
                 }
             }
         }
 
-        cards.sort_by(|a, b| b.created_at.cmp(&a.created_at));
-        Ok(cards)
+        self.records_cache_ready = true;
+        Ok(())
     }
 
-    fn seed_constitution_setup_items(
-        &self,
-        setup: &ConstitutionSetup,
-        evidence_ref: EvidenceRef,
-    ) -> Result<()> {
-        let existing_keys = self
-            .list_constitution_items()?
-            .into_iter()
-            .map(|item| constitution_key(&item.dimension, &item.claim))
-            .collect::<HashSet<_>>();
-        let mut created_keys = existing_keys;
-
-        let groups: &[(&str, &[String])] = &[
-            ("values", &setup.values),
-            ("taste", &setup.tastes),
-            ("constraints", &setup.constraints),
-            ("somatic", &setup.somatic_cues),
-            ("action_tendency", &setup.action_tendencies),
-        ];
+    fn record_file_path(&self, record_id: &str) -> PathBuf {
+        self.records_path.join(format!("{}.json", record_id))
+    }
 
-        for (dimension, entries) in groups {
-            for entry in entries.iter().filter(|entry| !entry.trim().is_empty()) {
-                let claim = entry.trim().to_string();
-                let key = constitution_key(dimension, &claim);
-                if !created_keys.insert(key) {
-                    continue;
-                }
-                self.create_constitution_item(ConstitutionItemCreate {
-                    claim,
-                    dimension: (*dimension).to_string(),
-                    scope: vec!["setup".to_string()],
-                    priority: 0.9,
-                    confidence: 0.9,
-                    status: ConstitutionStatus::Active,
-                    evidence_refs: vec![evidence_ref.clone()],
-                    tensions: Vec::new(),
-                    linked_record_ids: Vec::new(),
-                    source: Some("guided_setup".to_string()),
-                })?;
-            }
-        }
+    fn read_record_file(&self, path: &Path) -> Result<UserRecord> {
+        let content = std::fs::read_to_string(path)
+            .with_context(|| format!("Failed to read record file: {}", path.display()))?;
+        serde_json::from_str(&content)
+            .with_context(|| format!("Failed to parse record file: {}", path.display()))
+    }
 
-        Ok(())
+    pub(super) fn write_record_file(&self, record: &UserRecord) -> Result<()> {
+        let path = self.record_file_path(&record.id);
+        self.write_pretty_json(&path, record)
     }
 
-    fn decision_evidence_refs(&self, decision_id: &str) -> Result<Vec<EvidenceRef>> {
-        Self::validate_file_id(decision_id)?;
-        let mut refs = Vec::new();
-        for entry in WalkDir::new(&self.traces_path)
+    pub fn list_constitution_items(&self) -> Result<Vec<ConstitutionItem>> {
+        let mut items = Vec::new();
+        if !self.constitution_path.exists() {
+            return Ok(items);
+        }
+
+        for entry in WalkDir::new(&self.constitution_path)
             .min_depth(1)
             .max_depth(1)
             .into_iter()
             .filter_map(|entry| entry.ok())
         {
             let path = entry.path();
-            if !path.extension().is_some_and(|ext| ext == "json") {
-                continue;
-            }
-            let Some(trace) = load_or_quarantine::<SessionTrace>(path, "trace") else {
-                // A corrupt trace only omits its own evidence refs; the
-                // decision's evidence from healthy traces is still collected.
-                continue;
-            };
-            for event in trace.events {
-                let event_decision_id =
-                    payload_string(&event.payload, &["decision_episode_id"]).unwrap_or_default();
-                if event_decision_id != decision_id {
-                    continue;
+            if path.extension().is_some_and(|ext| ext == "json") {
+                if let Some(item) =
+                    load_or_quarantine::<ConstitutionItem>(path, "constitution item")
+                {
+                    items.push(item);
                 }
-                refs.push(EvidenceRef {
-                    trace_id: trace.id.clone(),
-                    event_id: event.id.clone(),
-                    session_id: trace.session_id.clone(),
-                    tile_id: extract_event_tile_id(&event.payload),
-                    model_id: extract_event_model_id(&event.payload),
-                    note: Some("Decision episode evidence".to_string()),
-                    source_type: Some("decision".to_string()),
-                    source_id: Some(decision_id.to_string()),
-                    source_label: Some("Decision episode evidence".to_string()),
-                    excerpt: None,
-                    speaker_role: None,
-                });
             }
         }
-        refs.sort_by(|a, b| a.event_id.cmp(&b.event_id));
-        Ok(refs)
+
+        items.sort_by(|a, b| {
+            constitution_status_sort_key(&a.status)
+                .cmp(&constitution_status_sort_key(&b.status))
+                .then_with(|| {
+                    b.priority
+                        .partial_cmp(&a.priority)
+                        .unwrap_or(std::cmp::Ordering::Equal)
+                })
+                .then_with(|| b.updated_at.cmp(&a.updated_at))
+        });
+        Ok(items)
     }
 
-    fn decision_feedback_events(&self, episode: &DecisionEpisode) -> Result<Vec<TraceEvent>> {
-        Self::validate_file_id(&episode.session_id)?;
-        let path = self.trace_file_path(&episode.session_id);
-        if !path.exists() {
-            return Ok(Vec::new());
-        }
+    pub fn create_constitution_item(
+        &self,
+        create: ConstitutionItemCreate,
+    ) -> Result<ConstitutionItem> {
+        let now = Utc::now();
+        let item = ConstitutionItem {
+            id: uuid::Uuid::new_v4().to_string(),
+            claim: create.claim,
+            dimension: create.dimension,
+            scope: create.scope,
+            priority: create.priority.clamp(0.0, 1.0),
+            confidence: create.confidence.clamp(0.0, 1.0),
+            status: create.status,
+            evidence_refs: create.evidence_refs,
+            tensions: create.tensions,
+            linked_record_ids: create.linked_record_ids,
+            source: create.source,
+            created_at: now,
+            updated_at: now,
+        };
+        self.write_constitution_file(&item)?;
+        Ok(item)
+    }
 
-        let trace = self.read_trace_file(&path)?;
-        let mut events = trace
-            .events
-            .into_iter()
-            .filter(|event| {
-                matches!(
-                    event.event_type,
-                    TraceEventType::FeedbackRecorded
-                        | TraceEventType::RankingRecorded
-                        | TraceEventType::InsightCaptured
-                )
-            })
-            .filter(|event| {
-                payload_string(&event.payload, &["decision_episode_id"])
-                    .is_some_and(|id| id == episode.id)
-                    || extract_event_tile_id(&event.payload)
-                        .is_some_and(|tile_id| tile_id == episode.tile_id)
-            })
-            .collect::<Vec<_>>();
-        events.sort_by(|a, b| b.created_at.cmp(&a.created_at));
-        Ok(events)
+    pub fn update_constitution_item(
+        &self,
+        id: &str,
+        update: ConstitutionItemUpdate,
+    ) -> Result<ConstitutionItem> {
+        Self::validate_file_id(id)?;
+        let path = self.constitution_file_path(id);
+        let mut item = self.read_constitution_file(&path)?;
+        if let Some(claim) = update.claim {
+            item.claim = claim;
+        }
+        if let Some(dimension) = update.dimension {
+            item.dimension = dimension;
+        }
+        if let Some(scope) = update.scope {
+            item.scope = scope;
+        }
+        if let Some(priority) = update.priority {
+            item.priority = priority.clamp(0.0, 1.0);
+        }
+        if let Some(confidence) = update.confidence {
+            item.confidence = confidence.clamp(0.0, 1.0);
+        }
+        if let Some(status) = update.status {
+            item.status = status;
+        }
+        if let Some(tensions) = update.tensions {
+            item.tensions = tensions;
+        }
+        item.updated_at = Utc::now();
+        self.write_constitution_file(&item)?;
+        Ok(item)
     }
 
-    fn write_jsonl_file(&self, path: &Path, lines: &[String]) -> Result<()> {
-        let mut content = lines.join("\n");
-        if !content.is_empty() {
-            content.push('\n');
-        }
-        write_atomic(path, content.as_bytes())
-            .with_context(|| format!("Failed to write JSONL file: {}", path.display()))
+    pub fn review_constitution_item(
+        &mut self,
+        id: &str,
+        request: ConstitutionReviewRequest,
+    ) -> Result<ConstitutionItem> {
+        Self::validate_file_id(id)?;
+        let mut item = self.read_constitution_file(&self.constitution_file_path(id))?;
+        item.status = constitution_status_for_action(&request.action);
+        item.updated_at = Utc::now();
+        self.write_constitution_file(&item)?;
+        self.append_trace_event(
+            "constitution-review",
+            TraceEventType::ConstitutionItemReviewed,
+            json!({
+                "constitution_item_id": item.id,
+                "action": request.action,
+                "rationale": request.rationale,
+            }),
+        )?;
+        Ok(item)
     }
 
-    fn write_pretty_json<T: Serialize>(&self, path: &Path, value: &T) -> Result<()> {
-        if let Some(parent) = path.parent() {
-            std::fs::create_dir_all(parent)
-                .with_context(|| format!("Failed to create directory: {}", parent.display()))?;
+    pub fn list_action_gaps(&self) -> Result<Vec<ActionGap>> {
+        let mut gaps = Vec::new();
+        if !self.action_gaps_path.exists() {
+            return Ok(gaps);
         }
 
-        let content = serde_json::to_string_pretty(value)?;
-        write_atomic(path, content.as_bytes())
-            .with_context(|| format!("Failed to write JSON file: {}", path.display()))
-    }
-
-    fn validate_file_id(id: &str) -> Result<()> {
-        if id.is_empty() || id.contains('/') || id.contains('\\') || id.contains("..") {
-            anyhow::bail!("Invalid file id: {}", id);
+        for entry in WalkDir::new(&self.action_gaps_path)
+            .min_depth(1)
+            .max_depth(1)
+            .into_iter()
+            .filter_map(|entry| entry.ok())
+        {
+            let path = entry.path();
+            if path.extension().is_some_and(|ext| ext == "json") {
+                if let Some(gap) = load_or_quarantine::<ActionGap>(path, "action gap") {
+                    gaps.push(gap);
+                }
+            }
         }
 
-        Ok(())
+        gaps.sort_by(|a, b| {
+            constitution_status_sort_key(&a.status)
+                .cmp(&constitution_status_sort_key(&b.status))
+                .then_with(|| {
+                    b.confidence
+                        .partial_cmp(&a.confidence)
+                        .unwrap_or(std::cmp::Ordering::Equal)
+                })
+                .then_with(|| b.updated_at.cmp(&a.updated_at))
+        });
+        Ok(gaps)
     }
-}
-
-/// Outcome of attempting to load a single JSON file within a per-file directory listing.
-enum FileLoadOutcome<T> {
-    Loaded(T),
-    /// The file couldn't be read (permissions, transient lock, etc). This is not
-    /// necessarily corruption — the file may be fine — so it must not be quarantined.
-    ReadFailed(anyhow::Error),
-    /// The file was read successfully but its content didn't parse as JSON. This is
-    /// genuine corruption (truncated write, hand-edit gone wrong) and should be
-    /// quarantined so it never bricks the listing again.
-    ParseFailed(anyhow::Error),
-}
 
-fn load_json_file<T: DeserializeOwned>(path: &Path) -> FileLoadOutcome<T> {
-    let content = match std::fs::read_to_string(path) {
-        Ok(content) => content,
-        Err(e) => return FileLoadOutcome::ReadFailed(anyhow::Error::new(e)),
-    };
-    match serde_json::from_str::<T>(&content) {
-        Ok(value) => FileLoadOutcome::Loaded(value),
-        Err(e) => FileLoadOutcome::ParseFailed(anyhow::Error::new(e)),
+    pub fn create_action_gap(&self, create: ActionGapCreate) -> Result<ActionGap> {
+        let now = Utc::now();
+        let gap = ActionGap {
+            id: uuid::Uuid::new_v4().to_string(),
+            stated_value: create.stated_value,
+            revealed_behavior: create.revealed_behavior,
+            driver_hypothesis: create.driver_hypothesis,
+            somatic_taste_signal: create.somatic_taste_signal,
+            decision_risk: create.decision_risk,
+            evidence_refs: create.evidence_refs,
+            linked_record_ids: create.linked_record_ids,
+            confidence: create.confidence.clamp(0.0, 1.0),
+            status: create.status,
+            created_at: now,
+            updated_at: now,
+        };
+        self.write_action_gap_file(&gap)?;
+        Ok(gap)
     }
-}
 
-/// Rename a corrupt file to `{name}.corrupt-{unix-timestamp}` in the same directory so
-/// the bytes aren't lost. Best-effort: if the rename itself fails, log and leave the
-/// file in place (it's still skipped for this pass by the caller).
-fn quarantine_corrupt_file(path: &Path) {
-    let timestamp = SystemTime::now()
-        .duration_since(UNIX_EPOCH)
-        .map(|d| d.as_secs())
-        .unwrap_or(0);
-    let Some(file_name) = path.file_name().and_then(|n| n.to_str()) else {
-        log::error!(
-            "Cannot quarantine file with non-UTF8 name: {}",
-            path.display()
-        );
-        return;
-    };
-    let quarantine_path = path.with_file_name(format!("{file_name}.corrupt-{timestamp}"));
-
-    match std::fs::rename(path, &quarantine_path) {
-        Ok(()) => log::error!(
-            "Quarantined corrupt file {} to {}",
-            path.display(),
-            quarantine_path.display()
-        ),
-        Err(e) => log::error!(
-            "Failed to quarantine corrupt file {} to {}: {}",
-            path.display(),
-            quarantine_path.display(),
-            e
-        ),
+    pub fn review_action_gap(
+        &mut self,
+        id: &str,
+        request: ConstitutionReviewRequest,
+    ) -> Result<ActionGap> {
+        Self::validate_file_id(id)?;
+        let mut gap = self.read_action_gap_file(&self.action_gap_file_path(id))?;
+        gap.status = constitution_status_for_action(&request.action);
+        gap.updated_at = Utc::now();
+        self.write_action_gap_file(&gap)?;
+        self.append_trace_event(
+            "constitution-review",
+            TraceEventType::ActionGapReviewed,
+            json!({
+                "action_gap_id": gap.id,
+                "action": request.action,
+                "rationale": request.rationale,
+            }),
+        )?;
+        Ok(gap)
     }
-}
 
-/// Load a single JSON file within a per-file directory-listing loop (record cache fill,
-/// session-trace listing, decision episodes, constitution items, action gaps, reflection
-/// cards). Instead of `?`-propagating and letting one bad file brick the whole listing,
-/// this skips the offending file and returns `None`:
-/// - a parse failure quarantines the file (renamed + logged) so it's never retried, and
-/// - a read failure is skipped without quarantine, since it may be transient/permissions
-///   and the file itself could be perfectly fine.
-fn load_or_quarantine<T: DeserializeOwned>(path: &Path, kind: &str) -> Option<T> {
-    match load_json_file::<T>(path) {
-        FileLoadOutcome::Loaded(value) => Some(value),
-        FileLoadOutcome::ReadFailed(e) => {
-            log::error!(
-                "Skipping unreadable {} file {}: {}",
-                kind,
-                path.display(),
-                e
-            );
-            None
-        }
-        FileLoadOutcome::ParseFailed(e) => {
-            log::error!(
-                "Skipping corrupt {} file {}: {} — quarantining",
-                kind,
-                path.display(),
-                e
-            );
-            quarantine_corrupt_file(path);
-            None
+    pub fn get_constitution_setup(&self) -> Result<ConstitutionSetup> {
+        if !self.setup_path.exists() {
+            return Ok(ConstitutionSetup::default());
         }
-    }
-}
 
-fn clean_setup_entries(entries: Vec<String>) -> Vec<String> {
-    let mut seen = HashSet::new();
-    entries
-        .into_iter()
-        .map(|entry| entry.trim().to_string())
-        .filter(|entry| !entry.is_empty())
-        .filter(|entry| seen.insert(entry.to_lowercase()))
-        .collect()
-}
-
-fn clean_optional_setup_entry(entry: Option<String>) -> Option<String> {
-    entry
-        .map(|value| value.trim().to_string())
-        .filter(|value| !value.is_empty())
-}
-
-fn clamp_decision_mirror_weights(mut weights: DecisionMirrorWeights) -> DecisionMirrorWeights {
-    weights.notes_weight = clamp_weight(weights.notes_weight);
-    weights.approved_records_weight = clamp_weight(weights.approved_records_weight);
-    weights.candidate_records_weight = clamp_weight(weights.candidate_records_weight);
-    weights.constitution_weight = clamp_weight(weights.constitution_weight);
-    weights.action_gaps_weight = clamp_weight(weights.action_gaps_weight);
-    weights.recency_weight = clamp_weight(weights.recency_weight);
-    weights.evidence_count_weight = clamp_weight(weights.evidence_count_weight);
-    weights.outcome_history_weight = clamp_weight(weights.outcome_history_weight);
-    weights.contradiction_weight = clamp_weight(weights.contradiction_weight);
-    weights.breadth_weight = clamp_weight(weights.breadth_weight);
-    weights.depth_weight = clamp_weight(weights.depth_weight);
-    weights.evidence_grounding_weight = clamp_weight(weights.evidence_grounding_weight);
-    weights.blind_spot_weight = clamp_weight(weights.blind_spot_weight);
-    weights.counter_position_weight = clamp_weight(weights.counter_position_weight);
-    weights.actionability_weight = clamp_weight(weights.actionability_weight);
-    weights.uncertainty_weight = clamp_weight(weights.uncertainty_weight);
-    weights.privacy_weight = clamp_weight(weights.privacy_weight);
-    weights.unsupported_penalty_weight = clamp_weight(weights.unsupported_penalty_weight);
-    weights
-}
-
-fn clamp_weight(weight: f32) -> f32 {
-    if weight.is_finite() {
-        weight.clamp(0.0, 3.0)
-    } else {
-        1.0
-    }
-}
-
-fn constitution_key(dimension: &str, claim: &str) -> String {
-    format!(
-        "{}::{}",
-        dimension.trim().to_lowercase(),
-        normalize_key_text(claim)
-    )
-}
-
-fn action_gap_key(stated_value: &str, revealed_behavior: &str) -> String {
-    format!(
-        "{}::{}",
-        normalize_key_text(stated_value),
-        normalize_key_text(revealed_behavior)
-    )
-}
-
-fn normalize_key_text(text: &str) -> String {
-    text.split_whitespace()
-        .collect::<Vec<_>>()
-        .join(" ")
-        .to_lowercase()
-}
-
-fn constitution_allows_record(record: &UserRecord) -> bool {
-    !matches!(
-        record.promotion_state,
-        PromotionState::Rejected | PromotionState::Private | PromotionState::NoTrain
-    ) && record.kind != UserRecordKind::Fact
-}
-
-fn behavior_event_for_constitution(event_type: &TraceEventType) -> bool {
-    matches!(
-        event_type,
-        TraceEventType::PromptSubmitted
-            | TraceEventType::FeedbackRecorded
-            | TraceEventType::RankingRecorded
-            | TraceEventType::InsightCaptured
-            | TraceEventType::DebateStarted
-            | TraceEventType::DebateContinued
-            | TraceEventType::NoteExported
-            | TraceEventType::NoteCanonicalPromoted
-            | TraceEventType::DecisionEpisodeCreated
-            | TraceEventType::OutcomeFollowUpRecorded
-    )
-}
-
-fn constitution_status_from_record(record: &UserRecord) -> ConstitutionStatus {
-    let support_count = record.evidence_refs.len();
-    match record.promotion_state {
-        PromotionState::AutoPromoted | PromotionState::Endorsed
-            if support_count >= AUTO_PROMOTE_SUPPORT_COUNT =>
-        {
-            ConstitutionStatus::Active
-        }
-        _ => ConstitutionStatus::Candidate,
+        let content = std::fs::read_to_string(&self.setup_path).with_context(|| {
+            format!(
+                "Failed to read constitution setup file: {}",
+                self.setup_path.display()
+            )
+        })?;
+        serde_json::from_str(&content).with_context(|| {
+            format!(
+                "Failed to parse constitution setup file: {}",
+                self.setup_path.display()
+            )
+        })
     }
-}
 
-fn constitution_context_allowed(status: &ConstitutionStatus) -> bool {
-    matches!(
-        status,
-        ConstitutionStatus::Active | ConstitutionStatus::Candidate | ConstitutionStatus::Softened
-    )
-}
+    pub fn save_constitution_setup(
+        &mut self,
+        mut setup: ConstitutionSetup,
+    ) -> Result<ConstitutionSetup> {
+        setup.twin_name = clean_optional_setup_entry(setup.twin_name);
+        setup.twin_role = clean_optional_setup_entry(setup.twin_role);
+        setup.source_boundaries = clean_setup_entries(setup.source_boundaries);
+        setup.values = clean_setup_entries(setup.values);
+        setup.tastes = clean_setup_entries(setup.tastes);
+        setup.constraints = clean_setup_entries(setup.constraints);
+        setup.somatic_cues = clean_setup_entries(setup.somatic_cues);
+        setup.action_tendencies = clean_setup_entries(setup.action_tendencies);
+        setup.updated_at = Some(Utc::now());
+        self.write_pretty_json(&self.setup_path, &setup)?;
 
-fn constitution_status_for_action(action: &MemoryDigestAction) -> ConstitutionStatus {
-    match action {
-        MemoryDigestAction::Keep => ConstitutionStatus::Active,
-        MemoryDigestAction::Soften => ConstitutionStatus::Softened,
-        MemoryDigestAction::NotMe => ConstitutionStatus::NotMe,
-        MemoryDigestAction::Private => ConstitutionStatus::Private,
-        MemoryDigestAction::NoTrain => ConstitutionStatus::NoTrain,
-        MemoryDigestAction::Reject => ConstitutionStatus::Rejected,
-    }
-}
+        let event = self.append_trace_event(
+            "constitution-setup",
+            TraceEventType::ConstitutionSetupSaved,
+            json!({
+                "twin_name": setup.twin_name,
+                "twin_role": setup.twin_role,
+                "source_boundaries": setup.source_boundaries,
+                "values": setup.values,
+                "tastes": setup.tastes,
+                "constraints": setup.constraints,
+                "somatic_cues": setup.somatic_cues,
+                "action_tendencies": setup.action_tendencies,
+            }),
+        )?;
+        let evidence_ref = EvidenceRef {
+            trace_id: "constitution-setup".to_string(),
+            event_id: event.id,
+            session_id: "constitution-setup".to_string(),
+            tile_id: None,
+            model_id: None,
+            note: Some("Guided Twin setup".to_string()),
+            source_type: Some("setup".to_string()),
+            source_id: Some("constitution-setup".to_string()),
+            source_label: Some("Guided Twin setup".to_string()),
+            excerpt: None,
+            speaker_role: None,
+        };
 
-fn constitution_status_sort_key(status: &ConstitutionStatus) -> u8 {
-    match status {
-        ConstitutionStatus::Active => 0,
-        ConstitutionStatus::Candidate => 1,
-        ConstitutionStatus::Softened => 2,
-        ConstitutionStatus::NotMe => 3,
-        ConstitutionStatus::Private => 4,
-        ConstitutionStatus::NoTrain => 5,
-        ConstitutionStatus::Rejected => 6,
+        self.seed_constitution_setup_items(&setup, evidence_ref)?;
+        Ok(setup)
     }
-}
 
-fn promotion_state_label(state: &PromotionState) -> &'static str {
-    match state {
-        PromotionState::Candidate => "Candidate",
-        PromotionState::AutoPromoted => "Auto-promoted",
-        PromotionState::Endorsed => "Endorsed",
-        PromotionState::Rejected => "Rejected",
-        PromotionState::Private => "Private",
-        PromotionState::NoTrain => "No-train",
+    pub fn run_constitution_inference(&mut self) -> Result<ConstitutionInferenceSummary> {
+        self.run_constitution_inference_with_notes(&[])
     }
-}
 
-fn infer_constitution_dimension(content: &str, kind: &UserRecordKind) -> String {
-    let lower = content.to_lowercase();
-    if text_contains_any(&lower, &["taste", "aesthetic", "style", "design", "feel"]) {
-        "taste".to_string()
-    } else if text_contains_any(
-        &lower,
-        &["constraint", "deadline", "budget", "time", "cost"],
-    ) {
-        "constraints".to_string()
-    } else if text_contains_any(&lower, &["somatic", "gut", "body", "energy", "fatigue"]) {
-        "somatic".to_string()
-    } else if text_contains_any(&lower, &["value", "principle", "mission", "care about"]) {
-        "values".to_string()
-    } else {
-        match kind {
-            UserRecordKind::Preference => "preferences".to_string(),
-            UserRecordKind::ReasoningPattern => "reasoning".to_string(),
-            UserRecordKind::Fact => "facts".to_string(),
+    pub fn run_constitution_inference_with_notes(
+        &mut self,
+        notes: &[Note],
+    ) -> Result<ConstitutionInferenceSummary> {
+        self.ensure_record_cache()?;
+        let current_note_ids = notes
+            .iter()
+            .map(|note| note.id.clone())
+            .collect::<HashSet<_>>();
+        let pruned_stale_records = self.prune_stale_note_records(&current_note_ids)?;
+        let distilled_setup = distill_constitution_setup_from_notes(notes);
+        let updated_setup_entries = constitution_setup_entry_count(&distilled_setup);
+        let pruned_stale_constitution_items = self
+            .prune_stale_note_constitution_items(&current_note_ids)?
+            + self.prune_stale_setup_constitution_items(&distilled_setup)?;
+        if updated_setup_entries > 0 || self.setup_path.exists() {
+            self.write_auto_constitution_setup(distilled_setup.clone())?;
         }
-    }
-}
-
-fn note_is_interview(note: &Note) -> bool {
-    note.properties
-        .get("source_type")
-        .or_else(|| note.properties.get("source"))
-        .and_then(Value::as_str)
-        .is_some_and(|value| value.eq_ignore_ascii_case("interview"))
-        || note
-            .tags
+        self.ensure_record_cache()?;
+        let records = self
+            .record_cache
+            .values()
+            .filter(|record| constitution_allows_record(record))
+            .cloned()
+            .collect::<Vec<_>>();
+        let traces = self.list_session_traces()?;
+        let scanned_behavior_events = traces
             .iter()
-            .any(|tag| tag.eq_ignore_ascii_case("interview"))
-}
-
-#[derive(Debug, Clone)]
-struct InterviewTurn {
-    role: String,
-    content: String,
-}
+            .flat_map(|trace| trace.events.iter())
+            .filter(|event| behavior_event_for_constitution(&event.event_type))
+            .count();
+        let decisions = self.list_decision_episodes()?;
+        let existing_items = self.list_constitution_items()?;
+        let existing_gaps = self.list_action_gaps()?;
+        let mut item_keys = existing_items
+            .iter()
+            .map(|item| constitution_key(&item.dimension, &item.claim))
+            .collect::<HashSet<_>>();
+        let mut gap_keys = existing_gaps
+            .iter()
+            .map(|gap| action_gap_key(&gap.stated_value, &gap.revealed_behavior))
+            .collect::<HashSet<_>>();
 
-enum InterviewExtraction {
-    Unlabeled,
-    Labeled {
-        interviewer_turns: Vec<InterviewTurn>,
-        interviewee_turns: Vec<InterviewTurn>,
-    },
-}
+        let mut created_constitution_items = 0_usize;
+        let mut created_action_gaps = 0_usize;
+        let mut auto_active_items = 0_usize;
+        let mut review_candidate_items = 0_usize;
+        let mut skipped_domain_claims = 0_usize;
+        let mut extracted_research_findings = 0_usize;
 
-fn extract_interview_note_evidence(note: &Note) -> InterviewExtraction {
-    let turns = extract_markdown_interview_turns(&note.content)
-        .or_else(|| extract_colon_labeled_interview_turns(&note.content));
-    let Some(turns) = turns else {
-        return InterviewExtraction::Unlabeled;
-    };
-    let interviewer_turns = turns
-        .iter()
-        .filter(|turn| turn.role == "user")
-        .cloned()
-        .collect::<Vec<_>>();
-    let interviewee_turns = turns
-        .into_iter()
-        .filter(|turn| turn.role == "interviewee")
-        .collect::<Vec<_>>();
-    if interviewer_turns.is_empty() || interviewee_turns.is_empty() {
-        return InterviewExtraction::Unlabeled;
-    }
-    InterviewExtraction::Labeled {
-        interviewer_turns,
-        interviewee_turns,
-    }
-}
+        for record in &records {
+            let dimension = infer_constitution_dimension(&record.content, &record.kind);
+            let claim = record.content.trim().to_string();
+            if claim.is_empty() {
+                continue;
+            }
+            let key = constitution_key(&dimension, &claim);
+            if item_keys.insert(key) {
+                let status = constitution_status_from_record(record);
+                if status == ConstitutionStatus::Active {
+                    auto_active_items += 1;
+                } else if status == ConstitutionStatus::Candidate {
+                    review_candidate_items += 1;
+                }
+                let source = if record.origin == RecordOrigin::Inferred {
+                    "behavior_inference"
+                } else {
+                    "constitution_inference"
+                };
+                self.create_constitution_item(ConstitutionItemCreate {
+                    claim,
+                    dimension,
+                    scope: vec!["general".to_string()],
+                    priority: record.confidence,
+                    confidence: record.confidence,
+                    status,
+                    evidence_refs: record.evidence_refs.clone(),
+                    tensions: Vec::new(),
+                    linked_record_ids: vec![record.id.clone()],
+                    source: Some(source.to_string()),
+                })?;
+                created_constitution_items += 1;
+            }
 
-fn extract_markdown_interview_turns(content: &str) -> Option<Vec<InterviewTurn>> {
-    let mut turns = Vec::new();
-    let mut current_role: Option<String> = None;
-    let mut current_content = String::new();
-    for line in content.lines() {
-        let trimmed = line.trim();
-        if let Some(role) = markdown_message_role(trimmed) {
-            flush_interview_turn(&mut turns, &mut current_role, &mut current_content);
-            current_role = Some(role);
-            continue;
+            if let Some((stated_value, revealed_behavior)) = split_action_gap_claim(&record.content)
+            {
+                let key = action_gap_key(&stated_value, &revealed_behavior);
+                if gap_keys.insert(key) {
+                    self.create_action_gap(ActionGapCreate {
+                        stated_value,
+                        revealed_behavior,
+                        driver_hypothesis: Some(
+                            "Inferred from a contradiction-style user record".to_string(),
+                        ),
+                        somatic_taste_signal: None,
+                        decision_risk:
+                            "The user's endorsed intent may diverge from what they repeatedly do."
+                                .to_string(),
+                        evidence_refs: record.evidence_refs.clone(),
+                        linked_record_ids: vec![record.id.clone()],
+                        confidence: record.confidence,
+                        status: ConstitutionStatus::Candidate,
+                    })?;
+                    created_action_gaps += 1;
+                }
+            }
         }
-        if current_role.is_some() {
-            current_content.push_str(line);
-            current_content.push('\n');
+
+        for decision in &decisions {
+            let Some(initial_leaning) = decision.initial_leaning.as_ref() else {
+                continue;
+            };
+            let Some(chosen_option) = decision.chosen_option.as_ref() else {
+                continue;
+            };
+            if initial_leaning
+                .trim()
+                .eq_ignore_ascii_case(chosen_option.trim())
+            {
+                continue;
+            }
+            let stated_value = format!("Initial leaning: {}", initial_leaning.trim());
+            let revealed_behavior = format!("Chosen option: {}", chosen_option.trim());
+            let key = action_gap_key(&stated_value, &revealed_behavior);
+            if gap_keys.insert(key) {
+                self.create_action_gap(ActionGapCreate {
+                    stated_value,
+                    revealed_behavior,
+                    driver_hypothesis: Some("Inferred from a decision where final action diverged from initial leaning.".to_string()),
+                    somatic_taste_signal: decision.primitive_assessment.somatic_signal.clone(),
+                    decision_risk: "Grafyn should check whether future similar decisions repeat this gap.".to_string(),
+                    evidence_refs: self.decision_evidence_refs(&decision.id)?,
+                    linked_record_ids: Vec::new(),
+                    confidence: 0.68,
+                    status: ConstitutionStatus::Candidate,
+                })?;
+                created_action_gaps += 1;
+            }
         }
-    }
-    flush_interview_turn(&mut turns, &mut current_role, &mut current_content);
-    if turns.len() >= 2 {
-        Some(turns)
-    } else {
-        None
-    }
-}
 
-fn markdown_message_role(line: &str) -> Option<String> {
-    let lower = line.to_lowercase();
-    if !(lower.starts_with("### message") || lower.starts_with("## message")) {
-        return None;
-    }
-    if lower.contains("interviewee") || lower.contains("participant") {
-        Some("interviewee".to_string())
-    } else if lower.contains("user")
-        || lower.contains("interviewer")
-        || lower.contains("researcher")
-    {
-        Some("user".to_string())
-    } else {
-        None
-    }
-}
+        for note in notes {
+            if note_is_interview(note) {
+                match extract_interview_note_evidence(note) {
+                    InterviewExtraction::Unlabeled => {
+                        skipped_domain_claims += 1;
+                    }
+                    InterviewExtraction::Labeled {
+                        interviewer_turns,
+                        interviewee_turns,
+                    } => {
+                        for turn in interviewer_turns {
+                            if let Some((dimension, claim)) =
+                                constitution_claim_from_interviewer_turn(&turn.content)
+                            {
+                                let key = constitution_key(&dimension, &claim);
+                                if item_keys.insert(key) {
+                                    self.create_constitution_item(ConstitutionItemCreate {
+                                        claim,
+                                        dimension,
+                                        scope: vec!["interview".to_string()],
+                                        priority: 0.62,
+                                        confidence: 0.62,
+                                        status: ConstitutionStatus::Candidate,
+                                        evidence_refs: vec![note_evidence_ref(
+                                            note,
+                                            "interview-question",
+                                            "Interviewer question",
+                                            Some("user"),
+                                            &turn.content,
+                                        )],
+                                        tensions: Vec::new(),
+                                        linked_record_ids: Vec::new(),
+                                        source: Some("interview_behavior_inference".to_string()),
+                                    })?;
+                                    created_constitution_items += 1;
+                                    review_candidate_items += 1;
+                                }
+                            }
+                        }
+                        for turn in interviewee_turns {
+                            if !looks_like_research_finding(&turn.content) {
+                                skipped_domain_claims += 1;
+                                continue;
+                            }
+                            if self.create_interview_research_record(note, &turn.content)? {
+                                extracted_research_findings += 1;
+                            }
+                        }
+                    }
+                }
+                continue;
+            }
 
-fn extract_colon_labeled_interview_turns(content: &str) -> Option<Vec<InterviewTurn>> {
-    let mut turns = Vec::new();
-    for line in content.lines() {
-        let Some((speaker, body)) = line.split_once(':') else {
-            continue;
-        };
-        let speaker = speaker.trim().to_lowercase();
-        let role = match speaker.as_str() {
-            "interviewer" | "researcher" | "moderator" | "facilitator" | "me" | "user" => "user",
-            "interviewee" | "participant" | "respondent" | "customer" | "student" | "teacher" => {
-                "interviewee"
+            if let Some((dimension, claim)) = constitution_claim_from_note(note) {
+                let key = constitution_key(&dimension, &claim);
+                if item_keys.insert(key) {
+                    self.create_constitution_item(ConstitutionItemCreate {
+                        claim,
+                        dimension,
+                        scope: vec!["note".to_string()],
+                        priority: 0.58,
+                        confidence: 0.58,
+                        status: ConstitutionStatus::Candidate,
+                        evidence_refs: vec![note_evidence_ref(
+                            note,
+                            "note",
+                            "Vault note",
+                            Some("user"),
+                            &note.content,
+                        )],
+                        tensions: Vec::new(),
+                        linked_record_ids: Vec::new(),
+                        source: Some("note_inference".to_string()),
+                    })?;
+                    created_constitution_items += 1;
+                    review_candidate_items += 1;
+                }
+            } else {
+                skipped_domain_claims += 1;
             }
-            _ => continue,
-        };
-        let content = body.trim();
-        if !content.is_empty() {
-            turns.push(InterviewTurn {
-                role: role.to_string(),
-                content: content.to_string(),
-            });
         }
-    }
-    if turns.len() >= 2 {
-        Some(turns)
-    } else {
-        None
-    }
-}
-
-fn flush_interview_turn(
-    turns: &mut Vec<InterviewTurn>,
-    current_role: &mut Option<String>,
-    current_content: &mut String,
-) {
-    let Some(role) = current_role.take() else {
-        return;
-    };
-    let content = current_content.trim().to_string();
-    current_content.clear();
-    if content.is_empty() {
-        return;
-    }
-    turns.push(InterviewTurn { role, content });
-}
 
-fn constitution_claim_from_interviewer_turn(content: &str) -> Option<(String, String)> {
-    let lower = content.to_lowercase();
-    if text_contains_any(
-        &lower,
-        &[
-            "concrete example",
-            "compare",
-            "why",
-            "how do you",
-            "what makes",
-            "walk me through",
-        ],
-    ) {
-        return Some((
-            "reasoning".to_string(),
-            "Uses interview questions to probe for concrete examples and comparisons before treating claims as useful.".to_string(),
-        ));
+        let summary = ConstitutionInferenceSummary {
+            scanned_records: records.len(),
+            scanned_decisions: decisions.len(),
+            created_constitution_items,
+            created_action_gaps,
+            scanned_behavior_events,
+            scanned_notes: notes.len(),
+            scanned_interviews: notes.iter().filter(|note| note_is_interview(note)).count(),
+            auto_active_items,
+            review_candidate_items,
+            skipped_domain_claims,
+            extracted_research_findings,
+            pruned_stale_constitution_items,
+            pruned_stale_records,
+            updated_setup_entries,
+            generated_at: Utc::now(),
+        };
+        self.append_trace_event(
+            "constitution-inference",
+            TraceEventType::ConstitutionInferenceRun,
+            serde_json::to_value(&summary)?,
+        )?;
+        Ok(summary)
     }
-    None
-}
 
-fn looks_like_research_finding(content: &str) -> bool {
-    content.split_whitespace().count() >= 8
-        && text_contains_any(
-            content,
-            &[
-                "need", "want", "trust", "frustrat", "prefer", "hard", "easy", "useful", "demo",
-                "workflow",
-            ],
-        )
-}
-
-fn constitution_claim_from_note(note: &Note) -> Option<(String, String)> {
-    if note.is_topic_hub() {
-        return None;
-    }
-    let content = note.content.trim();
-    if content.len() < 24 {
-        return None;
-    }
-    let lower = content.to_lowercase();
-    if !text_contains_any(
-        &lower,
-        &[
-            "i prefer",
-            "i need",
-            "i value",
-            "my reasoning",
-            "works for me",
-            "not me",
-            "i reject",
-            "i decide",
-        ],
-    ) {
-        return None;
-    }
-    if text_contains_any(&lower, &["prefer"]) {
-        Some((
-            "preferences".to_string(),
-            format!("Note-backed preference: {}", excerpt(content)),
-        ))
-    } else {
-        Some((
-            "reasoning".to_string(),
-            format!("Note-backed reasoning pattern: {}", excerpt(content)),
-        ))
+    fn create_interview_research_record(&mut self, note: &Note, content: &str) -> Result<bool> {
+        self.ensure_record_cache()?;
+        let finding = format!("Interview finding: {}", excerpt(content.trim()));
+        let existing = self.record_cache.values().any(|record| {
+            record.kind == UserRecordKind::Fact
+                && record.content == finding
+                && record.metadata.get("source_type").and_then(Value::as_str)
+                    == Some("interview_answer")
+        });
+        if existing {
+            return Ok(false);
+        }
+
+        self.create_user_record(UserRecordCreate {
+            kind: UserRecordKind::Fact,
+            content: finding,
+            evidence_refs: vec![note_evidence_ref(
+                note,
+                "interview-answer",
+                "Interviewee answer",
+                Some("interviewee"),
+                content,
+            )],
+            confidence: 0.66,
+            origin: RecordOrigin::Inferred,
+            promotion_state: Some(PromotionState::Candidate),
+            valid_from: None,
+            valid_until: None,
+            links: Vec::new(),
+            metadata: HashMap::from([
+                ("source_type".to_string(), json!("interview_answer")),
+                ("source_note_id".to_string(), json!(note.id.clone())),
+            ]),
+        })?;
+        Ok(true)
     }
-}
 
-fn note_evidence_ref(
-    note: &Note,
-    source_type: &str,
-    source_label: &str,
-    speaker_role: Option<&str>,
-    content: &str,
-) -> EvidenceRef {
-    EvidenceRef {
-        trace_id: format!("note-{}", note.id),
-        event_id: note.id.clone(),
-        session_id: "vault-note".to_string(),
-        tile_id: None,
-        model_id: None,
-        note: Some(note.title.clone()),
-        source_type: Some(source_type.to_string()),
-        source_id: Some(note.id.clone()),
-        source_label: Some(source_label.to_string()),
-        excerpt: Some(excerpt(content.trim())),
-        speaker_role: speaker_role.map(ToOwned::to_owned),
+    fn write_auto_constitution_setup(&self, mut setup: ConstitutionSetup) -> Result<()> {
+        if let Ok(existing) = self.get_constitution_setup() {
+            setup.twin_name = existing.twin_name;
+            setup.twin_role = existing.twin_role;
+            setup.source_boundaries = existing.source_boundaries;
+        }
+        setup.twin_name = clean_optional_setup_entry(setup.twin_name);
+        setup.twin_role = clean_optional_setup_entry(setup.twin_role);
+        setup.source_boundaries = clean_setup_entries(setup.source_boundaries);
+        setup.values = clean_setup_entries(setup.values);
+        setup.tastes = clean_setup_entries(setup.tastes);
+        setup.constraints = clean_setup_entries(setup.constraints);
+        setup.somatic_cues = clean_setup_entries(setup.somatic_cues);
+        setup.action_tendencies = clean_setup_entries(setup.action_tendencies);
+        setup.updated_at = Some(Utc::now());
+        self.write_pretty_json(&self.setup_path, &setup)
     }
-}
 
-fn distill_constitution_setup_from_notes(notes: &[Note]) -> ConstitutionSetup {
-    let mut setup = ConstitutionSetup::default();
-    let mut saw_interview_question = false;
-    let mut saw_values_question = false;
-    let mut saw_tradeoff_question = false;
-    let mut saw_risk_question = false;
-    let mut saw_concrete_question = false;
-    let mut saw_followup_question = false;
-    let mut saw_user_note_preference = false;
-    let mut interviewer_question_count = 0_usize;
+    fn prune_stale_note_records(&mut self, current_note_ids: &HashSet<String>) -> Result<usize> {
+        self.ensure_record_cache()?;
+        let stale_ids = self
+            .record_cache
+            .values()
+            .filter(|record| record_is_vault_derived(record))
+            .filter(|record| {
+                record
+                    .metadata
+                    .get("source_note_id")
+                    .and_then(Value::as_str)
+                    .is_some_and(|source_note_id| !current_note_ids.contains(source_note_id))
+            })
+            .map(|record| record.id.clone())
+            .collect::<Vec<_>>();
 
-    for note in notes {
-        if note.is_topic_hub() {
-            continue;
+        for id in &stale_ids {
+            self.record_cache.remove(id);
+            let path = self.records_path.join(format!("{}.json", id));
+            if path.exists() {
+                std::fs::remove_file(&path).with_context(|| {
+                    format!("Failed to remove stale Twin record: {}", path.display())
+                })?;
+            }
         }
 
-        if note_is_interview(note) {
-            if let InterviewExtraction::Labeled {
-                interviewer_turns, ..
-            } = extract_interview_note_evidence(note)
-            {
-                for turn in interviewer_turns {
-                    let lower = turn.content.to_lowercase();
-                    if turn.content.split_whitespace().count() < 5 {
-                        continue;
-                    }
-                    saw_interview_question = true;
-                    interviewer_question_count += 1;
-                    if text_contains_any(&lower, &["value", "cultural", "drives your decision"]) {
-                        saw_values_question = true;
-                    }
-                    if text_contains_any(&lower, &["trade off", "trade-off", "balance"]) {
-                        saw_tradeoff_question = true;
-                    }
-                    if text_contains_any(&lower, &["risk", "comfortable taking", "actively avoid"])
-                    {
-                        saw_risk_question = true;
-                    }
-                    if text_contains_any(
-                        &lower,
-                        &[
-                            "example",
-                            "walk us through",
-                            "walk through",
-                            "concrete",
-                            "top two",
-                        ],
-                    ) {
-                        saw_concrete_question = true;
-                    }
-                    if text_contains_any(
-                        &lower,
-                        &["following up", "if i understand", "drill", "how would"],
-                    ) {
-                        saw_followup_question = true;
-                    }
-                }
+        Ok(stale_ids.len())
+    }
+
+    fn prune_stale_note_constitution_items(
+        &self,
+        current_note_ids: &HashSet<String>,
+    ) -> Result<usize> {
+        let stale_items = self
+            .list_constitution_items()?
+            .into_iter()
+            .filter(|item| constitution_item_is_vault_derived(item))
+            .filter(|item| {
+                item.evidence_refs
+                    .iter()
+                    .filter_map(|evidence| evidence.source_id.as_deref())
+                    .any(|source_id| !current_note_ids.contains(source_id))
+            })
+            .collect::<Vec<_>>();
+
+        for item in &stale_items {
+            let path = self.constitution_path.join(format!("{}.json", item.id));
+            if path.exists() {
+                std::fs::remove_file(&path).with_context(|| {
+                    format!(
+                        "Failed to remove stale Constitution item: {}",
+                        path.display()
+                    )
+                })?;
             }
-            continue;
         }
 
-        if let Some((dimension, claim)) = constitution_claim_from_note(note) {
-            saw_user_note_preference = true;
-            match dimension.as_str() {
-                "preferences" => push_unique(&mut setup.tastes, claim),
-                "constraints" => push_unique(&mut setup.constraints, claim),
-                "action_tendency" => push_unique(&mut setup.action_tendencies, claim),
-                _ => push_unique(&mut setup.values, claim),
+        Ok(stale_items.len())
+    }
+
+    fn prune_stale_setup_constitution_items(&self, setup: &ConstitutionSetup) -> Result<usize> {
+        let setup_claims = constitution_setup_claims(setup);
+        let stale_items = self
+            .list_constitution_items()?
+            .into_iter()
+            .filter(|item| item.source.as_deref() == Some("guided_setup"))
+            .filter(|item| !setup_claims.contains(item.claim.trim()))
+            .collect::<Vec<_>>();
+
+        for item in &stale_items {
+            let path = self.constitution_path.join(format!("{}.json", item.id));
+            if path.exists() {
+                std::fs::remove_file(&path).with_context(|| {
+                    format!(
+                        "Failed to remove stale setup Constitution item: {}",
+                        path.display()
+                    )
+                })?;
             }
         }
-    }
 
-    if saw_interview_question {
-        push_unique(
-            &mut setup.constraints,
-            "Keeps interviewee answers as research evidence rather than treating them as the user's own Constitution.".to_string(),
-        );
-        push_unique(
-            &mut setup.constraints,
-            "Requires speaker-labelled evidence before extracting Constitution or research findings.".to_string(),
-        );
-    }
-    if saw_values_question {
-        push_unique(
-            &mut setup.values,
-            "Probes for the values and cultural assumptions behind decisions, not only the visible decision outcome.".to_string(),
-        );
-    }
-    if saw_tradeoff_question {
-        push_unique(
-            &mut setup.values,
-            "Treats important choices as tradeoffs between innovation, stability, impact, and institutional responsibility.".to_string(),
-        );
-    }
-    if saw_risk_question {
-        push_unique(
-            &mut setup.constraints,
-            "Separates acceptable experiments from risks that harm people, courses, or institutional trust.".to_string(),
-        );
-    }
-    if saw_concrete_question {
-        push_unique(
-            &mut setup.tastes,
-            "Prefers concrete walkthroughs, examples, and decision stories over abstract positioning.".to_string(),
-        );
+        Ok(stale_items.len())
     }
-    if saw_followup_question || (interviewer_question_count > 1 && saw_concrete_question) {
-        push_unique(
-            &mut setup.action_tendencies,
-            "Uses follow-up questions to move from broad narrative into specific decisions, assumptions, criteria, and consequences.".to_string(),
-        );
+
+    pub fn select_constitution_context(
+        &self,
+        query: &str,
+    ) -> Result<(Vec<ConstitutionItem>, Vec<ActionGap>)> {
+        let query_terms = lexical_terms(query);
+        let mut items = self
+            .list_constitution_items()?
+            .into_iter()
+            .filter(|item| constitution_context_allowed(&item.status))
+            .map(|item| (constitution_item_relevance(&item, &query_terms), item))
+            .filter(|(score, item)| *score > 0 || item.status == ConstitutionStatus::Active)
+            .collect::<Vec<_>>();
+        items.sort_by(|a, b| {
+            b.0.cmp(&a.0)
+                .then_with(|| {
+                    b.1.priority
+                        .partial_cmp(&a.1.priority)
+                        .unwrap_or(std::cmp::Ordering::Equal)
+                })
+                .then_with(|| b.1.updated_at.cmp(&a.1.updated_at))
+        });
+
+        let mut gaps = self
+            .list_action_gaps()?
+            .into_iter()
+            .filter(|gap| constitution_context_allowed(&gap.status))
+            .map(|gap| (action_gap_relevance(&gap, &query_terms), gap))
+            .filter(|(score, gap)| *score > 0 || gap.status == ConstitutionStatus::Active)
+            .collect::<Vec<_>>();
+        gaps.sort_by(|a, b| {
+            b.0.cmp(&a.0)
+                .then_with(|| {
+                    b.1.confidence
+                        .partial_cmp(&a.1.confidence)
+                        .unwrap_or(std::cmp::Ordering::Equal)
+                })
+                .then_with(|| b.1.updated_at.cmp(&a.1.updated_at))
+        });
+
+        Ok((
+            items.into_iter().take(8).map(|(_, item)| item).collect(),
+            gaps.into_iter().take(4).map(|(_, gap)| gap).collect(),
+        ))
     }
-    if saw_user_note_preference {
-        push_unique(
-            &mut setup.action_tendencies,
-            "Turns user-authored note evidence into reviewable Constitution candidates instead of accepting it silently.".to_string(),
-        );
+
+    fn constitution_file_path(&self, item_id: &str) -> PathBuf {
+        self.constitution_path.join(format!("{}.json", item_id))
     }
 
-    setup
-}
+    fn action_gap_file_path(&self, gap_id: &str) -> PathBuf {
+        self.action_gaps_path.join(format!("{}.json", gap_id))
+    }
 
-fn constitution_setup_entry_count(setup: &ConstitutionSetup) -> usize {
-    setup.values.len()
-        + setup.tastes.len()
-        + setup.constraints.len()
-        + setup.somatic_cues.len()
-        + setup.action_tendencies.len()
-}
+    fn read_constitution_file(&self, path: &Path) -> Result<ConstitutionItem> {
+        let content = std::fs::read_to_string(path)
+            .with_context(|| format!("Failed to read constitution file: {}", path.display()))?;
+        serde_json::from_str(&content)
+            .with_context(|| format!("Failed to parse constitution file: {}", path.display()))
+    }
 
-fn constitution_setup_claims(setup: &ConstitutionSetup) -> HashSet<String> {
-    setup
-        .values
-        .iter()
-        .chain(setup.tastes.iter())
-        .chain(setup.constraints.iter())
-        .chain(setup.somatic_cues.iter())
-        .chain(setup.action_tendencies.iter())
-        .map(|entry| entry.trim().to_string())
-        .filter(|entry| !entry.is_empty())
-        .collect()
-}
+    fn read_action_gap_file(&self, path: &Path) -> Result<ActionGap> {
+        let content = std::fs::read_to_string(path)
+            .with_context(|| format!("Failed to read action gap file: {}", path.display()))?;
+        serde_json::from_str(&content)
+            .with_context(|| format!("Failed to parse action gap file: {}", path.display()))
+    }
 
-fn push_unique(entries: &mut Vec<String>, entry: String) {
-    let normalized = entry.trim();
-    if normalized.is_empty() {
-        return;
+    fn write_constitution_file(&self, item: &ConstitutionItem) -> Result<()> {
+        let path = self.constitution_file_path(&item.id);
+        self.write_pretty_json(&path, item)
     }
-    if !entries
-        .iter()
-        .any(|existing| existing.eq_ignore_ascii_case(normalized))
-    {
-        entries.push(normalized.to_string());
+
+    fn write_action_gap_file(&self, gap: &ActionGap) -> Result<()> {
+        let path = self.action_gap_file_path(&gap.id);
+        self.write_pretty_json(&path, gap)
     }
-}
 
-fn constitution_item_is_vault_derived(item: &ConstitutionItem) -> bool {
-    matches!(
-        item.source.as_deref(),
-        Some("note_inference")
-            | Some("interview_behavior_inference")
-            | Some("interview_research_inference")
-    ) || item.evidence_refs.iter().any(|evidence| {
-        matches!(
-            evidence.source_type.as_deref(),
-            Some("note") | Some("interview-question") | Some("interview-answer")
-        )
-    })
-}
+    fn seed_constitution_setup_items(
+        &self,
+        setup: &ConstitutionSetup,
+        evidence_ref: EvidenceRef,
+    ) -> Result<()> {
+        let existing_keys = self
+            .list_constitution_items()?
+            .into_iter()
+            .map(|item| constitution_key(&item.dimension, &item.claim))
+            .collect::<HashSet<_>>();
+        let mut created_keys = existing_keys;
 
-fn record_is_vault_derived(record: &UserRecord) -> bool {
-    record.metadata.get("source_note_id").is_some()
-        || matches!(
-            record.metadata.get("source_type").and_then(Value::as_str),
-            Some("interview_answer") | Some("note")
-        )
-        || record.evidence_refs.iter().any(|evidence| {
-            matches!(
-                evidence.source_type.as_deref(),
-                Some("note") | Some("interview-question") | Some("interview-answer")
-            )
-        })
-}
+        let groups: &[(&str, &[String])] = &[
+            ("values", &setup.values),
+            ("taste", &setup.tastes),
+            ("constraints", &setup.constraints),
+            ("somatic", &setup.somatic_cues),
+            ("action_tendency", &setup.action_tendencies),
+        ];
 
-fn split_action_gap_claim(content: &str) -> Option<(String, String)> {
-    let lowered = content.to_lowercase();
-    for separator in [" but ", " however ", " yet ", " although "] {
-        if let Some(index) = lowered.find(separator) {
-            let left = content[..index].trim();
-            let right = content[index + separator.len()..].trim();
-            if left.len() >= 8 && right.len() >= 8 {
-                return Some((left.to_string(), right.to_string()));
+        for (dimension, entries) in groups {
+            for entry in entries.iter().filter(|entry| !entry.trim().is_empty()) {
+                let claim = entry.trim().to_string();
+                let key = constitution_key(dimension, &claim);
+                if !created_keys.insert(key) {
+                    continue;
+                }
+                self.create_constitution_item(ConstitutionItemCreate {
+                    claim,
+                    dimension: (*dimension).to_string(),
+                    scope: vec!["setup".to_string()],
+                    priority: 0.9,
+                    confidence: 0.9,
+                    status: ConstitutionStatus::Active,
+                    evidence_refs: vec![evidence_ref.clone()],
+                    tensions: Vec::new(),
+                    linked_record_ids: Vec::new(),
+                    source: Some("guided_setup".to_string()),
+                })?;
             }
         }
-    }
-    None
-}
 
-fn constitution_item_relevance(item: &ConstitutionItem, query_terms: &HashSet<String>) -> usize {
-    if query_terms.is_empty() {
-        return 0;
-    }
-    let mut haystack = format!("{} {} {}", item.claim, item.dimension, item.scope.join(" "));
-    for tension in &item.tensions {
-        haystack.push(' ');
-        haystack.push_str(tension);
+        Ok(())
     }
-    let item_terms = lexical_terms(&haystack);
-    query_terms.intersection(&item_terms).count()
-}
 
-fn action_gap_relevance(gap: &ActionGap, query_terms: &HashSet<String>) -> usize {
-    if query_terms.is_empty() {
-        return 0;
-    }
-    let mut haystack = format!(
-        "{} {} {}",
-        gap.stated_value, gap.revealed_behavior, gap.decision_risk
-    );
-    if let Some(driver) = &gap.driver_hypothesis {
-        haystack.push(' ');
-        haystack.push_str(driver);
-    }
-    if let Some(signal) = &gap.somatic_taste_signal {
-        haystack.push(' ');
-        haystack.push_str(signal);
-    }
-    let gap_terms = lexical_terms(&haystack);
-    query_terms.intersection(&gap_terms).count()
-}
+    pub fn get_decision_mirror_config(&self) -> Result<DecisionMirrorConfig> {
+        if !self.decision_mirror_config_path.exists() {
+            return Ok(DecisionMirrorConfig::default());
+        }
 
-fn memory_digest_trigger(record: &UserRecord) -> Option<&'static str> {
-    if record.kind == UserRecordKind::Fact {
-        return None;
+        let content =
+            std::fs::read_to_string(&self.decision_mirror_config_path).with_context(|| {
+                format!(
+                    "Failed to read decision mirror config {}",
+                    self.decision_mirror_config_path.display()
+                )
+            })?;
+        let mut config: DecisionMirrorConfig =
+            serde_json::from_str(&content).context("Failed to parse decision mirror config")?;
+        config.weights = clamp_decision_mirror_weights(config.weights);
+        Ok(config)
     }
 
-    match record.promotion_state {
-        PromotionState::Rejected | PromotionState::Private | PromotionState::NoTrain => None,
-        PromotionState::AutoPromoted
-            if record.evidence_refs.len() >= AUTO_PROMOTE_SUPPORT_COUNT =>
-        {
-            Some("3+ evidence points support this durable pattern")
-        }
-        PromotionState::Candidate if record.evidence_refs.len() >= AUTO_PROMOTE_SUPPORT_COUNT => {
-            Some("candidate pattern has enough evidence for review")
+    pub fn update_decision_mirror_config(
+        &self,
+        update: DecisionMirrorConfigUpdate,
+    ) -> Result<DecisionMirrorConfig> {
+        let mut config = self.get_decision_mirror_config()?;
+        if let Some(preset) = update.preset {
+            config.weights = DecisionMirrorWeights::for_preset(&preset);
+            config.preset = preset;
         }
-        PromotionState::Candidate
-            if record.confidence >= AUTO_PROMOTE_CONFIDENCE && !record.evidence_refs.is_empty() =>
-        {
-            Some("high-confidence candidate pattern needs review")
+        if let Some(weights) = update.weights {
+            config.weights = clamp_decision_mirror_weights(weights);
         }
-        PromotionState::Endorsed if stale_for_review(record) => {
-            Some("endorsed pattern may be stale")
+        if let Some(advanced_enabled) = update.advanced_enabled {
+            config.advanced_enabled = advanced_enabled;
         }
-        PromotionState::AutoPromoted => None,
-        PromotionState::Endorsed => None,
-        PromotionState::Candidate => None,
-    }
-}
 
-fn memory_digest_cluster_key(record: &UserRecord) -> String {
-    if let Some(signal_family) = record
-        .metadata
-        .get("signal_family")
-        .and_then(Value::as_str)
-        .filter(|value| !value.trim().is_empty())
-    {
-        return format!("{:?}::{}", record.kind, signal_family.trim().to_lowercase());
+        self.write_decision_mirror_config_file(&config)?;
+        Ok(config)
     }
 
-    let mut terms = lexical_terms(&record.content)
-        .into_iter()
-        .collect::<Vec<_>>();
-    terms.sort();
-    terms.truncate(6);
-    if terms.is_empty() {
-        format!("{:?}::{}", record.kind, normalize_key_text(&record.content))
-    } else {
-        format!("{:?}::{}", record.kind, terms.join("-"))
+    pub fn reset_decision_mirror_config(&self) -> Result<DecisionMirrorConfig> {
+        let config = DecisionMirrorConfig::default();
+        self.write_decision_mirror_config_file(&config)?;
+        Ok(config)
     }
-}
 
-fn stable_digest_id(records: &[UserRecord]) -> String {
-    let mut ids = records
-        .iter()
-        .map(|record| record.id.as_str())
-        .collect::<Vec<_>>();
-    ids.sort_unstable();
-    let mut hasher = DefaultHasher::new();
-    ids.hash(&mut hasher);
-    format!("digest-cluster-{:x}", hasher.finish())
-}
+    pub fn record_decision_episode(
+        &mut self,
+        create: DecisionEpisodeCreate,
+    ) -> Result<DecisionEpisode> {
+        Self::validate_file_id(&create.id)?;
+        Self::validate_file_id(&create.session_id)?;
+        Self::validate_file_id(&create.tile_id)?;
 
-fn stale_for_review(record: &UserRecord) -> bool {
-    Utc::now()
-        .signed_duration_since(record.updated_at)
-        .num_days()
-        >= 90
-}
+        let now = Utc::now();
+        // A prediction is only attempted when there are at least two options
+        // to choose between; record why one will not arrive otherwise.
+        let prediction_status = if create.options.len() >= 2 {
+            Some("requested".to_string())
+        } else {
+            None
+        };
+        let episode = DecisionEpisode {
+            id: create.id,
+            session_id: create.session_id,
+            tile_id: create.tile_id,
+            decision: create.decision,
+            options: create.options,
+            stakes: create.stakes,
+            initial_leaning: create.initial_leaning,
+            selected_response: None,
+            chosen_option: None,
+            confidence: None,
+            review_date: create.review_date,
+            outcome: None,
+            regret_score: None,
+            lesson: None,
+            missed_something: None,
+            primitive_assessment: create.primitive_assessment,
+            twin_prediction: None,
+            prediction_status,
+            agreement: None,
+            correction_note: None,
+            context_version: create.context_version,
+            outcome_recorded_at: None,
+            created_at: now,
+            updated_at: now,
+        };
 
-fn digest_state_sort_key(state: &MemoryDigestState) -> u8 {
-    match state {
-        MemoryDigestState::Pending => 0,
-        MemoryDigestState::Softened => 1,
-        MemoryDigestState::Kept => 2,
-        MemoryDigestState::NotMe => 3,
-        MemoryDigestState::Private => 4,
-        MemoryDigestState::NoTrain => 5,
-        MemoryDigestState::Rejected => 6,
-    }
-}
+        self.write_decision_file(&episode)?;
+        self.append_trace_event(
+            &episode.session_id,
+            TraceEventType::DecisionEpisodeCreated,
+            json!({
+                "decision_episode_id": episode.id,
+                "tile_id": episode.tile_id,
+                "decision": episode.decision,
+                "options": episode.options,
+                "stakes": episode.stakes,
+                "initial_leaning": episode.initial_leaning,
+                "review_date": episode.review_date,
+                "primitive_assessment": episode.primitive_assessment,
+            }),
+        )?;
 
-fn memory_digest_state_for_action(action: &MemoryDigestAction) -> MemoryDigestState {
-    match action {
-        MemoryDigestAction::Keep => MemoryDigestState::Kept,
-        MemoryDigestAction::Soften => MemoryDigestState::Softened,
-        MemoryDigestAction::NotMe => MemoryDigestState::NotMe,
-        MemoryDigestAction::Private => MemoryDigestState::Private,
-        MemoryDigestAction::NoTrain => MemoryDigestState::NoTrain,
-        MemoryDigestAction::Reject => MemoryDigestState::Rejected,
+        Ok(episode)
     }
-}
 
-fn score_reflection_card(
-    content: &str,
-    cited_note_ids: &[String],
-    cited_user_record_ids: &[String],
-    cited_constitution_item_ids: &[String],
-    cited_action_gap_ids: &[String],
-    config: &DecisionMirrorConfig,
-) -> ReflectionScores {
-    let lower = content.to_lowercase();
-    let section_checks: &[&[&str]] = &[
-        &["decision frame", "actual decision"],
-        &["reasoning pattern", "likely reasoning", "default pattern"],
-        &["evidence", "vault", "record"],
-        &["blind spot", "missing", "underweighting"],
-        &["counter-position", "counter position", "counterargument"],
-        &["recommendation", "would do next"],
-        &["confidence", "uncertain", "would change my mind"],
-        &["next action", "smallest", "follow-up"],
-    ];
-    let present_sections = section_checks
-        .iter()
-        .filter(|aliases| aliases.iter().any(|alias| lower.contains(alias)))
-        .count();
-    let breadth_score = present_sections as f32 / section_checks.len() as f32;
+    pub fn list_decision_episodes(&self) -> Result<Vec<DecisionEpisode>> {
+        let mut episodes = Vec::new();
+        if !self.decisions_path.exists() {
+            return Ok(episodes);
+        }
 
-    let word_count = content.split_whitespace().count() as f32;
-    let depth_score = ((word_count / 450.0).min(1.0) * 0.5)
-        + (phrase_score(
-            &lower,
-            &[
-                "because",
-                "tradeoff",
-                "evidence",
-                "alternative",
-                "would change",
-                "unsupported",
-            ],
-        ) * 0.5);
+        for entry in WalkDir::new(&self.decisions_path)
+            .min_depth(1)
+            .max_depth(1)
+            .into_iter()
+            .filter_map(|entry| entry.ok())
+        {
+            let path = entry.path();
+            if path.extension().is_some_and(|ext| ext == "json") {
+                if let Some(episode) =
+                    load_or_quarantine::<DecisionEpisode>(path, "decision episode")
+                {
+                    episodes.push(episode);
+                }
+            }
+        }
 
-    let evidence_grounding_score = if !cited_note_ids.is_empty()
-        || !cited_user_record_ids.is_empty()
-        || !cited_constitution_item_ids.is_empty()
-        || !cited_action_gap_ids.is_empty()
-    {
-        1.0
-    } else if lower.contains("evidence")
-        || lower.contains("note")
-        || lower.contains("record")
-        || lower.contains("based on")
-    {
-        0.5
-    } else {
-        0.0
-    };
+        episodes.sort_by(|a, b| b.updated_at.cmp(&a.updated_at));
+        Ok(episodes)
+    }
 
-    let blind_spot_score = phrase_score(
-        &lower,
-        &[
-            "blind spot",
-            "missing",
-            "underweight",
-            "bias",
-            "avoid",
-            "overfit",
-        ],
-    );
-    let actionability_score = phrase_score(
-        &lower,
-        &["next action", "smallest", "experiment", "step", "by "],
-    );
-    let counterargument_score = phrase_score(
-        &lower,
-        &[
-            "counter",
-            "strongest argument",
-            "against",
-            "alternative frame",
-        ],
-    );
-    let uncertainty_score = phrase_score(
-        &lower,
-        &[
-            "hypothesis",
-            "may",
-            "seem",
-            "confidence",
-            "uncertain",
-            "would change",
-        ],
-    );
-    let privacy_score = 1.0;
-    let unsupported_claim_count = unsupported_self_claim_count(
-        &lower,
-        evidence_grounding_score,
-        cited_note_ids,
-        cited_user_record_ids,
-        cited_constitution_item_ids,
-        cited_action_gap_ids,
-    );
-    let (overall_score, weighted_breakdown) = weighted_reflection_score(
-        config,
-        &[
-            ("breadth", breadth_score),
-            ("depth", depth_score.min(1.0)),
-            ("evidence_grounding", evidence_grounding_score),
-            ("blind_spot", blind_spot_score),
-            ("counter_position", counterargument_score),
-            ("actionability", actionability_score),
-            ("uncertainty", uncertainty_score),
-            ("privacy", privacy_score),
-        ],
-        unsupported_claim_count,
-    );
+    /// Select past decided episodes as verbatim behavioral cases for twin
+    /// context. Correction notes (recorded when a sealed prediction missed)
+    /// break ties between equally relevant cases but never outrank a more
+    /// relevant case.
+    pub fn select_decision_cases(
+        &self,
+        query: &str,
+        exclude_episode_id: Option<&str>,
+        max: usize,
+    ) -> Result<Vec<DecisionEpisode>> {
+        if max == 0 {
+            return Ok(Vec::new());
+        }
+
+        let query_terms = lexical_terms(query);
+        let mut scored = Vec::new();
+        let mut fallback = Vec::new();
 
-    ReflectionScores {
-        breadth_score,
-        depth_score: depth_score.min(1.0),
-        evidence_grounding_score,
-        blind_spot_score,
-        actionability_score,
-        counterargument_score,
-        uncertainty_score,
-        privacy_score,
-        unsupported_claim_count,
-        overall_score,
-        weighted_breakdown,
-    }
-}
+        for episode in self.list_decision_episodes()? {
+            if episode.chosen_option.is_none() {
+                continue;
+            }
+            if exclude_episode_id.is_some_and(|id| id == episode.id) {
+                continue;
+            }
+            let score = decision_case_relevance(&episode, &query_terms);
+            if score > 0 {
+                scored.push((score, episode));
+            } else {
+                fallback.push(episode);
+            }
+        }
 
-fn weighted_reflection_score(
-    config: &DecisionMirrorConfig,
-    scores: &[(&str, f32)],
-    unsupported_claim_count: u32,
-) -> (f32, HashMap<String, f32>) {
-    let weights = &config.weights;
-    let weight_for = |key: &str| match key {
-        "breadth" => weights.breadth_weight,
-        "depth" => weights.depth_weight,
-        "evidence_grounding" => weights.evidence_grounding_weight,
-        "blind_spot" => weights.blind_spot_weight,
-        "counter_position" => weights.counter_position_weight,
-        "actionability" => weights.actionability_weight,
-        "uncertainty" => weights.uncertainty_weight,
-        "privacy" => weights.privacy_weight,
-        _ => 1.0,
-    };
+        if scored.is_empty() {
+            // No keyword overlap at all: include the most recent decided
+            // cases rather than an empty behavioral context.
+            fallback.sort_by(|a, b| b.updated_at.cmp(&a.updated_at));
+            fallback.truncate(max.min(2));
+            return Ok(fallback);
+        }
 
-    let mut weighted_breakdown = HashMap::new();
-    let mut weighted_sum = 0.0_f32;
-    let mut weight_sum = 0.0_f32;
-    for (key, score) in scores {
-        let weight = clamp_weight(weight_for(key));
-        let contribution = score.clamp(0.0, 1.0) * weight;
-        weighted_breakdown.insert((*key).to_string(), contribution);
-        weighted_sum += contribution;
-        weight_sum += weight;
+        scored.sort_by(|a, b| {
+            b.0.cmp(&a.0)
+                .then_with(|| {
+                    b.1.correction_note
+                        .is_some()
+                        .cmp(&a.1.correction_note.is_some())
+                })
+                .then_with(|| b.1.updated_at.cmp(&a.1.updated_at))
+        });
+
+        Ok(scored
+            .into_iter()
+            .take(max)
+            .map(|(_, episode)| episode)
+            .collect())
     }
 
-    let unsupported_penalty =
-        (unsupported_claim_count.min(5) as f32 / 5.0) * weights.unsupported_penalty_weight;
-    weighted_breakdown.insert("unsupported_penalty".to_string(), -unsupported_penalty);
+    pub fn update_decision_outcome(
+        &mut self,
+        id: &str,
+        update: DecisionOutcomeUpdate,
+    ) -> Result<DecisionEpisode> {
+        Self::validate_file_id(id)?;
+        let path = self.decision_file_path(id);
+        let mut episode = self.read_decision_file(&path)?;
 
-    if weight_sum <= 0.0 {
-        return (0.0, weighted_breakdown);
-    }
+        if let Some(selected_response) = update.selected_response {
+            episode.selected_response = Some(selected_response);
+        }
+        if let Some(chosen_option) = update.chosen_option {
+            // Canonicalize label/case variants ("b", "Option 2", extra
+            // whitespace) against the recorded options; unmatched free text
+            // is kept as-is (legacy and "other" outcomes stay recordable).
+            let canonical = match_option_index(&chosen_option, &episode.options)
+                .map(|index| episode.options[index].clone())
+                .unwrap_or(chosen_option);
+            episode.chosen_option = Some(canonical);
+        }
+        if let Some(confidence) = update.confidence {
+            episode.confidence = Some(confidence.clamp(0.0, 1.0));
+        }
+        if let Some(review_date) = update.review_date {
+            episode.review_date = Some(review_date);
+        }
+        if let Some(outcome) = update.outcome {
+            episode.outcome = Some(outcome);
+        }
+        if let Some(regret_score) = update.regret_score {
+            episode.regret_score = Some(regret_score.min(10));
+        }
+        if let Some(lesson) = update.lesson {
+            episode.lesson = Some(lesson);
+        }
+        if let Some(missed_something) = update.missed_something {
+            episode.missed_something = Some(missed_something);
+        }
+        if let Some(primitive_assessment) = update.primitive_assessment {
+            episode.primitive_assessment = primitive_assessment;
+        }
+        if let Some(correction_note) = update.correction_note {
+            episode.correction_note = Some(correction_note);
+        }
 
-    let overall = ((weighted_sum - unsupported_penalty) / weight_sum).clamp(0.0, 1.0);
-    (overall, weighted_breakdown)
-}
+        if episode.outcome_recorded_at.is_none()
+            && (episode.chosen_option.is_some() || episode.outcome.is_some())
+        {
+            episode.outcome_recorded_at = Some(Utc::now());
+        }
 
-fn phrase_score(content: &str, phrases: &[&str]) -> f32 {
-    let hits = phrases
-        .iter()
-        .filter(|phrase| content.contains(**phrase))
-        .count();
-    (hits as f32 / phrases.len().max(1) as f32).min(1.0)
-}
+        // Agreement is recomputed whenever both sides exist, so a corrected
+        // chosen_option keeps the stored agreement current. Only predictions
+        // sealed before the outcome was first recorded count.
+        if let (Some(chosen), Some(prediction)) = (&episode.chosen_option, &episode.twin_prediction)
+        {
+            let recorded_at = episode.outcome_recorded_at.unwrap_or_else(Utc::now);
+            if prediction.sealed_at <= recorded_at {
+                episode.agreement = Some(compute_agreement(prediction, chosen, &episode.options));
+            }
+        }
 
-fn unsupported_self_claim_count(
-    lower: &str,
-    evidence_grounding_score: f32,
-    cited_note_ids: &[String],
-    cited_user_record_ids: &[String],
-    cited_constitution_item_ids: &[String],
-    cited_action_gap_ids: &[String],
-) -> u32 {
-    let has_structural_evidence = !cited_note_ids.is_empty()
-        || !cited_user_record_ids.is_empty()
-        || !cited_constitution_item_ids.is_empty()
-        || !cited_action_gap_ids.is_empty()
-        || evidence_grounding_score >= 0.5;
-    if has_structural_evidence {
-        return 0;
+        episode.updated_at = Utc::now();
+        self.write_decision_file(&episode)?;
+        self.append_trace_event(
+            &episode.session_id,
+            TraceEventType::OutcomeFollowUpRecorded,
+            json!({
+                "decision_episode_id": episode.id,
+                "tile_id": episode.tile_id,
+                "selected_response": episode.selected_response,
+                "chosen_option": episode.chosen_option,
+                "confidence": episode.confidence,
+                "review_date": episode.review_date,
+                "outcome": episode.outcome,
+                "regret_score": episode.regret_score,
+                "lesson": episode.lesson,
+                "missed_something": episode.missed_something,
+                "primitive_assessment": episode.primitive_assessment,
+                "agreement": episode.agreement,
+                "correction_note": episode.correction_note,
+                "prediction_context_version": episode
+                    .twin_prediction
+                    .as_ref()
+                    .map(|prediction| prediction.context_version.clone()),
+            }),
+        )?;
+
+        Ok(episode)
     }
 
-    [
-        "you seem",
-        "you may",
-        "you often",
-        "you tend",
-        "your likely",
-        "based on your",
-        "you prefer",
-        "you avoid",
-    ]
-    .iter()
-    .map(|needle| lower.matches(needle).count() as u32)
-    .sum()
-}
+    /// Seal a twin prediction onto an episode. Refuses (as a logged no-op
+    /// returning the unchanged episode) when the outcome is already recorded
+    /// or a prediction already exists, so `sealed_at` always precedes the
+    /// outcome structurally. The trace payload never contains the predicted
+    /// option — the trace viewer must not leak a sealed prediction.
+    pub fn attach_twin_prediction(
+        &mut self,
+        episode_id: &str,
+        draft: TwinPredictionDraft,
+        model_id: &str,
+        context_version: &str,
+    ) -> Result<DecisionEpisode> {
+        Self::validate_file_id(episode_id)?;
+        let path = self.decision_file_path(episode_id);
+        let mut episode = self.read_decision_file(&path)?;
+
+        if episode.chosen_option.is_some() {
+            log::warn!(
+                "Twin prediction for episode {} arrived after the outcome was recorded; discarding",
+                episode_id
+            );
+            episode.prediction_status = Some("outcome_recorded_first".to_string());
+            episode.updated_at = Utc::now();
+            self.write_decision_file(&episode)?;
+            return Ok(episode);
+        }
+        if episode.twin_prediction.is_some() {
+            log::warn!(
+                "Episode {} already has a sealed twin prediction; ignoring duplicate",
+                episode_id
+            );
+            return Ok(episode);
+        }
+
+        let prediction = TwinPrediction {
+            predicted_option: draft.predicted_option,
+            matched_option_index: draft.matched_option_index,
+            confidence: draft.confidence,
+            rationale: draft.rationale,
+            parse_mode: draft.parse_mode.clone(),
+            model_id: model_id.to_string(),
+            context_version: context_version.to_string(),
+            sealed_at: Utc::now(),
+        };
+        let sealed_at = prediction.sealed_at;
+        episode.twin_prediction = Some(prediction);
+        episode.prediction_status = Some("sealed".to_string());
+        episode.updated_at = Utc::now();
+        self.write_decision_file(&episode)?;
+
+        self.append_trace_event(
+            &episode.session_id,
+            TraceEventType::TwinPredictionSealed,
+            json!({
+                "decision_episode_id": episode.id,
+                "tile_id": episode.tile_id,
+                "model_id": model_id,
+                "context_version": context_version,
+                "parse_mode": draft.parse_mode,
+                "sealed_at": sealed_at,
+            }),
+        )?;
+
+        Ok(episode)
+    }
 
-#[derive(Debug, Clone)]
-struct InferredRecordDraft {
-    inference_key: String,
-    signal_family: String,
-    kind: UserRecordKind,
-    content: String,
-    evidence_refs: Vec<EvidenceRef>,
-    evidence_event_ids: Vec<String>,
-    support_count: usize,
-    confidence: f32,
-}
+    /// Record that the hidden prediction call failed, so exported episodes
+    /// distinguish "no prediction because the call failed" from "agreed to
+    /// not predict" — silent gaps would inflate measured accuracy.
+    pub fn mark_twin_prediction_failed(&mut self, episode_id: &str) -> Result<()> {
+        Self::validate_file_id(episode_id)?;
+        let path = self.decision_file_path(episode_id);
+        let mut episode = self.read_decision_file(&path)?;
+        if episode.twin_prediction.is_some() || episode.chosen_option.is_some() {
+            return Ok(());
+        }
+        episode.prediction_status = Some("failed".to_string());
+        episode.updated_at = Utc::now();
+        self.write_decision_file(&episode)
+    }
 
-#[derive(Debug, Default)]
-struct SignalAccumulator {
-    evidence_refs: Vec<EvidenceRef>,
-    evidence_event_ids: HashSet<String>,
-}
+    pub fn record_reflection_card(
+        &mut self,
+        create: ReflectionCardCreate,
+    ) -> Result<ReflectionCard> {
+        Self::validate_file_id(&create.decision_episode_id)?;
+        Self::validate_file_id(&create.session_id)?;
+        Self::validate_file_id(&create.tile_id)?;
 
-impl SignalAccumulator {
-    fn add_event(&mut self, trace: &SessionTrace, event: &TraceEvent) {
-        if !self.evidence_event_ids.insert(event.id.clone()) {
-            return;
+        let config = self.get_decision_mirror_config()?;
+        let mut evidence_packet = match create.evidence_packet.clone() {
+            Some(packet) => packet,
+            None => self.build_decision_evidence_packet(
+                &create.cited_note_ids,
+                &create.cited_user_record_ids,
+                &create.cited_constitution_item_ids,
+                &create.cited_action_gap_ids,
+                &config,
+            )?,
+        };
+        if evidence_packet.config_snapshot.is_none() {
+            evidence_packet.config_snapshot = Some(config.clone());
         }
+        let scores = score_reflection_card(
+            &create.content,
+            &create.cited_note_ids,
+            &create.cited_user_record_ids,
+            &create.cited_constitution_item_ids,
+            &create.cited_action_gap_ids,
+            &config,
+        );
+        let card = ReflectionCard {
+            id: uuid::Uuid::new_v4().to_string(),
+            decision_episode_id: create.decision_episode_id,
+            session_id: create.session_id,
+            tile_id: create.tile_id,
+            model_id: create.model_id,
+            content: create.content,
+            cited_note_ids: create.cited_note_ids,
+            cited_user_record_ids: create.cited_user_record_ids,
+            cited_constitution_item_ids: create.cited_constitution_item_ids,
+            cited_action_gap_ids: create.cited_action_gap_ids,
+            scores,
+            evidence_packet,
+            created_at: Utc::now(),
+        };
 
-        self.evidence_refs.push(EvidenceRef {
-            trace_id: trace.id.clone(),
-            event_id: event.id.clone(),
-            session_id: trace.session_id.clone(),
-            tile_id: extract_event_tile_id(&event.payload),
-            model_id: extract_event_model_id(&event.payload),
-            note: evidence_note(event),
-            source_type: Some("behavior".to_string()),
-            source_id: Some(event.id.clone()),
-            source_label: evidence_note(event),
-            excerpt: Some(excerpt(&event_text(event))),
-            speaker_role: None,
-        });
-    }
-}
+        self.write_reflection_file(&card)?;
+        self.append_trace_event(
+            &card.session_id,
+            TraceEventType::ReflectionCardRecorded,
+            json!({
+                "reflection_card_id": card.id,
+                "decision_episode_id": card.decision_episode_id,
+                "tile_id": card.tile_id,
+                "model_id": card.model_id,
+                "cited_note_ids": card.cited_note_ids,
+                "cited_user_record_ids": card.cited_user_record_ids,
+                "cited_constitution_item_ids": card.cited_constitution_item_ids,
+                "cited_action_gap_ids": card.cited_action_gap_ids,
+                "scores": card.scores,
+                "evidence_packet": card.evidence_packet,
+            }),
+        )?;
 
-fn infer_behavioral_records(traces: &[SessionTrace]) -> Vec<InferredRecordDraft> {
-    let mut signals: HashMap<String, SignalAccumulator> = HashMap::new();
+        Ok(card)
+    }
 
-    for trace in traces {
-        for event in &trace.events {
-            match &event.event_type {
-                TraceEventType::PromptSubmitted => {
-                    let prompt = payload_string(&event.payload, &["prompt"]).unwrap_or_default();
-                    if event
-                        .payload
-                        .get("parent_tile_id")
-                        .is_some_and(|value| !value.is_null())
-                    {
-                        add_signal(&mut signals, "reasoning.iterative_deepening", trace, event);
-                    }
-                    if text_contains_any(
-                        &prompt,
-                        &["think harder", "revisit", "improve your previous answer"],
-                    ) {
-                        add_signal(&mut signals, "reasoning.iterative_deepening", trace, event);
-                    }
-                    if text_contains_any(
-                        &prompt,
-                        &[
-                            "implement",
-                            "fix",
-                            "test",
-                            "build",
-                            "file",
-                            "branch",
-                            "worktree",
-                        ],
-                    ) {
-                        add_signal(
-                            &mut signals,
-                            "preference.implementation_detail",
-                            trace,
-                            event,
-                        );
-                    }
-                    if payload_string(&event.payload, &["context_mode"])
-                        .is_some_and(|mode| mode == "knowledge_search" || mode == "semantic")
-                    {
-                        add_signal(&mut signals, "preference.grounded_context", trace, event);
-                    }
-                    if value_contains_key(&event.payload, "twin_domain") {
-                        add_signal(&mut signals, "fact.twin_domain_metadata", trace, event);
-                    }
-                }
-                TraceEventType::FeedbackRecorded => {
-                    let feedback_type =
-                        payload_string(&event.payload, &["feedback_type"]).unwrap_or_default();
-                    let text = event_text(event);
+    fn build_decision_evidence_packet(
+        &mut self,
+        cited_note_ids: &[String],
+        cited_user_record_ids: &[String],
+        cited_constitution_item_ids: &[String],
+        cited_action_gap_ids: &[String],
+        config: &DecisionMirrorConfig,
+    ) -> Result<DecisionEvidencePacket> {
+        self.ensure_record_cache()?;
+        let weights = &config.weights;
+        let mut selected_sources = Vec::new();
 
-                    match feedback_type.as_str() {
-                        "accept" => {
-                            if looks_structured(&text) {
-                                add_signal(
-                                    &mut signals,
-                                    "preference.structured_answers",
-                                    trace,
-                                    event,
-                                );
-                            }
-                            if looks_evidence_backed(&text) {
-                                add_signal(
-                                    &mut signals,
-                                    "preference.evidence_backed_detail",
-                                    trace,
-                                    event,
-                                );
-                            }
-                            if looks_implementation_detailed(&text) {
-                                add_signal(
-                                    &mut signals,
-                                    "preference.implementation_detail",
-                                    trace,
-                                    event,
-                                );
-                            }
-                        }
-                        "reject" => {
-                            add_signal(&mut signals, "preference.rejects_mismatch", trace, event);
-                        }
-                        "correction" => {
-                            add_signal(&mut signals, "preference.rejects_mismatch", trace, event);
-                            add_signal(&mut signals, "reasoning.corrects_ai_outputs", trace, event);
-                        }
-                        _ => {}
-                    }
-                }
-                TraceEventType::RankingRecorded => {
-                    add_signal(&mut signals, "reasoning.model_comparison", trace, event);
-                    let text = event_text(event);
-                    if looks_structured(&text) {
-                        add_signal(&mut signals, "preference.structured_answers", trace, event);
-                    }
-                    if looks_evidence_backed(&text) {
-                        add_signal(
-                            &mut signals,
-                            "preference.evidence_backed_detail",
-                            trace,
-                            event,
-                        );
-                    }
-                    if looks_implementation_detailed(&text) {
-                        add_signal(
-                            &mut signals,
-                            "preference.implementation_detail",
-                            trace,
-                            event,
-                        );
+        for id in cited_note_ids {
+            selected_sources.push(DecisionEvidenceSource {
+                source_type: "note".to_string(),
+                id: id.clone(),
+                label: format!("Note {}", id),
+                weight: weights.notes_weight,
+                reason: "Selected by vault retrieval for this decision".to_string(),
+            });
+        }
+
+        for id in cited_user_record_ids {
+            if let Ok(record) = self.get_user_record(id) {
+                let (source_type, weight) = match &record.promotion_state {
+                    PromotionState::Endorsed | PromotionState::AutoPromoted => {
+                        ("approved_record", weights.approved_records_weight)
                     }
-                }
-                TraceEventType::InsightCaptured => {
-                    add_signal(
-                        &mut signals,
-                        "reasoning.captures_self_knowledge",
-                        trace,
-                        event,
-                    );
-                }
-                TraceEventType::ModelsAdded => {
-                    add_signal(&mut signals, "reasoning.model_comparison", trace, event);
-                }
-                TraceEventType::DebateStarted | TraceEventType::DebateContinued => {
-                    add_signal(&mut signals, "reasoning.model_comparison", trace, event);
-                    add_signal(&mut signals, "reasoning.uses_debate", trace, event);
-                }
-                TraceEventType::NoteExported => {
-                    add_signal(
-                        &mut signals,
-                        "reasoning.curates_evidence_notes",
-                        trace,
-                        event,
-                    );
-                }
-                TraceEventType::NoteCanonicalPromoted => {
-                    add_signal(&mut signals, "reasoning.canonical_validation", trace, event);
-                }
-                TraceEventType::NoteCreated | TraceEventType::NoteUpdated => {
-                    if value_contains_key(&event.payload, "twin_domain") {
-                        add_signal(&mut signals, "fact.twin_domain_metadata", trace, event);
+                    PromotionState::Candidate => {
+                        ("candidate_record", weights.candidate_records_weight)
                     }
-                    if payload_string(&event.payload, &["status"])
-                        .is_some_and(|status| status == "canonical")
-                    {
-                        add_signal(&mut signals, "reasoning.canonical_validation", trace, event);
+                    PromotionState::Rejected
+                    | PromotionState::Private
+                    | PromotionState::NoTrain => {
+                        continue;
                     }
-                }
-                _ => {}
+                };
+                selected_sources.push(DecisionEvidenceSource {
+                    source_type: source_type.to_string(),
+                    id: record.id,
+                    label: excerpt(&record.content),
+                    weight,
+                    reason: format!(
+                        "{} user record selected for live twin context",
+                        promotion_state_label(&record.promotion_state)
+                    ),
+                });
             }
         }
-    }
-
-    let mut drafts = signals
-        .into_iter()
-        .filter_map(|(key, accumulator)| {
-            let support_count = accumulator.evidence_refs.len();
-            if support_count == 0 {
-                return None;
-            }
-
-            let (kind, signal_family, content) = signal_definition(&key)?;
-            let mut evidence_event_ids = accumulator
-                .evidence_event_ids
-                .into_iter()
-                .collect::<Vec<_>>();
-            evidence_event_ids.sort();
-
-            Some(InferredRecordDraft {
-                inference_key: key,
-                signal_family: signal_family.to_string(),
-                kind,
-                content: content.to_string(),
-                confidence: confidence_for_support(support_count),
-                support_count,
-                evidence_refs: accumulator.evidence_refs,
-                evidence_event_ids,
-            })
-        })
-        .collect::<Vec<_>>();
-
-    drafts.sort_by(|a, b| a.inference_key.cmp(&b.inference_key));
-    drafts
-}
 
-fn add_signal(
-    signals: &mut HashMap<String, SignalAccumulator>,
-    key: &str,
-    trace: &SessionTrace,
-    event: &TraceEvent,
-) {
-    signals
-        .entry(key.to_string())
-        .or_default()
-        .add_event(trace, event);
-}
+        for id in cited_constitution_item_ids {
+            let label = self
+                .read_constitution_file(&self.constitution_file_path(id))
+                .ok()
+                .map(|item| excerpt(&item.claim))
+                .unwrap_or_else(|| format!("Constitution {}", id));
+            selected_sources.push(DecisionEvidenceSource {
+                source_type: "constitution_item".to_string(),
+                id: id.clone(),
+                label,
+                weight: weights.constitution_weight,
+                reason: "Higher-order constitution item selected for decision framing".to_string(),
+            });
+        }
 
-fn signal_definition(key: &str) -> Option<(UserRecordKind, &'static str, &'static str)> {
-    match key {
-        "fact.twin_domain_metadata" => Some((
-            UserRecordKind::Fact,
-            "twin_domain",
-            "Uses twin_domain metadata to separate captured knowledge by the domain it belongs to.",
-        )),
-        "preference.structured_answers" => Some((
-            UserRecordKind::Preference,
-            "explicit_feedback",
-            "Prefers structured answers with headings, lists, or clear steps when judging model output.",
-        )),
-        "preference.evidence_backed_detail" => Some((
-            UserRecordKind::Preference,
-            "explicit_feedback",
-            "Prefers evidence-backed implementation detail over generic summary.",
-        )),
-        "preference.implementation_detail" => Some((
-            UserRecordKind::Preference,
-            "passive_prompting",
-            "Prefers answers that include concrete implementation details such as files, commands, tests, or code.",
-        )),
-        "preference.grounded_context" => Some((
-            UserRecordKind::Preference,
-            "passive_prompting",
-            "Uses existing notes as grounding context when asking models to reason.",
-        )),
-        "preference.rejects_mismatch" => Some((
-            UserRecordKind::Preference,
-            "explicit_feedback",
-            "Rejects or corrects responses that do not match their knowledge instead of saving them as truth.",
-        )),
-        "reasoning.corrects_ai_outputs" => Some((
-            UserRecordKind::ReasoningPattern,
-            "explicit_feedback",
-            "Provides corrections when model output conflicts with what they know.",
-        )),
-        "reasoning.iterative_deepening" => Some((
-            UserRecordKind::ReasoningPattern,
-            "branching",
-            "Revisits answers through branches or think-harder passes before treating them as settled.",
-        )),
-        "reasoning.model_comparison" => Some((
-            UserRecordKind::ReasoningPattern,
-            "model_selection",
-            "Compares multiple model outputs before selecting what matches their thinking.",
-        )),
-        "reasoning.uses_debate" => Some((
-            UserRecordKind::ReasoningPattern,
-            "debate_selection",
-            "Uses model debate or disagreement to test alternatives before deciding what to keep.",
-        )),
-        "reasoning.captures_self_knowledge" => Some((
-            UserRecordKind::ReasoningPattern,
-            "explicit_feedback",
-            "Captures durable facts, preferences, or reasoning patterns as explicit twin records.",
-        )),
-        "reasoning.curates_evidence_notes" => Some((
-            UserRecordKind::ReasoningPattern,
-            "note_export",
-            "Turns useful canvas work into durable evidence notes.",
-        )),
-        "reasoning.canonical_validation" => Some((
-            UserRecordKind::ReasoningPattern,
-            "canonical_promotion",
-            "Promotes knowledge to canonical notes after review or repeated validation.",
-        )),
-        _ => None,
-    }
-}
+        for id in cited_action_gap_ids {
+            let label = self
+                .read_action_gap_file(&self.action_gap_file_path(id))
+                .ok()
+                .map(|gap| excerpt(&gap.decision_risk))
+                .unwrap_or_else(|| format!("Action Gap {}", id));
+            selected_sources.push(DecisionEvidenceSource {
+                source_type: "action_gap".to_string(),
+                id: id.clone(),
+                label,
+                weight: weights.action_gaps_weight,
+                reason: "Action gap selected as decision risk context".to_string(),
+            });
+        }
 
-fn confidence_for_support(support_count: usize) -> f32 {
-    (0.45 + support_count as f32 * 0.10).min(0.95)
-}
+        let mut excluded_private_count = self
+            .record_cache
+            .values()
+            .filter(|record| record.promotion_state == PromotionState::Private)
+            .count();
+        let mut excluded_rejected_count = self
+            .record_cache
+            .values()
+            .filter(|record| record.promotion_state == PromotionState::Rejected)
+            .count();
+        let mut excluded_no_train_count = self
+            .record_cache
+            .values()
+            .filter(|record| record.promotion_state == PromotionState::NoTrain)
+            .count();
 
-fn build_inference_metadata(
-    draft: &InferredRecordDraft,
-    auto_promoted: bool,
-) -> HashMap<String, Value> {
-    json!({
-        "inference_key": draft.inference_key,
-        "inference_version": TWIN_INFERENCE_VERSION,
-        "signal_family": draft.signal_family,
-        "support_count": draft.support_count,
-        "evidence_event_ids": draft.evidence_event_ids,
-        "auto_promoted": auto_promoted,
-    })
-    .as_object()
-    .cloned()
-    .unwrap_or_default()
-    .into_iter()
-    .collect()
-}
+        for item in self.list_constitution_items()? {
+            match item.status {
+                ConstitutionStatus::Private => excluded_private_count += 1,
+                ConstitutionStatus::Rejected | ConstitutionStatus::NotMe => {
+                    excluded_rejected_count += 1
+                }
+                ConstitutionStatus::NoTrain => excluded_no_train_count += 1,
+                ConstitutionStatus::Candidate
+                | ConstitutionStatus::Active
+                | ConstitutionStatus::Softened => {}
+            }
+        }
+        for gap in self.list_action_gaps()? {
+            match gap.status {
+                ConstitutionStatus::Private => excluded_private_count += 1,
+                ConstitutionStatus::Rejected | ConstitutionStatus::NotMe => {
+                    excluded_rejected_count += 1
+                }
+                ConstitutionStatus::NoTrain => excluded_no_train_count += 1,
+                ConstitutionStatus::Candidate
+                | ConstitutionStatus::Active
+                | ConstitutionStatus::Softened => {}
+            }
+        }
 
-fn merge_promotion_history(
-    existing: HashMap<String, Value>,
-    mut next: HashMap<String, Value>,
-) -> HashMap<String, Value> {
-    for (key, value) in existing {
-        next.entry(key).or_insert(value);
+        Ok(DecisionEvidencePacket {
+            selected_sources,
+            excluded_private_count,
+            excluded_rejected_count,
+            excluded_no_train_count,
+            created_at: Some(Utc::now()),
+            config_snapshot: Some(config.clone()),
+        })
     }
-    next
-}
-
-fn append_promotion_history(
-    metadata: &mut HashMap<String, Value>,
-    from: &PromotionState,
-    to: &PromotionState,
-    rationale: Option<&str>,
-    automatic: bool,
-) {
-    let mut history = metadata
-        .get("promotion_history")
-        .and_then(Value::as_array)
-        .cloned()
-        .unwrap_or_default();
 
-    history.push(json!({
-        "from": from,
-        "to": to,
-        "at": Utc::now(),
-        "rationale": rationale,
-        "automatic": automatic,
-    }));
-    metadata.insert("promotion_history".to_string(), Value::Array(history));
-}
+    pub fn list_decision_episodes_with_reflections(
+        &self,
+    ) -> Result<Vec<DecisionEpisodeWithReflections>> {
+        let cards = self.list_reflection_cards()?;
+        let mut cards_by_episode: HashMap<String, Vec<ReflectionCard>> = HashMap::new();
+        for card in cards {
+            cards_by_episode
+                .entry(card.decision_episode_id.clone())
+                .or_default()
+                .push(card);
+        }
 
-fn promotion_state_sort_key(state: &PromotionState) -> u8 {
-    match state {
-        PromotionState::AutoPromoted => 0,
-        PromotionState::Candidate => 1,
-        PromotionState::Endorsed => 2,
-        PromotionState::Rejected => 3,
-        PromotionState::Private => 4,
-        PromotionState::NoTrain => 5,
+        let mut episodes = self
+            .list_decision_episodes()?
+            .into_iter()
+            .map(|mut episode| {
+                let mut reflection_cards = cards_by_episode.remove(&episode.id).unwrap_or_default();
+                reflection_cards.sort_by(|a, b| b.created_at.cmp(&a.created_at));
+                let feedback_events = self.decision_feedback_events(&episode).unwrap_or_default();
+                // A sealed prediction must never cross IPC before the outcome
+                // is recorded; the UI only learns that one exists.
+                let prediction_sealed =
+                    episode.twin_prediction.is_some() && episode.chosen_option.is_none();
+                if prediction_sealed {
+                    episode.twin_prediction = None;
+                }
+                DecisionEpisodeWithReflections {
+                    episode,
+                    reflection_cards,
+                    feedback_events,
+                    prediction_sealed,
+                }
+            })
+            .collect::<Vec<_>>();
+        episodes.sort_by(|a, b| b.episode.updated_at.cmp(&a.episode.updated_at));
+        Ok(episodes)
     }
-}
 
-fn twin_context_record(record: &UserRecord, source_label: &str) -> TwinContextRecord {
-    TwinContextRecord {
-        id: record.id.clone(),
-        kind: record.kind.clone(),
-        content: record.content.clone(),
-        confidence: record.confidence,
-        promotion_state: record.promotion_state.clone(),
-        evidence_count: record.evidence_refs.len(),
-        source_label: Some(source_label.to_string()),
+    fn decision_file_path(&self, decision_id: &str) -> PathBuf {
+        self.decisions_path.join(format!("{}.json", decision_id))
     }
-}
 
-fn twin_record_relevance(record: &UserRecord, query_terms: &HashSet<String>) -> usize {
-    if query_terms.is_empty() {
-        return 0;
+    fn reflection_file_path(&self, reflection_id: &str) -> PathBuf {
+        self.reflections_path
+            .join(format!("{}.json", reflection_id))
     }
 
-    let mut haystack = record.content.clone();
-    for evidence in &record.evidence_refs {
-        if let Some(note) = &evidence.note {
-            haystack.push(' ');
-            haystack.push_str(note);
-        }
-    }
-    for value in record.metadata.values() {
-        haystack.push(' ');
-        haystack.push_str(&value.to_string());
+    fn read_decision_file(&self, path: &Path) -> Result<DecisionEpisode> {
+        let content = std::fs::read_to_string(path)
+            .with_context(|| format!("Failed to read decision file: {}", path.display()))?;
+        serde_json::from_str(&content)
+            .with_context(|| format!("Failed to parse decision file: {}", path.display()))
     }
 
-    let record_terms = lexical_terms(&haystack);
-    query_terms.intersection(&record_terms).count()
-}
-
-const PREDICTION_OPTION_MAX_CHARS: usize = 500;
-const PREDICTION_RATIONALE_MAX_CHARS: usize = 2000;
-
-/// Normalize an option string for comparison: trim, strip wrapping quotes,
-/// lowercase, collapse whitespace. Label forms ("Option 2", "B") are handled
-/// separately by `match_option_index` so meaningful digits survive.
-pub fn normalize_option(text: &str) -> String {
-    text.trim()
-        .trim_matches(|c: char| c == '"' || c == '\'' || c == '`')
-        .to_lowercase()
-        .split_whitespace()
-        .collect::<Vec<_>>()
-        .join(" ")
-}
+    fn write_decision_mirror_config_file(&self, config: &DecisionMirrorConfig) -> Result<()> {
+        self.write_pretty_json(&self.decision_mirror_config_path, config)
+    }
 
-fn truncate_chars(text: &str, max_chars: usize) -> String {
-    if text.chars().count() <= max_chars {
-        text.to_string()
-    } else {
-        text.chars().take(max_chars).collect()
+    fn write_decision_file(&self, episode: &DecisionEpisode) -> Result<()> {
+        let path = self.decision_file_path(&episode.id);
+        self.write_pretty_json(&path, episode)
     }
-}
 
-fn match_option_index(text: &str, options: &[String]) -> Option<usize> {
-    let normalized = normalize_option(text);
-    if normalized.is_empty() {
-        return None;
+    fn write_reflection_file(&self, card: &ReflectionCard) -> Result<()> {
+        let path = self.reflection_file_path(&card.id);
+        self.write_pretty_json(&path, card)
     }
 
-    // Label forms: "option 2" / "choice b" / bare "2" / bare "b".
-    let label = ["option", "choice"]
-        .iter()
-        .find_map(|prefix| normalized.strip_prefix(prefix))
-        .map(str::trim)
-        .unwrap_or(&normalized)
-        .trim_matches(|c: char| c == '.' || c == ')' || c == ':' || c.is_whitespace());
-    if label.len() == 1 {
-        if let Some(letter) = label.chars().next() {
-            if letter.is_ascii_lowercase() {
-                let index = (letter as usize) - ('a' as usize);
-                if index < options.len() {
-                    return Some(index);
+    pub(super) fn list_reflection_cards(&self) -> Result<Vec<ReflectionCard>> {
+        let mut cards = Vec::new();
+        if !self.reflections_path.exists() {
+            return Ok(cards);
+        }
+
+        for entry in WalkDir::new(&self.reflections_path)
+            .min_depth(1)
+            .max_depth(1)
+            .into_iter()
+            .filter_map(|entry| entry.ok())
+        {
+            let path = entry.path();
+            if path.extension().is_some_and(|ext| ext == "json") {
+                if let Some(card) = load_or_quarantine::<ReflectionCard>(path, "reflection card") {
+                    cards.push(card);
                 }
             }
         }
-    }
-    // Bare number labels: humans count from 1.
-    if let Ok(number) = label.parse::<usize>() {
-        if (1..=options.len()).contains(&number) {
-            return Some(number - 1);
-        }
-    }
-
-    options
-        .iter()
-        .position(|option| normalize_option(option) == normalized)
-}
 
-fn sanitize_confidence(raw: Option<f64>) -> Option<f32> {
-    let value = raw?;
-    if !value.is_finite() {
-        return None;
+        cards.sort_by(|a, b| b.created_at.cmp(&a.created_at));
+        Ok(cards)
     }
-    let value = if value > 2.0 && value <= 100.0 {
-        // Percent-style answer ("73" meaning 73%).
-        value / 100.0
-    } else {
-        // Near-misses like 1.2 are over-confident, not percentages.
-        value
-    };
-    Some(value.clamp(0.0, 1.0) as f32)
-}
 
-/// Extract the first balanced `{...}` span from `raw`, for best-effort JSON parsing of
-/// model output. Returns `None` if there's no opening brace, no closing brace, or the
-/// closing brace appears before the opening one (e.g. truncated/malformed model output
-/// like `"Option A} — but {incomplete"`) — guarding this instead of blindly slicing
-/// `&raw[start..=end]` is what prevents a panic on malformed input.
-fn extract_json_slice(raw: &str) -> Option<&str> {
-    let start = raw.find('{')?;
-    let end = raw.rfind('}')?;
-    if start > end {
-        return None;
+    pub(super) fn decision_evidence_refs(&self, decision_id: &str) -> Result<Vec<EvidenceRef>> {
+        Self::validate_file_id(decision_id)?;
+        let mut refs = Vec::new();
+        for entry in WalkDir::new(&self.traces_path)
+            .min_depth(1)
+            .max_depth(1)
+            .into_iter()
+            .filter_map(|entry| entry.ok())
+        {
+            let path = entry.path();
+            if !path.extension().is_some_and(|ext| ext == "json") {
+                continue;
+            }
+            let Some(trace) = load_or_quarantine::<SessionTrace>(path, "trace") else {
+                // A corrupt trace only omits its own evidence refs; the
+                // decision's evidence from healthy traces is still collected.
+                continue;
+            };
+            for event in trace.events {
+                let event_decision_id =
+                    payload_string(&event.payload, &["decision_episode_id"]).unwrap_or_default();
+                if event_decision_id != decision_id {
+                    continue;
+                }
+                refs.push(EvidenceRef {
+                    trace_id: trace.id.clone(),
+                    event_id: event.id.clone(),
+                    session_id: trace.session_id.clone(),
+                    tile_id: extract_event_tile_id(&event.payload),
+                    model_id: extract_event_model_id(&event.payload),
+                    note: Some("Decision episode evidence".to_string()),
+                    source_type: Some("decision".to_string()),
+                    source_id: Some(decision_id.to_string()),
+                    source_label: Some("Decision episode evidence".to_string()),
+                    excerpt: None,
+                    speaker_role: None,
+                });
+            }
+        }
+        refs.sort_by(|a, b| a.event_id.cmp(&b.event_id));
+        Ok(refs)
     }
-    Some(&raw[start..=end])
-}
 
-/// Parse the raw model output of a sealed-prediction call into a draft.
-/// Fallback chain: fenced/embedded strict JSON -> normalized string match
-/// against `options` -> raw text (manual adjudication later).
-pub fn parse_twin_prediction(raw: &str, options: &[String]) -> TwinPredictionDraft {
-    #[derive(serde::Deserialize)]
-    struct ParsedPrediction {
-        predicted_option: Option<String>,
-        option_index: Option<Value>,
-        confidence: Option<f64>,
-        rationale: Option<String>,
+    fn decision_feedback_events(&self, episode: &DecisionEpisode) -> Result<Vec<TraceEvent>> {
+        Self::validate_file_id(&episode.session_id)?;
+        let path = self.trace_file_path(&episode.session_id);
+        if !path.exists() {
+            return Ok(Vec::new());
+        }
+
+        let trace = self.read_trace_file(&path)?;
+        let mut events = trace
+            .events
+            .into_iter()
+            .filter(|event| {
+                matches!(
+                    event.event_type,
+                    TraceEventType::FeedbackRecorded
+                        | TraceEventType::RankingRecorded
+                        | TraceEventType::InsightCaptured
+                )
+            })
+            .filter(|event| {
+                payload_string(&event.payload, &["decision_episode_id"])
+                    .is_some_and(|id| id == episode.id)
+                    || extract_event_tile_id(&event.payload)
+                        .is_some_and(|tile_id| tile_id == episode.tile_id)
+            })
+            .collect::<Vec<_>>();
+        events.sort_by(|a, b| b.created_at.cmp(&a.created_at));
+        Ok(events)
     }
 
-    let json_slice = extract_json_slice(raw);
+    pub fn list_memory_digest(&mut self) -> Result<Vec<MemoryDigestItem>> {
+        self.ensure_record_cache()?;
+        let mut existing = self.read_memory_digest_file()?;
+        let mut existing_by_id = existing
+            .iter()
+            .cloned()
+            .map(|item| (item.id.clone(), item))
+            .collect::<HashMap<_, _>>();
+        let now = Utc::now();
+        let records = self
+            .record_cache
+            .values()
+            .filter(|record| memory_digest_trigger(record).is_some())
+            .cloned()
+            .collect::<Vec<_>>();
+        let mut clusters: HashMap<String, Vec<UserRecord>> = HashMap::new();
 
-    if let Some(slice) = json_slice {
-        if let Ok(parsed) = serde_json::from_str::<ParsedPrediction>(slice) {
-            let text = parsed.predicted_option.unwrap_or_default();
-            let text_index = match_option_index(&text, options);
-            let field_index = parsed.option_index.as_ref().and_then(|value| match value {
-                Value::Number(number) => number.as_u64().map(|n| n as usize),
-                Value::String(text) => text.trim().parse::<usize>().ok(),
-                _ => None,
-            });
-            // The prompt displays a 1-based option list, so prefer the
-            // 1-based reading; tolerate 0-based answers, and let the option
-            // text disambiguate when both readings are valid.
-            let field_index = field_index.and_then(|index| {
-                let one_based = index.checked_sub(1).filter(|i| *i < options.len());
-                let zero_based = Some(index).filter(|i| *i < options.len());
-                match (one_based, zero_based) {
-                    (Some(ob), Some(zb)) => match text_index {
-                        Some(text_idx) if text_idx == zb => Some(zb),
-                        _ => Some(ob),
-                    },
-                    (Some(ob), None) => Some(ob),
-                    (None, Some(zb)) => Some(zb),
-                    (None, None) => None,
-                }
+        for record in records {
+            clusters
+                .entry(memory_digest_cluster_key(&record))
+                .or_default()
+                .push(record);
+        }
+
+        for mut records in clusters.into_values() {
+            records.sort_by(|a, b| {
+                b.evidence_refs
+                    .len()
+                    .cmp(&a.evidence_refs.len())
+                    .then_with(|| {
+                        b.confidence
+                            .partial_cmp(&a.confidence)
+                            .unwrap_or(std::cmp::Ordering::Equal)
+                    })
+                    .then_with(|| b.updated_at.cmp(&a.updated_at))
             });
-            // The option text is what the model actually said; a conflicting
-            // numeric index loses.
-            let matched_option_index = match (text_index, field_index) {
-                (Some(text_idx), _) => Some(text_idx),
-                (None, Some(field_idx)) if text.is_empty() => Some(field_idx),
-                _ => None,
+            let primary = match records.first() {
+                Some(record) => record,
+                None => continue,
             };
-            let predicted_option = if text.is_empty() {
-                matched_option_index
-                    .map(|index| options[index].clone())
-                    .unwrap_or_else(|| truncate_chars(raw.trim(), PREDICTION_OPTION_MAX_CHARS))
+            let item_id = stable_digest_id(&records);
+            if existing_by_id.contains_key(&item_id) {
+                continue;
+            }
+
+            let record_ids = records
+                .iter()
+                .map(|record| record.id.clone())
+                .collect::<Vec<_>>();
+            let evidence_count = records
+                .iter()
+                .map(|record| record.evidence_refs.len())
+                .sum::<usize>();
+            let confidence = records
+                .iter()
+                .map(|record| record.confidence)
+                .fold(0.0_f32, f32::max);
+            let trigger_reason = if records.len() > 1 {
+                format!("{} related patterns clustered for review", records.len())
             } else {
-                truncate_chars(&text, PREDICTION_OPTION_MAX_CHARS)
+                memory_digest_trigger(primary)
+                    .unwrap_or("pattern needs review")
+                    .to_string()
             };
-            return TwinPredictionDraft {
-                predicted_option,
-                matched_option_index,
-                confidence: sanitize_confidence(parsed.confidence),
-                rationale: parsed
-                    .rationale
-                    .map(|text| truncate_chars(&text, PREDICTION_RATIONALE_MAX_CHARS)),
-                parse_mode: "json".to_string(),
+            let latest_evidence = self
+                .resolve_evidence_refs(&primary.evidence_refs)
+                .ok()
+                .and_then(|mut refs| refs.drain(..).next());
+            let item = MemoryDigestItem {
+                id: item_id.clone(),
+                pattern: primary.content.clone(),
+                evidence_count,
+                confidence,
+                trigger_reason,
+                latest_evidence,
+                record_ids,
+                state: MemoryDigestState::Pending,
+                created_at: now,
+                updated_at: now,
             };
+            existing_by_id.insert(item_id, item);
         }
-    }
 
-    if let Some(index) = match_option_index(raw, options) {
-        return TwinPredictionDraft {
-            predicted_option: options[index].clone(),
-            matched_option_index: Some(index),
-            confidence: None,
-            rationale: None,
-            parse_mode: "string_match".to_string(),
-        };
+        existing = existing_by_id.into_values().collect();
+        existing.sort_by(|a, b| {
+            digest_state_sort_key(&a.state)
+                .cmp(&digest_state_sort_key(&b.state))
+                .then_with(|| b.evidence_count.cmp(&a.evidence_count))
+                .then_with(|| {
+                    b.confidence
+                        .partial_cmp(&a.confidence)
+                        .unwrap_or(std::cmp::Ordering::Equal)
+                })
+                .then_with(|| b.updated_at.cmp(&a.updated_at))
+        });
+        self.write_memory_digest_file(&existing)?;
+
+        Ok(existing
+            .into_iter()
+            .filter(|item| item.state == MemoryDigestState::Pending)
+            .take(MAX_MEMORY_DIGEST_ITEMS)
+            .collect())
     }
 
-    TwinPredictionDraft {
-        predicted_option: truncate_chars(raw.trim(), PREDICTION_OPTION_MAX_CHARS),
-        matched_option_index: None,
-        confidence: None,
-        rationale: None,
-        parse_mode: "raw".to_string(),
+    pub fn review_memory_digest_item(
+        &mut self,
+        id: &str,
+        request: MemoryDigestReviewRequest,
+    ) -> Result<MemoryDigestItem> {
+        Self::validate_file_id(id)?;
+        let mut items = self.read_memory_digest_file()?;
+        if !items.iter().any(|item| item.id == id) {
+            let _ = self.list_memory_digest()?;
+            items = self.read_memory_digest_file()?;
+        }
+
+        let item_index = items
+            .iter()
+            .position(|item| item.id == id)
+            .ok_or_else(|| anyhow::anyhow!("Memory digest item not found: {}", id))?;
+        let mut item = items[item_index].clone();
+        item.state = memory_digest_state_for_action(&request.action);
+        item.updated_at = Utc::now();
+        items[item_index] = item.clone();
+        self.write_memory_digest_file(&items)?;
+
+        for record_id in &item.record_ids {
+            if self.get_user_record(record_id).is_err() {
+                continue;
+            }
+
+            let promotion_state = match request.action {
+                MemoryDigestAction::Keep => Some(PromotionState::Endorsed),
+                MemoryDigestAction::Soften => Some(PromotionState::Candidate),
+                MemoryDigestAction::NotMe | MemoryDigestAction::Reject => {
+                    Some(PromotionState::Rejected)
+                }
+                MemoryDigestAction::Private => Some(PromotionState::Private),
+                MemoryDigestAction::NoTrain => Some(PromotionState::NoTrain),
+            };
+
+            if let Some(state) = promotion_state {
+                let _ = self.set_user_record_promotion(
+                    record_id,
+                    state,
+                    request
+                        .rationale
+                        .clone()
+                        .or_else(|| Some(format!("Memory digest action: {:?}", request.action))),
+                );
+            }
+
+            if request.action == MemoryDigestAction::Soften {
+                if let Ok(record) = self.get_user_record(record_id) {
+                    let _ = self.update_user_record(
+                        record_id,
+                        UserRecordUpdate {
+                            confidence: Some((record.confidence * 0.85).max(0.35)),
+                            ..UserRecordUpdate::default()
+                        },
+                    );
+                }
+            }
+        }
+
+        Ok(item)
     }
-}
 
-fn compute_agreement(prediction: &TwinPrediction, chosen: &str, options: &[String]) -> bool {
-    let chosen_index = match_option_index(chosen, options);
-    match (prediction.matched_option_index, chosen_index) {
-        (Some(predicted), Some(chosen)) => predicted == chosen,
-        _ => normalize_option(&prediction.predicted_option) == normalize_option(chosen),
-    }
-}
+    fn read_memory_digest_file(&self) -> Result<Vec<MemoryDigestItem>> {
+        if !self.digest_path.exists() {
+            return Ok(Vec::new());
+        }
 
-fn decision_case_relevance(episode: &DecisionEpisode, query_terms: &HashSet<String>) -> usize {
-    if query_terms.is_empty() {
-        return 0;
+        let content = std::fs::read_to_string(&self.digest_path).with_context(|| {
+            format!(
+                "Failed to read memory digest file: {}",
+                self.digest_path.display()
+            )
+        })?;
+        serde_json::from_str(&content).with_context(|| {
+            format!(
+                "Failed to parse memory digest file: {}",
+                self.digest_path.display()
+            )
+        })
     }
 
-    let mut haystack = episode.decision.clone();
-    haystack.push(' ');
-    haystack.push_str(&episode.options.join(" "));
-    for text in [
-        episode.chosen_option.as_deref(),
-        episode.initial_leaning.as_deref(),
-        episode.lesson.as_deref(),
-        episode.outcome.as_deref(),
-        episode.correction_note.as_deref(),
-    ]
-    .into_iter()
-    .flatten()
-    {
-        haystack.push(' ');
-        haystack.push_str(text);
+    fn write_memory_digest_file(&self, items: &[MemoryDigestItem]) -> Result<()> {
+        self.write_pretty_json(&self.digest_path, &items)
     }
 
-    let episode_terms = lexical_terms(&haystack);
-    query_terms.intersection(&episode_terms).count()
-}
+    pub fn export_bundle(&mut self, request: TwinExportRequest) -> Result<ExportBundle> {
+        self.ensure_record_cache()?;
 
-fn lexical_terms(text: &str) -> HashSet<String> {
-    const STOPWORDS: &[&str] = &[
-        "a", "an", "and", "are", "as", "at", "be", "by", "can", "do", "for", "from", "how", "i",
-        "if", "in", "into", "is", "it", "its", "me", "my", "of", "on", "or", "our", "so", "that",
-        "the", "their", "them", "this", "to", "up", "use", "was", "we", "what", "when", "where",
-        "which", "who", "why", "with", "would", "you", "your",
-    ];
+        let eval_percentage = request.eval_percentage.unwrap_or(DEFAULT_EVAL_PERCENTAGE);
+        let holdout_percentage = request
+            .holdout_percentage
+            .unwrap_or(DEFAULT_HOLDOUT_PERCENTAGE);
 
-    text.split(|ch: char| !ch.is_alphanumeric())
-        .filter_map(|token| {
-            let token = token.trim().to_lowercase();
-            if token.len() < 3 || STOPWORDS.contains(&token.as_str()) {
-                None
-            } else {
-                Some(token)
-            }
-        })
-        .collect()
-}
+        if eval_percentage + holdout_percentage >= 100 {
+            anyhow::bail!("Eval and holdout percentages must total less than 100");
+        }
 
-fn resolve_event_evidence(
-    trace: &SessionTrace,
-    event: &TraceEvent,
-    evidence_ref: &EvidenceRef,
-) -> ResolvedEvidenceRef {
-    let prompt_excerpt = first_payload_string(
-        &event.payload,
-        &[
-            &["prompt"],
-            &["response", "prompt"],
-            &["evidence", "prompt"],
-            &["ranked_responses", "0", "response", "prompt"],
-        ],
-    )
-    .map(|value| excerpt(&value));
+        let bundle_name = request.bundle_name.as_deref().unwrap_or("latest").trim();
+        if bundle_name.is_empty() {
+            anyhow::bail!("Bundle name cannot be empty");
+        }
+        Self::validate_file_id(bundle_name)?;
 
-    let response_excerpt = first_payload_string(
-        &event.payload,
-        &[
-            &["content"],
-            &["response", "response_content"],
-            &["response", "response_excerpt"],
-            &["evidence", "response_content"],
-            &["ranked_responses", "0", "response", "response_content"],
-            &["ranked_responses", "0", "response_excerpt"],
-        ],
-    )
-    .map(|value| excerpt(&value));
+        let output_dir = self.exports_path.join(bundle_name);
+        std::fs::create_dir_all(&output_dir).with_context(|| {
+            format!(
+                "Failed to create export directory: {}",
+                output_dir.display()
+            )
+        })?;
 
-    let model_name = first_payload_string(
-        &event.payload,
-        &[
-            &["model_name"],
-            &["response", "model_name"],
-            &["evidence", "model_name"],
-            &["ranked_responses", "0", "response", "model_name"],
-        ],
-    );
+        let approved_path = output_dir.join("approved_user_records.jsonl");
+        let candidate_path = output_dir.join("candidate_user_records.jsonl");
+        let rejected_path = output_dir.join("rejected_user_records.jsonl");
+        let train_path = output_dir.join("train.jsonl");
+        let eval_path = output_dir.join("eval.jsonl");
+        let holdout_path = output_dir.join("holdout.jsonl");
+        let benchmark_path = output_dir.join("decision_mirror_benchmark.jsonl");
+        let constitution_path = output_dir.join("constitution_items.jsonl");
+        let action_gaps_path = output_dir.join("action_gaps.jsonl");
+        let decision_episodes_path = output_dir.join("decision_episodes.jsonl");
+        let feedback_events_path = output_dir.join("feedback_events.jsonl");
+        let manifest_path = output_dir.join("manifest.json");
 
-    ResolvedEvidenceRef {
-        trace_id: evidence_ref.trace_id.clone(),
-        event_id: event.id.clone(),
-        session_id: trace.session_id.clone(),
-        tile_id: evidence_ref
-            .tile_id
-            .clone()
-            .or_else(|| extract_event_tile_id(&event.payload)),
-        model_id: evidence_ref
-            .model_id
-            .clone()
-            .or_else(|| extract_event_model_id(&event.payload)),
-        event_type: event.event_type.clone(),
-        created_at: event.created_at,
-        note: evidence_ref.note.clone(),
-        summary: Some(event_summary(
-            event,
-            prompt_excerpt.as_deref(),
-            response_excerpt.as_deref(),
-        )),
-        prompt_excerpt,
-        response_excerpt,
-        model_name,
-        source_type: evidence_ref.source_type.clone(),
-        source_id: evidence_ref.source_id.clone(),
-        source_label: evidence_ref.source_label.clone(),
-        excerpt: evidence_ref.excerpt.clone(),
-        speaker_role: evidence_ref.speaker_role.clone(),
-        payload: event.payload.clone(),
-    }
-}
+        let mut records: Vec<UserRecord> = self.record_cache.values().cloned().collect();
+        records.sort_by(|a, b| a.id.cmp(&b.id));
 
-fn event_summary(
-    event: &TraceEvent,
-    prompt_excerpt: Option<&str>,
-    response_excerpt: Option<&str>,
-) -> String {
-    match &event.event_type {
-        TraceEventType::PromptSubmitted => {
-            format!(
-                "Prompt submitted: {}",
-                prompt_excerpt.unwrap_or("no prompt excerpt")
-            )
-        }
-        TraceEventType::ResponseCompleted => {
-            format!(
-                "Response completed: {}",
-                response_excerpt.unwrap_or("no response excerpt")
-            )
-        }
-        TraceEventType::FeedbackRecorded => {
-            let feedback_type = payload_string(&event.payload, &["feedback_type"])
-                .unwrap_or_else(|| "feedback".to_string());
-            format!("{} feedback recorded", feedback_type)
-        }
-        TraceEventType::RankingRecorded => "Response ranking recorded".to_string(),
-        TraceEventType::InsightCaptured => "Explicit twin insight captured".to_string(),
-        TraceEventType::ModelsAdded => "Additional models added for comparison".to_string(),
-        TraceEventType::DebateStarted => "Model debate started".to_string(),
-        TraceEventType::DebateContinued => "Model debate continued".to_string(),
-        TraceEventType::NoteExported => {
-            let title =
-                payload_string(&event.payload, &["title"]).unwrap_or_else(|| "note".to_string());
-            format!("Canvas exported to note: {}", title)
+        let mut approved_lines = Vec::new();
+        let mut candidate_lines = Vec::new();
+        let mut rejected_lines = Vec::new();
+        let mut train_lines = Vec::new();
+        let mut eval_lines = Vec::new();
+        let mut holdout_lines = Vec::new();
+        let mut included_record_ids = Vec::new();
+        let mut private_or_no_train_record_ids = Vec::new();
+
+        for record in records {
+            let line = serde_json::to_string(&Self::record_to_export_value(&record))?;
+
+            match record.promotion_state {
+                PromotionState::AutoPromoted | PromotionState::Endorsed => {
+                    included_record_ids.push(record.id.clone());
+                    approved_lines.push(line.clone());
+                    match Self::split_for_record(&record, eval_percentage, holdout_percentage) {
+                        ExportSplit::Train => train_lines.push(line),
+                        ExportSplit::Eval => eval_lines.push(line),
+                        ExportSplit::Holdout => holdout_lines.push(line),
+                    }
+                }
+                PromotionState::Candidate => {
+                    candidate_lines.push(line);
+                }
+                PromotionState::Rejected => {
+                    rejected_lines.push(line);
+                }
+                PromotionState::Private | PromotionState::NoTrain => {
+                    private_or_no_train_record_ids.push(record.id.clone());
+                }
+            }
         }
-        TraceEventType::NoteCanonicalPromoted => "Note promoted to canonical".to_string(),
-        TraceEventType::NoteCreated => "Note created".to_string(),
-        TraceEventType::NoteUpdated => "Note updated".to_string(),
-        _ => format!("{:?}", &event.event_type),
-    }
-}
 
-fn evidence_note(event: &TraceEvent) -> Option<String> {
-    match &event.event_type {
-        TraceEventType::NoteExported => payload_string(&event.payload, &["title"]),
-        TraceEventType::FeedbackRecorded
-        | TraceEventType::RankingRecorded
-        | TraceEventType::InsightCaptured => payload_string(&event.payload, &["rationale"]),
-        _ => None,
-    }
-}
+        self.write_jsonl_file(&approved_path, &approved_lines)?;
+        self.write_jsonl_file(&candidate_path, &candidate_lines)?;
+        self.write_jsonl_file(&rejected_path, &rejected_lines)?;
+        self.write_jsonl_file(&train_path, &train_lines)?;
+        self.write_jsonl_file(&eval_path, &eval_lines)?;
+        self.write_jsonl_file(&holdout_path, &holdout_lines)?;
+        let decision_mirror_config = self.get_decision_mirror_config()?;
+        let benchmark_lines = self
+            .list_decision_episodes_with_reflections()?
+            .into_iter()
+            .map(|entry| {
+                serde_json::to_string(&json!({
+                    "variant": "decision_mirror",
+                    "baseline_variants": [
+                        "generic_llm",
+                        "persona_prompt",
+                        "vault_only_rag",
+                        "twin_rag",
+                        "decision_mirror"
+                    ],
+                    "config": decision_mirror_config.clone(),
+                    "episode": entry.episode,
+                    "reflection_cards": entry.reflection_cards,
+                }))
+            })
+            .collect::<std::result::Result<Vec<_>, _>>()?;
+        self.write_jsonl_file(&benchmark_path, &benchmark_lines)?;
+        let constitution_lines = self
+            .list_constitution_items()?
+            .into_iter()
+            .map(|item| serde_json::to_string(&item))
+            .collect::<std::result::Result<Vec<_>, _>>()?;
+        self.write_jsonl_file(&constitution_path, &constitution_lines)?;
+        let action_gap_lines = self
+            .list_action_gaps()?
+            .into_iter()
+            .map(|gap| serde_json::to_string(&gap))
+            .collect::<std::result::Result<Vec<_>, _>>()?;
+        self.write_jsonl_file(&action_gaps_path, &action_gap_lines)?;
+
+        // Decision episodes with sealed-prediction integrity: while an
+        // episode has no recorded choice, its prediction exports as a
+        // non-revealing stub so the bet cannot leak through an early export.
+        let decision_episode_lines = self
+            .list_decision_episodes()?
+            .into_iter()
+            .map(|episode| {
+                let still_sealed =
+                    episode.twin_prediction.is_some() && episode.chosen_option.is_none();
+                let mut value = serde_json::to_value(&episode)?;
+                if still_sealed {
+                    if let Some(object) = value.as_object_mut() {
+                        let stub = episode.twin_prediction.as_ref().map(|prediction| {
+                            serde_json::json!({
+                                "sealed": true,
+                                "sealed_at": prediction.sealed_at,
+                                "model_id": prediction.model_id,
+                                "context_version": prediction.context_version,
+                                "parse_mode": prediction.parse_mode,
+                            })
+                        });
+                        object.insert("twin_prediction".to_string(), stub.unwrap_or(Value::Null));
+                    }
+                }
+                serde_json::to_string(&value).map_err(anyhow::Error::from)
+            })
+            .collect::<Result<Vec<_>>>()?;
+        self.write_jsonl_file(&decision_episodes_path, &decision_episode_lines)?;
 
-fn event_text(event: &TraceEvent) -> String {
-    let mut parts = Vec::new();
-    collect_strings(&event.payload, &mut parts);
-    parts.join("\n").to_lowercase()
-}
+        // Ranking / Matches-Me / insight raw material. Privacy rule: skip
+        // events that are evidence for records now marked Rejected, Private,
+        // or NoTrain.
+        let excluded_event_ids: HashSet<String> = self
+            .record_cache
+            .values()
+            .filter(|record| {
+                matches!(
+                    record.promotion_state,
+                    PromotionState::Rejected | PromotionState::Private | PromotionState::NoTrain
+                )
+            })
+            .flat_map(|record| {
+                record
+                    .evidence_refs
+                    .iter()
+                    .map(|evidence| evidence.event_id.clone())
+            })
+            .collect();
+        let feedback_event_lines = self
+            .list_session_traces()?
+            .into_iter()
+            .flat_map(|trace| {
+                let session_id = trace.session_id.clone();
+                let trace_id = trace.id.clone();
+                trace
+                    .events
+                    .into_iter()
+                    .filter(|event| {
+                        matches!(
+                            event.event_type,
+                            TraceEventType::FeedbackRecorded
+                                | TraceEventType::RankingRecorded
+                                | TraceEventType::InsightCaptured
+                        ) && !excluded_event_ids.contains(&event.id)
+                    })
+                    .map(move |event| {
+                        serde_json::to_string(&serde_json::json!({
+                            "session_id": session_id,
+                            "trace_id": trace_id,
+                            "event": event,
+                        }))
+                        .map_err(anyhow::Error::from)
+                    })
+                    .collect::<Vec<_>>()
+            })
+            .collect::<Result<Vec<_>>>()?;
+        self.write_jsonl_file(&feedback_events_path, &feedback_event_lines)?;
 
-fn collect_strings(value: &Value, out: &mut Vec<String>) {
-    match value {
-        Value::String(value) => out.push(value.clone()),
-        Value::Array(items) => {
-            for item in items {
-                collect_strings(item, out);
-            }
-        }
-        Value::Object(map) => {
-            for value in map.values() {
-                collect_strings(value, out);
+        let manifest = serde_json::json!({
+            "bundle_schema_version": 2,
+            "generated_at": Utc::now(),
+            "root_path": self.root_path.display().to_string(),
+            "eval_percentage": eval_percentage,
+            "holdout_percentage": holdout_percentage,
+            "included_record_ids": included_record_ids,
+            "record_files": {
+                "approved_user_records": {
+                    "path": approved_path.display().to_string(),
+                    "count": approved_lines.len(),
+                },
+                "candidate_user_records": {
+                    "path": candidate_path.display().to_string(),
+                    "count": candidate_lines.len(),
+                },
+                "rejected_user_records": {
+                    "path": rejected_path.display().to_string(),
+                    "count": rejected_lines.len(),
+                },
+                "decision_mirror_benchmark": {
+                    "path": benchmark_path.display().to_string(),
+                    "count": benchmark_lines.len(),
+                },
+                "constitution_items": {
+                    "path": constitution_path.display().to_string(),
+                    "count": constitution_lines.len(),
+                },
+                "action_gaps": {
+                    "path": action_gaps_path.display().to_string(),
+                    "count": action_gap_lines.len(),
+                },
+                "decision_episodes": {
+                    "path": decision_episodes_path.display().to_string(),
+                    "count": decision_episode_lines.len(),
+                },
+                "feedback_events": {
+                    "path": feedback_events_path.display().to_string(),
+                    "count": feedback_event_lines.len(),
+                },
+            },
+            "excluded_counts": {
+                "private_or_no_train": private_or_no_train_record_ids.len(),
             }
-        }
-        _ => {}
-    }
-}
-
-fn extract_event_tile_id(payload: &Value) -> Option<String> {
-    first_payload_string(
-        payload,
-        &[
-            &["tile_id"],
-            &["response", "tile_id"],
-            &["evidence", "tile_id"],
-            &["ranked_responses", "0", "response", "tile_id"],
-        ],
-    )
-}
-
-fn extract_event_model_id(payload: &Value) -> Option<String> {
-    first_payload_string(
-        payload,
-        &[
-            &["model_id"],
-            &["response", "model_id"],
-            &["evidence", "model_id"],
-            &["ranked_responses", "0", "response", "model_id"],
-        ],
-    )
-}
-
-fn first_payload_string(payload: &Value, paths: &[&[&str]]) -> Option<String> {
-    paths
-        .iter()
-        .find_map(|path| payload_string(payload, path))
-        .map(|value| value.trim().to_string())
-        .filter(|value| !value.is_empty())
-}
-
-fn payload_string(payload: &Value, path: &[&str]) -> Option<String> {
-    let mut current = payload;
-    for part in path {
-        if let Ok(index) = part.parse::<usize>() {
-            current = current.as_array()?.get(index)?;
-        } else {
-            current = current.get(*part)?;
-        }
-    }
+        });
+        self.write_pretty_json(&manifest_path, &manifest)?;
 
-    current
-        .as_str()
-        .map(ToOwned::to_owned)
-        .or_else(|| match current {
-            Value::Bool(value) => Some(value.to_string()),
-            Value::Number(value) => Some(value.to_string()),
-            _ => None,
+        Ok(ExportBundle {
+            output_dir: output_dir.display().to_string(),
+            approved_user_records: ExportFileSummary {
+                path: approved_path.display().to_string(),
+                count: approved_lines.len(),
+            },
+            candidate_user_records: ExportFileSummary {
+                path: candidate_path.display().to_string(),
+                count: candidate_lines.len(),
+            },
+            rejected_user_records: ExportFileSummary {
+                path: rejected_path.display().to_string(),
+                count: rejected_lines.len(),
+            },
+            decision_mirror_benchmark: ExportFileSummary {
+                path: benchmark_path.display().to_string(),
+                count: benchmark_lines.len(),
+            },
+            constitution_items: ExportFileSummary {
+                path: constitution_path.display().to_string(),
+                count: constitution_lines.len(),
+            },
+            action_gaps: ExportFileSummary {
+                path: action_gaps_path.display().to_string(),
+                count: action_gap_lines.len(),
+            },
+            decision_episodes: ExportFileSummary {
+                path: decision_episodes_path.display().to_string(),
+                count: decision_episode_lines.len(),
+            },
+            feedback_events: ExportFileSummary {
+                path: feedback_events_path.display().to_string(),
+                count: feedback_event_lines.len(),
+            },
+            train: ExportFileSummary {
+                path: train_path.display().to_string(),
+                count: train_lines.len(),
+            },
+            eval: ExportFileSummary {
+                path: eval_path.display().to_string(),
+                count: eval_lines.len(),
+            },
+            holdout: ExportFileSummary {
+                path: holdout_path.display().to_string(),
+                count: holdout_lines.len(),
+            },
+            manifest_path: manifest_path.display().to_string(),
+            included_records: train_lines.len() + eval_lines.len() + holdout_lines.len(),
+            excluded_records: private_or_no_train_record_ids.len(),
         })
-}
-
-fn value_contains_key(value: &Value, key: &str) -> bool {
-    match value {
-        Value::Object(map) => {
-            map.contains_key(key) || map.values().any(|value| value_contains_key(value, key))
-        }
-        Value::Array(items) => items.iter().any(|value| value_contains_key(value, key)),
-        _ => false,
     }
-}
-
-fn looks_structured(text: &str) -> bool {
-    text.contains("\n- ")
-        || text.contains("\n* ")
-        || text.contains("\n1. ")
-        || text.contains("##")
-        || text.contains("```")
-}
 
-fn looks_evidence_backed(text: &str) -> bool {
-    text_contains_any(
-        text,
-        &[
-            "evidence",
-            "source",
-            "according",
-            "because",
-            "verify",
-            "verified",
-            "test",
-            "logs",
-            "tradeoff",
-        ],
-    )
-}
+    fn split_for_record(
+        record: &UserRecord,
+        eval_percentage: u8,
+        holdout_percentage: u8,
+    ) -> ExportSplit {
+        let key = format!(
+            "{}:{}:{}:{}",
+            record.id,
+            serde_json::to_string(&record.kind).unwrap_or_default(),
+            record.content,
+            record.updated_at
+        );
+        let bucket = Self::stable_bucket(&key);
 
-fn looks_implementation_detailed(text: &str) -> bool {
-    text_contains_any(
-        text,
-        &[
-            ".rs",
-            ".js",
-            ".vue",
-            "frontend/",
-            "src/",
-            "cargo ",
-            "npm ",
-            "test",
-            "function ",
-            "```",
-            "command",
-            "file",
-        ],
-    )
-}
+        if bucket < holdout_percentage {
+            ExportSplit::Holdout
+        } else if bucket < holdout_percentage + eval_percentage {
+            ExportSplit::Eval
+        } else {
+            ExportSplit::Train
+        }
+    }
 
-fn text_contains_any(text: &str, needles: &[&str]) -> bool {
-    let text = text.to_lowercase();
-    needles.iter().any(|needle| text.contains(needle))
-}
+    fn stable_bucket(key: &str) -> u8 {
+        let mut hasher = DefaultHasher::new();
+        key.hash(&mut hasher);
+        (hasher.finish() % 100) as u8
+    }
 
-fn excerpt(content: &str) -> String {
-    if content.chars().count() <= EXCERPT_MAX_CHARS {
-        return content.to_string();
+    fn record_to_export_value(record: &UserRecord) -> serde_json::Value {
+        serde_json::json!({
+            "id": record.id,
+            "kind": record.kind,
+            "content": record.content,
+            "origin": record.origin,
+            "promotion_state": record.promotion_state,
+            "confidence": record.confidence,
+            "created_at": record.created_at,
+            "updated_at": record.updated_at,
+            "valid_from": record.valid_from,
+            "valid_until": record.valid_until,
+            "links": record.links,
+            "evidence_refs": record.evidence_refs,
+            "metadata": record.metadata,
+        })
     }
 
-    let mut excerpt = content.chars().take(EXCERPT_MAX_CHARS).collect::<String>();
-    excerpt.push_str("...");
-    excerpt
+    fn write_jsonl_file(&self, path: &Path, lines: &[String]) -> Result<()> {
+        let mut content = lines.join("\n");
+        if !content.is_empty() {
+            content.push('\n');
+        }
+        write_atomic(path, content.as_bytes())
+            .with_context(|| format!("Failed to write JSONL file: {}", path.display()))
+    }
 }
 
 #[cfg(test)]
@@ -4602,423 +4391,157 @@ mod tests {
     };
     use tempfile::tempdir;
 
-    fn test_note(id: &str, title: &str, content: &str, source_type: Option<&str>) -> Note {
-        let now = Utc::now();
-        let mut properties = HashMap::new();
-        if let Some(source_type) = source_type {
-            properties.insert(
-                "source_type".to_string(),
-                Value::String(source_type.to_string()),
-            );
-        }
-        Note {
-            id: id.to_string(),
-            title: title.to_string(),
-            content: content.to_string(),
-            relative_path: format!("{}.md", id),
-            aliases: Vec::new(),
-            status: NoteStatus::Evidence,
-            tags: Vec::new(),
-            created_at: now,
-            updated_at: now,
-            schema_version: crate::models::note::CURRENT_NOTE_SCHEMA_VERSION,
-            migration_source: None,
-            optimizer_managed: false,
-            wikilinks: Vec::new(),
-            parsed_links: Vec::new(),
-            properties,
-            ..Default::default()
-        }
-    }
-
+    use crate::models::twin::ConstitutionStatus;
     #[test]
-    fn user_record_writes_are_atomic_with_no_tmp_litter() {
+    fn evidence_resolution_returns_trace_session_model_and_excerpts() {
         let temp_dir = tempdir().expect("temp dir should be created");
         let mut store = TwinStore::new(temp_dir.path().to_path_buf());
 
+        let event = store
+            .append_trace_event(
+                "session-1",
+                TraceEventType::ResponseCompleted,
+                serde_json::json!({
+                    "tile_id": "tile-1",
+                    "model_id": "openai/gpt-4o",
+                    "model_name": "GPT-4o",
+                    "prompt": "Implement this with tests.",
+                    "content": "Updated frontend/src/api/client.js and ran npm run test:run.",
+                }),
+            )
+            .expect("trace event should append");
         let record = store
             .create_user_record(UserRecordCreate {
                 kind: UserRecordKind::Preference,
-                content: "Prefers atomic writes".to_string(),
-                origin: RecordOrigin::User,
-                evidence_refs: Vec::new(),
-                confidence: default_record_confidence(),
-                promotion_state: None,
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
-            })
-            .expect("record should be created");
-
-        let record_file = store.records_path.join(format!("{}.json", record.id));
-        let persisted = std::fs::read_to_string(&record_file).expect("record file should exist");
-        assert!(persisted.contains("Prefers atomic writes"));
-        crate::services::atomic_io::assert_no_tmp_siblings(&store.records_path);
-    }
-
-    #[test]
-    fn synthetic_records_require_endorsement_for_export() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        let synthetic = store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::Preference,
-                content: "Synthesized summary".to_string(),
-                origin: RecordOrigin::Synthetic,
-                evidence_refs: Vec::new(),
-                confidence: default_record_confidence(),
-                promotion_state: None,
+                content: "Prefers implementation detail.".to_string(),
+                origin: RecordOrigin::Inferred,
+                evidence_refs: vec![EvidenceRef {
+                    trace_id: "session-1".to_string(),
+                    event_id: event.id,
+                    session_id: "session-1".to_string(),
+                    tile_id: Some("tile-1".to_string()),
+                    model_id: Some("openai/gpt-4o".to_string()),
+                    note: None,
+                    source_type: Some("behavior".to_string()),
+                    source_id: None,
+                    source_label: None,
+                    excerpt: None,
+                    speaker_role: None,
+                }],
+                confidence: 0.8,
+                promotion_state: Some(PromotionState::Candidate),
                 valid_from: None,
                 valid_until: None,
                 links: Vec::new(),
-                metadata: HashMap::new(),
-            })
-            .expect("synthetic record should be created");
-
-        let bundle = store
-            .export_bundle(TwinExportRequest::default())
-            .expect("export should succeed");
-        assert_eq!(bundle.included_records, 0);
-
-        store
-            .update_user_record(
-                &synthetic.id,
-                UserRecordUpdate {
-                    promotion_state: Some(PromotionState::Endorsed),
-                    ..UserRecordUpdate::default()
-                },
-            )
-            .expect("synthetic record should update");
-
-        let bundle = store
-            .export_bundle(TwinExportRequest::default())
-            .expect("endorsed export should succeed");
-        assert_eq!(bundle.included_records, 1);
-    }
-
-    #[test]
-    fn decision_episode_and_reflection_card_persist_with_scores() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        let episode = store
-            .record_decision_episode(DecisionEpisodeCreate {
-                id: "decision-1".to_string(),
-                session_id: "session-1".to_string(),
-                tile_id: "tile-1".to_string(),
-                decision: "Should Grafyn build Decision Mirror first?".to_string(),
-                options: vec!["Decision Mirror".to_string(), "Topology".to_string()],
-                stakes: Some("Product direction".to_string()),
-                initial_leaning: Some("Decision Mirror".to_string()),
-                review_date: Some("2026-05-15".to_string()),
-                primitive_assessment: PrimitiveDecisionAssessment {
-                    stakes: Some("high".to_string()),
-                    reversibility: Some("medium".to_string()),
-                    time_horizon: Some("weeks".to_string()),
-                    uncertainty: Some("medium".to_string()),
-                    agency: Some("high".to_string()),
-                    value_tension: Some("ambition vs proof".to_string()),
-                    constraint_pressure: None,
-                    taste_aesthetic_pull: None,
-                    somatic_signal: None,
-                    action_gap_risk: None,
-                    outcome_feedback: None,
-                },
-                context_version: None,
-            })
-            .expect("decision episode should persist");
-
-        let card = store
-            .record_reflection_card(ReflectionCardCreate {
-                decision_episode_id: episode.id.clone(),
-                session_id: episode.session_id.clone(),
-                tile_id: episode.tile_id.clone(),
-                model_id: "openai/gpt-4".to_string(),
-                content: [
-                    "## Decision Frame",
-                    "You seem pulled toward ambitious topology.",
-                    "## Likely Reasoning Pattern",
-                    "You tend to prefer large architecture.",
-                    "## Recommendation",
-                    "Build the smaller proof first.",
-                ]
-                .join("\n"),
-                cited_note_ids: Vec::new(),
-                cited_user_record_ids: Vec::new(),
-                cited_constitution_item_ids: Vec::new(),
-                cited_action_gap_ids: Vec::new(),
-                evidence_packet: None,
-            })
-            .expect("reflection card should persist");
-
-        assert_eq!(card.decision_episode_id, "decision-1");
-        assert!(card.scores.unsupported_claim_count > 0);
-        assert!(card.scores.overall_score <= 1.0);
-        assert_eq!(card.evidence_packet.selected_sources.len(), 0);
-        assert_eq!(
-            card.evidence_packet
-                .config_snapshot
-                .as_ref()
-                .expect("config snapshot should persist")
-                .preset,
-            DecisionMirrorPreset::Balanced
-        );
-        store
-            .append_trace_event(
-                &episode.session_id,
-                TraceEventType::FeedbackRecorded,
-                json!({
-                    "feedback_type": "reject",
-                    "response": {
-                        "tile_id": episode.tile_id.clone(),
-                        "model_id": "openai/gpt-4",
-                    },
-                    "rationale": "Decision Mirror reflection marked Not Me",
-                }),
-            )
-            .expect("feedback event should persist");
+                metadata: HashMap::new(),
+            })
+            .expect("record should be created");
 
-        let decision_rows = store
-            .list_decision_episodes_with_reflections()
-            .expect("decision rows should list with traces");
-        assert_eq!(decision_rows[0].reflection_cards.len(), 1);
-        assert_eq!(decision_rows[0].feedback_events.len(), 1);
+        let evidence = store
+            .resolve_user_record_evidence(&record.id)
+            .expect("evidence should resolve");
+
+        assert_eq!(evidence.len(), 1);
+        assert_eq!(evidence[0].session_id, "session-1");
+        assert_eq!(evidence[0].model_id.as_deref(), Some("openai/gpt-4o"));
         assert_eq!(
-            decision_rows[0].feedback_events[0]
-                .payload
-                .get("feedback_type")
-                .and_then(|value| value.as_str()),
-            Some("reject")
+            evidence[0].prompt_excerpt.as_deref(),
+            Some("Implement this with tests.")
         );
-        let episodes = store
-            .list_decision_episodes()
-            .expect("episodes should list");
-        assert_eq!(episodes.len(), 1);
-
-        let legacy_card: ReflectionCard = serde_json::from_str(
-            r#"{
-                "id": "legacy-card",
-                "decision_episode_id": "decision-1",
-                "session_id": "session-1",
-                "tile_id": "tile-1",
-                "model_id": "openai/gpt-4",
-                "content": "legacy reflection",
-                "scores": { "overall_score": 0.5 },
-                "created_at": "2026-05-08T00:00:00Z"
-            }"#,
-        )
-        .expect("legacy reflection cards should deserialize");
-        assert!(legacy_card.evidence_packet.config_snapshot.is_none());
+        assert!(evidence[0]
+            .response_excerpt
+            .as_deref()
+            .unwrap_or_default()
+            .contains("frontend/src/api/client.js"));
     }
 
     #[test]
-    fn memory_digest_caps_review_items_and_updates_record_state() {
+    fn append_trace_event_creates_trace_file() {
         let temp_dir = tempdir().expect("temp dir should be created");
         let mut store = TwinStore::new(temp_dir.path().to_path_buf());
 
-        let mut record_ids = Vec::new();
-        for index in 0..6 {
-            let record = store
-                .create_user_record(UserRecordCreate {
-                    kind: UserRecordKind::ReasoningPattern,
-                    content: format!("Pattern {} benefits from evidence gates.", index),
-                    origin: RecordOrigin::Inferred,
-                    evidence_refs: vec![
-                        EvidenceRef {
-                            trace_id: "session-1".to_string(),
-                            event_id: format!("event-{}-1", index),
-                            session_id: "session-1".to_string(),
-                            tile_id: Some(format!("tile-{}", index)),
-                            model_id: None,
-                            note: None,
-                            source_type: Some("behavior".to_string()),
-                            source_id: None,
-                            source_label: None,
-                            excerpt: None,
-                            speaker_role: None,
-                        },
-                        EvidenceRef {
-                            trace_id: "session-1".to_string(),
-                            event_id: format!("event-{}-2", index),
-                            session_id: "session-1".to_string(),
-                            tile_id: Some(format!("tile-{}", index)),
-                            model_id: None,
-                            note: None,
-                            source_type: Some("behavior".to_string()),
-                            source_id: None,
-                            source_label: None,
-                            excerpt: None,
-                            speaker_role: None,
-                        },
-                        EvidenceRef {
-                            trace_id: "session-1".to_string(),
-                            event_id: format!("event-{}-3", index),
-                            session_id: "session-1".to_string(),
-                            tile_id: Some(format!("tile-{}", index)),
-                            model_id: None,
-                            note: None,
-                            source_type: Some("behavior".to_string()),
-                            source_id: None,
-                            source_label: None,
-                            excerpt: None,
-                            speaker_role: None,
-                        },
-                    ],
-                    confidence: 0.82,
-                    promotion_state: Some(PromotionState::Candidate),
-                    valid_from: None,
-                    valid_until: None,
-                    links: Vec::new(),
-                    metadata: HashMap::from([(
-                        "signal_family".to_string(),
-                        serde_json::json!(format!("evidence_gate_family_{}", index)),
-                    )]),
-                })
-                .expect("record should be created");
-            record_ids.push(record.id);
-        }
-
-        let digest = store.list_memory_digest().expect("digest should list");
-        assert_eq!(digest.len(), 5);
-        assert!(digest.iter().all(|item| item.evidence_count == 3));
-
-        let reviewed = store
-            .review_memory_digest_item(
-                &digest[0].id,
-                MemoryDigestReviewRequest {
-                    action: MemoryDigestAction::NoTrain,
-                    rationale: Some("Do not use this in twin context".to_string()),
-                },
+        let event = store
+            .append_trace_event(
+                "session-1",
+                TraceEventType::PromptSubmitted,
+                serde_json::json!({ "prompt": "hello" }),
             )
-            .expect("digest item should update");
-        assert_eq!(reviewed.state, MemoryDigestState::NoTrain);
+            .expect("trace event should append");
 
-        let linked_record = store
-            .get_user_record(&reviewed.record_ids[0])
-            .expect("linked record should still exist");
-        assert_eq!(linked_record.promotion_state, PromotionState::NoTrain);
+        let trace = store
+            .get_session_trace("session-1")
+            .expect("trace should load");
 
-        let (approved, candidates) = store
-            .select_context_records("evidence gates")
-            .expect("context records should select");
-        assert!(!approved
-            .iter()
-            .any(|record| record.id == reviewed.record_ids[0]));
-        assert!(!candidates
-            .iter()
-            .any(|record| record.id == reviewed.record_ids[0]));
-        assert_eq!(record_ids.len(), 6);
+        assert_eq!(trace.events.len(), 1);
+        assert_eq!(trace.events[0].id, event.id);
+        assert_eq!(trace.events[0].event_type, TraceEventType::PromptSubmitted);
     }
 
     #[test]
-    fn memory_digest_clusters_related_records() {
+    fn user_record_writes_are_atomic_with_no_tmp_litter() {
         let temp_dir = tempdir().expect("temp dir should be created");
         let mut store = TwinStore::new(temp_dir.path().to_path_buf());
 
-        for index in 0..3 {
-            store
-                .create_user_record(UserRecordCreate {
-                    kind: UserRecordKind::ReasoningPattern,
-                    content: format!(
-                        "Pattern {} says the user benefits from hard evidence gates before scaling.",
-                        index
-                    ),
-                    origin: RecordOrigin::Inferred,
-                    evidence_refs: vec![
-                        EvidenceRef {
-                            trace_id: "session-1".to_string(),
-                            event_id: format!("cluster-event-{}-1", index),
-                            session_id: "session-1".to_string(),
-                            tile_id: Some(format!("cluster-tile-{}", index)),
-                            model_id: None,
-                            note: None,
-                            source_type: Some("behavior".to_string()),
-                            source_id: None,
-                            source_label: None,
-                            excerpt: None,
-                            speaker_role: None,
-                        },
-                        EvidenceRef {
-                            trace_id: "session-1".to_string(),
-                            event_id: format!("cluster-event-{}-2", index),
-                            session_id: "session-1".to_string(),
-                            tile_id: Some(format!("cluster-tile-{}", index)),
-                            model_id: None,
-                            note: None,
-                            source_type: Some("behavior".to_string()),
-                            source_id: None,
-                            source_label: None,
-                            excerpt: None,
-                            speaker_role: None,
-                        },
-                        EvidenceRef {
-                            trace_id: "session-1".to_string(),
-                            event_id: format!("cluster-event-{}-3", index),
-                            session_id: "session-1".to_string(),
-                            tile_id: Some(format!("cluster-tile-{}", index)),
-                            model_id: None,
-                            note: None,
-                            source_type: Some("behavior".to_string()),
-                            source_id: None,
-                            source_label: None,
-                            excerpt: None,
-                            speaker_role: None,
-                        },
-                    ],
-                    confidence: 0.84,
-                    promotion_state: Some(PromotionState::Candidate),
-                    valid_from: None,
-                    valid_until: None,
-                    links: Vec::new(),
-                    metadata: HashMap::from([(
-                        "signal_family".to_string(),
-                        serde_json::json!("evidence_gates"),
-                    )]),
-                })
-                .expect("record should be created");
-        }
+        let record = store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::Preference,
+                content: "Prefers atomic writes".to_string(),
+                origin: RecordOrigin::User,
+                evidence_refs: Vec::new(),
+                confidence: default_record_confidence(),
+                promotion_state: None,
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
+            })
+            .expect("record should be created");
 
-        let digest = store.list_memory_digest().expect("digest should list");
-        assert_eq!(digest.len(), 1);
-        assert_eq!(digest[0].record_ids.len(), 3);
-        assert_eq!(digest[0].evidence_count, 9);
-        assert!(digest[0].trigger_reason.contains("clustered"));
+        let record_file = store.records_path.join(format!("{}.json", record.id));
+        let persisted = std::fs::read_to_string(&record_file).expect("record file should exist");
+        assert!(persisted.contains("Prefers atomic writes"));
+        crate::services::atomic_io::assert_no_tmp_siblings(&store.records_path);
     }
 
     #[test]
-    fn decision_mirror_config_presets_persist() {
+    fn synthetic_records_require_endorsement_for_export() {
         let temp_dir = tempdir().expect("temp dir should be created");
-        let store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        let default_config = store
-            .get_decision_mirror_config()
-            .expect("default config should load");
-        assert_eq!(default_config.preset, DecisionMirrorPreset::Balanced);
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
 
-        let updated = store
-            .update_decision_mirror_config(DecisionMirrorConfigUpdate {
-                preset: Some(DecisionMirrorPreset::EvidenceStrict),
-                weights: None,
-                advanced_enabled: Some(true),
+        let synthetic = store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::Preference,
+                content: "Synthesized summary".to_string(),
+                origin: RecordOrigin::Synthetic,
+                evidence_refs: Vec::new(),
+                confidence: default_record_confidence(),
+                promotion_state: None,
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
             })
-            .expect("config should update");
-        assert_eq!(updated.preset, DecisionMirrorPreset::EvidenceStrict);
-        assert!(
-            updated.weights.evidence_grounding_weight
-                > default_config.weights.evidence_grounding_weight
-        );
+            .expect("synthetic record should be created");
 
-        let persisted = store
-            .get_decision_mirror_config()
-            .expect("persisted config should load");
-        assert_eq!(persisted.preset, DecisionMirrorPreset::EvidenceStrict);
+        let bundle = store
+            .export_bundle(TwinExportRequest::default())
+            .expect("export should succeed");
+        assert_eq!(bundle.included_records, 0);
 
-        let reset = store
-            .reset_decision_mirror_config()
-            .expect("config should reset");
-        assert_eq!(reset.preset, DecisionMirrorPreset::Balanced);
+        store
+            .update_user_record(
+                &synthetic.id,
+                UserRecordUpdate {
+                    promotion_state: Some(PromotionState::Endorsed),
+                    ..UserRecordUpdate::default()
+                },
+            )
+            .expect("synthetic record should update");
+
+        let bundle = store
+            .export_bundle(TwinExportRequest::default())
+            .expect("endorsed export should succeed");
+        assert_eq!(bundle.included_records, 1);
     }
 
     #[test]
@@ -5195,6 +4718,224 @@ mod tests {
         assert!(summary.skipped_rejected_records >= 1);
     }
 
+    #[test]
+    fn context_records_include_approved_and_only_relevant_candidates() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::Preference,
+                content: "Prefers evidence-backed implementation detail.".to_string(),
+                origin: RecordOrigin::User,
+                evidence_refs: Vec::new(),
+                confidence: 0.9,
+                promotion_state: Some(PromotionState::Endorsed),
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
+            })
+            .expect("approved record should create");
+        let relevant_candidate = store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::ReasoningPattern,
+                content: "May prefer red-team critique for shipping decisions.".to_string(),
+                origin: RecordOrigin::Inferred,
+                evidence_refs: Vec::new(),
+                confidence: 0.6,
+                promotion_state: Some(PromotionState::Candidate),
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
+            })
+            .expect("candidate should create");
+        store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::ReasoningPattern,
+                content: "May prefer visual design exploration.".to_string(),
+                origin: RecordOrigin::Inferred,
+                evidence_refs: Vec::new(),
+                confidence: 0.6,
+                promotion_state: Some(PromotionState::Candidate),
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
+            })
+            .expect("irrelevant candidate should create");
+
+        let (approved, candidates) = store
+            .select_context_records("Need red-team critique for this shipping decision")
+            .expect("context records should select");
+
+        assert_eq!(approved.len(), 1);
+        assert_eq!(candidates.len(), 1);
+        assert_eq!(candidates[0].id, relevant_candidate.id);
+    }
+
+    #[test]
+    fn context_records_exclude_rejected_private_and_no_train() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        for state in [
+            PromotionState::Rejected,
+            PromotionState::Private,
+            PromotionState::NoTrain,
+        ] {
+            store
+                .create_user_record(UserRecordCreate {
+                    kind: UserRecordKind::Preference,
+                    content: format!("Excluded record for red-team decision: {:?}", state),
+                    origin: RecordOrigin::User,
+                    evidence_refs: Vec::new(),
+                    confidence: 0.9,
+                    promotion_state: Some(state),
+                    valid_from: None,
+                    valid_until: None,
+                    links: Vec::new(),
+                    metadata: HashMap::new(),
+                })
+                .expect("record should create");
+        }
+
+        let (approved, candidates) = store
+            .select_context_records("red-team decision")
+            .expect("context records should select");
+
+        assert!(approved.is_empty());
+        assert!(candidates.is_empty());
+    }
+
+    #[test]
+    fn export_preserves_history_through_links_instead_of_overwriting() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        let old_record = store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::Preference,
+                content: "Preferred shorter answers earlier.".to_string(),
+                origin: RecordOrigin::User,
+                evidence_refs: Vec::new(),
+                confidence: 0.7,
+                promotion_state: Some(PromotionState::Endorsed),
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
+            })
+            .expect("old record should be created");
+
+        let new_record = store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::Preference,
+                content: "Now prefers blunt, longer answers when accuracy matters.".to_string(),
+                origin: RecordOrigin::User,
+                evidence_refs: Vec::new(),
+                confidence: 0.9,
+                promotion_state: Some(PromotionState::Endorsed),
+                valid_from: None,
+                valid_until: None,
+                links: vec![RecordLink {
+                    relation: RecordLinkType::Supersedes,
+                    target_record_id: old_record.id.clone(),
+                }],
+                metadata: HashMap::new(),
+            })
+            .expect("new record should be created");
+
+        let listed = store.list_user_records().expect("records should list");
+        let old = listed
+            .iter()
+            .find(|record| record.id == old_record.id)
+            .expect("old record should remain present");
+        let new = listed
+            .iter()
+            .find(|record| record.id == new_record.id)
+            .expect("new record should remain present");
+
+        assert!(old.links.is_empty());
+        assert_eq!(new.links.len(), 1);
+        assert_eq!(new.links[0].target_record_id, old_record.id);
+    }
+
+    fn endorsed_record(store: &mut TwinStore, content: &str, confidence: f32) -> UserRecord {
+        store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::Preference,
+                content: content.to_string(),
+                origin: RecordOrigin::User,
+                evidence_refs: Vec::new(),
+                confidence,
+                promotion_state: Some(PromotionState::Endorsed),
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
+            })
+            .expect("record should be created")
+    }
+
+    #[test]
+    fn approved_records_are_relevance_gated_with_confidence_fallback() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        endorsed_record(
+            &mut store,
+            "Prefers remote work over relocation for salary",
+            0.6,
+        );
+        endorsed_record(&mut store, "Enjoys woodworking podcasts on weekends", 0.9);
+
+        let (approved, _) = store
+            .select_context_records("Should I accept the relocation offer for more salary?")
+            .expect("selection should succeed");
+        assert_eq!(approved.len(), 1);
+        assert!(approved[0].content.contains("relocation"));
+
+        // No keyword overlap at all: fall back to top-confidence records
+        // instead of an empty behavioral context.
+        let (fallback, _) = store
+            .select_context_records("zzz qqq xyzzy")
+            .expect("fallback selection should succeed");
+        assert!(!fallback.is_empty());
+        assert!(fallback.len() <= MAX_TWIN_APPROVED_FALLBACK_RECORDS);
+        assert!(fallback[0].content.contains("woodworking"));
+    }
+
+    fn test_note(id: &str, title: &str, content: &str, source_type: Option<&str>) -> Note {
+        let now = Utc::now();
+        let mut properties = HashMap::new();
+        if let Some(source_type) = source_type {
+            properties.insert(
+                "source_type".to_string(),
+                Value::String(source_type.to_string()),
+            );
+        }
+        Note {
+            id: id.to_string(),
+            title: title.to_string(),
+            content: content.to_string(),
+            relative_path: format!("{}.md", id),
+            aliases: Vec::new(),
+            status: NoteStatus::Evidence,
+            tags: Vec::new(),
+            created_at: now,
+            updated_at: now,
+            schema_version: crate::models::note::CURRENT_NOTE_SCHEMA_VERSION,
+            migration_source: None,
+            optimizer_managed: false,
+            wikilinks: Vec::new(),
+            parsed_links: Vec::new(),
+            properties,
+            ..Default::default()
+        }
+    }
+
     #[test]
     fn constitution_inference_uses_repeated_behavior_as_primary_evidence() {
         let temp_dir = tempdir().expect("temp dir should be created");
@@ -5514,292 +5255,152 @@ mod tests {
     }
 
     #[test]
-    fn export_separates_approved_candidate_and_rejected_records() {
+    fn decision_episode_and_reflection_card_persist_with_scores() {
         let temp_dir = tempdir().expect("temp dir should be created");
         let mut store = TwinStore::new(temp_dir.path().to_path_buf());
 
-        store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::Fact,
-                content: "Approved".to_string(),
-                origin: RecordOrigin::User,
-                evidence_refs: Vec::new(),
-                confidence: 0.9,
-                promotion_state: Some(PromotionState::Endorsed),
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
-            })
-            .expect("approved record should be created");
-        store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::Preference,
-                content: "Candidate".to_string(),
-                origin: RecordOrigin::Inferred,
-                evidence_refs: Vec::new(),
-                confidence: 0.6,
-                promotion_state: Some(PromotionState::Candidate),
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
-            })
-            .expect("candidate record should be created");
-        store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::ReasoningPattern,
-                content: "Rejected".to_string(),
-                origin: RecordOrigin::Inferred,
-                evidence_refs: Vec::new(),
-                confidence: 0.8,
-                promotion_state: Some(PromotionState::Rejected),
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
+        let episode = store
+            .record_decision_episode(DecisionEpisodeCreate {
+                id: "decision-1".to_string(),
+                session_id: "session-1".to_string(),
+                tile_id: "tile-1".to_string(),
+                decision: "Should Grafyn build Decision Mirror first?".to_string(),
+                options: vec!["Decision Mirror".to_string(), "Topology".to_string()],
+                stakes: Some("Product direction".to_string()),
+                initial_leaning: Some("Decision Mirror".to_string()),
+                review_date: Some("2026-05-15".to_string()),
+                primitive_assessment: PrimitiveDecisionAssessment {
+                    stakes: Some("high".to_string()),
+                    reversibility: Some("medium".to_string()),
+                    time_horizon: Some("weeks".to_string()),
+                    uncertainty: Some("medium".to_string()),
+                    agency: Some("high".to_string()),
+                    value_tension: Some("ambition vs proof".to_string()),
+                    constraint_pressure: None,
+                    taste_aesthetic_pull: None,
+                    somatic_signal: None,
+                    action_gap_risk: None,
+                    outcome_feedback: None,
+                },
+                context_version: None,
             })
-            .expect("rejected record should be created");
-
-        let bundle = store
-            .export_bundle(TwinExportRequest::default())
-            .expect("export should succeed");
-
-        assert_eq!(bundle.approved_user_records.count, 1);
-        assert_eq!(bundle.candidate_user_records.count, 1);
-        assert_eq!(bundle.rejected_user_records.count, 1);
-        assert!(std::path::Path::new(&bundle.approved_user_records.path).exists());
-        assert!(std::path::Path::new(&bundle.candidate_user_records.path).exists());
-        assert!(std::path::Path::new(&bundle.rejected_user_records.path).exists());
-    }
-
-    #[test]
-    fn context_records_include_approved_and_only_relevant_candidates() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+            .expect("decision episode should persist");
 
-        store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::Preference,
-                content: "Prefers evidence-backed implementation detail.".to_string(),
-                origin: RecordOrigin::User,
-                evidence_refs: Vec::new(),
-                confidence: 0.9,
-                promotion_state: Some(PromotionState::Endorsed),
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
-            })
-            .expect("approved record should create");
-        let relevant_candidate = store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::ReasoningPattern,
-                content: "May prefer red-team critique for shipping decisions.".to_string(),
-                origin: RecordOrigin::Inferred,
-                evidence_refs: Vec::new(),
-                confidence: 0.6,
-                promotion_state: Some(PromotionState::Candidate),
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
-            })
-            .expect("candidate should create");
-        store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::ReasoningPattern,
-                content: "May prefer visual design exploration.".to_string(),
-                origin: RecordOrigin::Inferred,
-                evidence_refs: Vec::new(),
-                confidence: 0.6,
-                promotion_state: Some(PromotionState::Candidate),
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
+        let card = store
+            .record_reflection_card(ReflectionCardCreate {
+                decision_episode_id: episode.id.clone(),
+                session_id: episode.session_id.clone(),
+                tile_id: episode.tile_id.clone(),
+                model_id: "openai/gpt-4".to_string(),
+                content: [
+                    "## Decision Frame",
+                    "You seem pulled toward ambitious topology.",
+                    "## Likely Reasoning Pattern",
+                    "You tend to prefer large architecture.",
+                    "## Recommendation",
+                    "Build the smaller proof first.",
+                ]
+                .join("\n"),
+                cited_note_ids: Vec::new(),
+                cited_user_record_ids: Vec::new(),
+                cited_constitution_item_ids: Vec::new(),
+                cited_action_gap_ids: Vec::new(),
+                evidence_packet: None,
             })
-            .expect("irrelevant candidate should create");
-
-        let (approved, candidates) = store
-            .select_context_records("Need red-team critique for this shipping decision")
-            .expect("context records should select");
-
-        assert_eq!(approved.len(), 1);
-        assert_eq!(candidates.len(), 1);
-        assert_eq!(candidates[0].id, relevant_candidate.id);
-    }
-
-    #[test]
-    fn context_records_exclude_rejected_private_and_no_train() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        for state in [
-            PromotionState::Rejected,
-            PromotionState::Private,
-            PromotionState::NoTrain,
-        ] {
-            store
-                .create_user_record(UserRecordCreate {
-                    kind: UserRecordKind::Preference,
-                    content: format!("Excluded record for red-team decision: {:?}", state),
-                    origin: RecordOrigin::User,
-                    evidence_refs: Vec::new(),
-                    confidence: 0.9,
-                    promotion_state: Some(state),
-                    valid_from: None,
-                    valid_until: None,
-                    links: Vec::new(),
-                    metadata: HashMap::new(),
-                })
-                .expect("record should create");
-        }
-
-        let (approved, candidates) = store
-            .select_context_records("red-team decision")
-            .expect("context records should select");
-
-        assert!(approved.is_empty());
-        assert!(candidates.is_empty());
-    }
-
-    #[test]
-    fn evidence_resolution_returns_trace_session_model_and_excerpts() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+            .expect("reflection card should persist");
 
-        let event = store
+        assert_eq!(card.decision_episode_id, "decision-1");
+        assert!(card.scores.unsupported_claim_count > 0);
+        assert!(card.scores.overall_score <= 1.0);
+        assert_eq!(card.evidence_packet.selected_sources.len(), 0);
+        assert_eq!(
+            card.evidence_packet
+                .config_snapshot
+                .as_ref()
+                .expect("config snapshot should persist")
+                .preset,
+            DecisionMirrorPreset::Balanced
+        );
+        store
             .append_trace_event(
-                "session-1",
-                TraceEventType::ResponseCompleted,
-                serde_json::json!({
-                    "tile_id": "tile-1",
-                    "model_id": "openai/gpt-4o",
-                    "model_name": "GPT-4o",
-                    "prompt": "Implement this with tests.",
-                    "content": "Updated frontend/src/api/client.js and ran npm run test:run.",
-                }),
-            )
-            .expect("trace event should append");
-        let record = store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::Preference,
-                content: "Prefers implementation detail.".to_string(),
-                origin: RecordOrigin::Inferred,
-                evidence_refs: vec![EvidenceRef {
-                    trace_id: "session-1".to_string(),
-                    event_id: event.id,
-                    session_id: "session-1".to_string(),
-                    tile_id: Some("tile-1".to_string()),
-                    model_id: Some("openai/gpt-4o".to_string()),
-                    note: None,
-                    source_type: Some("behavior".to_string()),
-                    source_id: None,
-                    source_label: None,
-                    excerpt: None,
-                    speaker_role: None,
-                }],
-                confidence: 0.8,
-                promotion_state: Some(PromotionState::Candidate),
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
-            })
-            .expect("record should be created");
-
-        let evidence = store
-            .resolve_user_record_evidence(&record.id)
-            .expect("evidence should resolve");
+                &episode.session_id,
+                TraceEventType::FeedbackRecorded,
+                json!({
+                    "feedback_type": "reject",
+                    "response": {
+                        "tile_id": episode.tile_id.clone(),
+                        "model_id": "openai/gpt-4",
+                    },
+                    "rationale": "Decision Mirror reflection marked Not Me",
+                }),
+            )
+            .expect("feedback event should persist");
 
-        assert_eq!(evidence.len(), 1);
-        assert_eq!(evidence[0].session_id, "session-1");
-        assert_eq!(evidence[0].model_id.as_deref(), Some("openai/gpt-4o"));
+        let decision_rows = store
+            .list_decision_episodes_with_reflections()
+            .expect("decision rows should list with traces");
+        assert_eq!(decision_rows[0].reflection_cards.len(), 1);
+        assert_eq!(decision_rows[0].feedback_events.len(), 1);
         assert_eq!(
-            evidence[0].prompt_excerpt.as_deref(),
-            Some("Implement this with tests.")
+            decision_rows[0].feedback_events[0]
+                .payload
+                .get("feedback_type")
+                .and_then(|value| value.as_str()),
+            Some("reject")
         );
-        assert!(evidence[0]
-            .response_excerpt
-            .as_deref()
-            .unwrap_or_default()
-            .contains("frontend/src/api/client.js"));
+        let episodes = store
+            .list_decision_episodes()
+            .expect("episodes should list");
+        assert_eq!(episodes.len(), 1);
+
+        let legacy_card: ReflectionCard = serde_json::from_str(
+            r#"{
+                "id": "legacy-card",
+                "decision_episode_id": "decision-1",
+                "session_id": "session-1",
+                "tile_id": "tile-1",
+                "model_id": "openai/gpt-4",
+                "content": "legacy reflection",
+                "scores": { "overall_score": 0.5 },
+                "created_at": "2026-05-08T00:00:00Z"
+            }"#,
+        )
+        .expect("legacy reflection cards should deserialize");
+        assert!(legacy_card.evidence_packet.config_snapshot.is_none());
     }
 
     #[test]
-    fn export_preserves_history_through_links_instead_of_overwriting() {
+    fn decision_mirror_config_presets_persist() {
         let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+        let store = TwinStore::new(temp_dir.path().to_path_buf());
 
-        let old_record = store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::Preference,
-                content: "Preferred shorter answers earlier.".to_string(),
-                origin: RecordOrigin::User,
-                evidence_refs: Vec::new(),
-                confidence: 0.7,
-                promotion_state: Some(PromotionState::Endorsed),
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
-            })
-            .expect("old record should be created");
+        let default_config = store
+            .get_decision_mirror_config()
+            .expect("default config should load");
+        assert_eq!(default_config.preset, DecisionMirrorPreset::Balanced);
 
-        let new_record = store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::Preference,
-                content: "Now prefers blunt, longer answers when accuracy matters.".to_string(),
-                origin: RecordOrigin::User,
-                evidence_refs: Vec::new(),
-                confidence: 0.9,
-                promotion_state: Some(PromotionState::Endorsed),
-                valid_from: None,
-                valid_until: None,
-                links: vec![RecordLink {
-                    relation: RecordLinkType::Supersedes,
-                    target_record_id: old_record.id.clone(),
-                }],
-                metadata: HashMap::new(),
+        let updated = store
+            .update_decision_mirror_config(DecisionMirrorConfigUpdate {
+                preset: Some(DecisionMirrorPreset::EvidenceStrict),
+                weights: None,
+                advanced_enabled: Some(true),
             })
-            .expect("new record should be created");
-
-        let listed = store.list_user_records().expect("records should list");
-        let old = listed
-            .iter()
-            .find(|record| record.id == old_record.id)
-            .expect("old record should remain present");
-        let new = listed
-            .iter()
-            .find(|record| record.id == new_record.id)
-            .expect("new record should remain present");
-
-        assert!(old.links.is_empty());
-        assert_eq!(new.links.len(), 1);
-        assert_eq!(new.links[0].target_record_id, old_record.id);
-    }
-
-    #[test]
-    fn append_trace_event_creates_trace_file() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        let event = store
-            .append_trace_event(
-                "session-1",
-                TraceEventType::PromptSubmitted,
-                serde_json::json!({ "prompt": "hello" }),
-            )
-            .expect("trace event should append");
+            .expect("config should update");
+        assert_eq!(updated.preset, DecisionMirrorPreset::EvidenceStrict);
+        assert!(
+            updated.weights.evidence_grounding_weight
+                > default_config.weights.evidence_grounding_weight
+        );
 
-        let trace = store
-            .get_session_trace("session-1")
-            .expect("trace should load");
+        let persisted = store
+            .get_decision_mirror_config()
+            .expect("persisted config should load");
+        assert_eq!(persisted.preset, DecisionMirrorPreset::EvidenceStrict);
 
-        assert_eq!(trace.events.len(), 1);
-        assert_eq!(trace.events[0].id, event.id);
-        assert_eq!(trace.events[0].event_type, TraceEventType::PromptSubmitted);
+        let reset = store
+            .reset_decision_mirror_config()
+            .expect("config should reset");
+        assert_eq!(reset.preset, DecisionMirrorPreset::Balanced);
     }
 
     #[test]
@@ -5907,23 +5508,6 @@ mod tests {
         assert_eq!(prediction.predicted_option, "Stay");
     }
 
-    fn endorsed_record(store: &mut TwinStore, content: &str, confidence: f32) -> UserRecord {
-        store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::Preference,
-                content: content.to_string(),
-                origin: RecordOrigin::User,
-                evidence_refs: Vec::new(),
-                confidence,
-                promotion_state: Some(PromotionState::Endorsed),
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
-            })
-            .expect("record should be created")
-    }
-
     fn decided_episode(
         store: &mut TwinStore,
         id: &str,
@@ -5954,34 +5538,6 @@ mod tests {
         decided
     }
 
-    #[test]
-    fn approved_records_are_relevance_gated_with_confidence_fallback() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        endorsed_record(
-            &mut store,
-            "Prefers remote work over relocation for salary",
-            0.6,
-        );
-        endorsed_record(&mut store, "Enjoys woodworking podcasts on weekends", 0.9);
-
-        let (approved, _) = store
-            .select_context_records("Should I accept the relocation offer for more salary?")
-            .expect("selection should succeed");
-        assert_eq!(approved.len(), 1);
-        assert!(approved[0].content.contains("relocation"));
-
-        // No keyword overlap at all: fall back to top-confidence records
-        // instead of an empty behavioral context.
-        let (fallback, _) = store
-            .select_context_records("zzz qqq xyzzy")
-            .expect("fallback selection should succeed");
-        assert!(!fallback.is_empty());
-        assert!(fallback.len() <= MAX_TWIN_APPROVED_FALLBACK_RECORDS);
-        assert!(fallback[0].content.contains("woodworking"));
-    }
-
     #[test]
     fn decision_cases_rank_relevance_above_correction_notes() {
         let temp_dir = tempdir().expect("temp dir should be created");
@@ -6170,17 +5726,91 @@ mod tests {
             r#"{"predicted_option": "Stay in Austin", "confidence": null}"#,
             &options,
         );
-        assert!(null.confidence.is_none());
+        assert!(null.confidence.is_none());
+    }
+
+    #[test]
+    fn attach_twin_prediction_refuses_after_outcome_and_duplicates() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        let episode = store
+            .record_decision_episode(DecisionEpisodeCreate {
+                id: "decision-attach".to_string(),
+                session_id: "session-1".to_string(),
+                tile_id: "tile-1".to_string(),
+                decision: "Take the Denver job?".to_string(),
+                options: prediction_options(),
+                stakes: None,
+                initial_leaning: None,
+                review_date: None,
+                primitive_assessment: PrimitiveDecisionAssessment::default(),
+                context_version: Some("ctx-test".to_string()),
+            })
+            .expect("episode should persist");
+
+        let draft = parse_twin_prediction("Stay in Austin", &prediction_options());
+        let sealed = store
+            .attach_twin_prediction(&episode.id, draft.clone(), "test/model", "ctx-test")
+            .expect("first attach should seal");
+        assert_eq!(sealed.prediction_status.as_deref(), Some("sealed"));
+        let first_sealed_at = sealed.twin_prediction.as_ref().unwrap().sealed_at;
+
+        // Duplicate attach is a no-op.
+        let duplicate = store
+            .attach_twin_prediction(&episode.id, draft.clone(), "other/model", "ctx-test")
+            .expect("duplicate attach should not error");
+        assert_eq!(
+            duplicate.twin_prediction.as_ref().unwrap().sealed_at,
+            first_sealed_at
+        );
+        assert_eq!(
+            duplicate.twin_prediction.as_ref().unwrap().model_id,
+            "test/model"
+        );
+
+        // Outcome-first race: attach after the choice is recorded.
+        let late_episode = store
+            .record_decision_episode(DecisionEpisodeCreate {
+                id: "decision-late".to_string(),
+                session_id: "session-1".to_string(),
+                tile_id: "tile-2".to_string(),
+                decision: "Take the Denver job?".to_string(),
+                options: prediction_options(),
+                stakes: None,
+                initial_leaning: None,
+                review_date: None,
+                primitive_assessment: PrimitiveDecisionAssessment::default(),
+                context_version: None,
+            })
+            .expect("episode should persist");
+        store
+            .update_decision_outcome(
+                &late_episode.id,
+                DecisionOutcomeUpdate {
+                    chosen_option: Some("Stay in Austin".to_string()),
+                    ..DecisionOutcomeUpdate::default()
+                },
+            )
+            .expect("outcome should record");
+        let refused = store
+            .attach_twin_prediction(&late_episode.id, draft, "test/model", "ctx-test")
+            .expect("late attach should not error");
+        assert!(refused.twin_prediction.is_none());
+        assert_eq!(
+            refused.prediction_status.as_deref(),
+            Some("outcome_recorded_first")
+        );
     }
 
     #[test]
-    fn attach_twin_prediction_refuses_after_outcome_and_duplicates() {
+    fn outcome_computes_agreement_and_canonicalizes_choice() {
         let temp_dir = tempdir().expect("temp dir should be created");
         let mut store = TwinStore::new(temp_dir.path().to_path_buf());
 
         let episode = store
             .record_decision_episode(DecisionEpisodeCreate {
-                id: "decision-attach".to_string(),
+                id: "decision-agree".to_string(),
                 session_id: "session-1".to_string(),
                 tile_id: "tile-1".to_string(),
                 decision: "Take the Denver job?".to_string(),
@@ -6192,33 +5822,59 @@ mod tests {
                 context_version: Some("ctx-test".to_string()),
             })
             .expect("episode should persist");
-
         let draft = parse_twin_prediction("Stay in Austin", &prediction_options());
-        let sealed = store
-            .attach_twin_prediction(&episode.id, draft.clone(), "test/model", "ctx-test")
-            .expect("first attach should seal");
-        assert_eq!(sealed.prediction_status.as_deref(), Some("sealed"));
-        let first_sealed_at = sealed.twin_prediction.as_ref().unwrap().sealed_at;
+        store
+            .attach_twin_prediction(&episode.id, draft, "test/model", "ctx-test")
+            .expect("prediction should seal");
 
-        // Duplicate attach is a no-op.
-        let duplicate = store
-            .attach_twin_prediction(&episode.id, draft.clone(), "other/model", "ctx-test")
-            .expect("duplicate attach should not error");
-        assert_eq!(
-            duplicate.twin_prediction.as_ref().unwrap().sealed_at,
-            first_sealed_at
-        );
+        // Label + case variant resolves to the canonical option text and
+        // agreement computes via index comparison.
+        let updated = store
+            .update_decision_outcome(
+                &episode.id,
+                DecisionOutcomeUpdate {
+                    chosen_option: Some("option 2".to_string()),
+                    correction_note: None,
+                    ..DecisionOutcomeUpdate::default()
+                },
+            )
+            .expect("outcome should record");
+        assert_eq!(updated.chosen_option.as_deref(), Some("Stay in Austin"));
+        assert_eq!(updated.agreement, Some(true));
+        assert!(updated.outcome_recorded_at.is_some());
+
+        // Editing the choice recomputes agreement and accepts a correction
+        // note; outcome_recorded_at is not reset.
+        let first_recorded_at = updated.outcome_recorded_at;
+        let edited = store
+            .update_decision_outcome(
+                &episode.id,
+                DecisionOutcomeUpdate {
+                    chosen_option: Some("  TAKE the denver JOB ".to_string()),
+                    correction_note: Some("Twin overweighted family proximity.".to_string()),
+                    ..DecisionOutcomeUpdate::default()
+                },
+            )
+            .expect("edited outcome should record");
+        assert_eq!(edited.chosen_option.as_deref(), Some("Take the Denver job"));
+        assert_eq!(edited.agreement, Some(false));
         assert_eq!(
-            duplicate.twin_prediction.as_ref().unwrap().model_id,
-            "test/model"
+            edited.correction_note.as_deref(),
+            Some("Twin overweighted family proximity.")
         );
+        assert_eq!(edited.outcome_recorded_at, first_recorded_at);
+    }
 
-        // Outcome-first race: attach after the choice is recorded.
-        let late_episode = store
+    #[test]
+    fn outcome_without_prediction_records_no_agreement_and_keeps_free_text() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        let episode = store
             .record_decision_episode(DecisionEpisodeCreate {
-                id: "decision-late".to_string(),
+                id: "decision-free".to_string(),
                 session_id: "session-1".to_string(),
-                tile_id: "tile-2".to_string(),
+                tile_id: "tile-1".to_string(),
                 decision: "Take the Denver job?".to_string(),
                 options: prediction_options(),
                 stakes: None,
@@ -6228,122 +5884,256 @@ mod tests {
                 context_version: None,
             })
             .expect("episode should persist");
-        store
+
+        let updated = store
             .update_decision_outcome(
-                &late_episode.id,
+                &episode.id,
                 DecisionOutcomeUpdate {
-                    chosen_option: Some("Stay in Austin".to_string()),
+                    chosen_option: Some("Negotiated a remote arrangement instead".to_string()),
                     ..DecisionOutcomeUpdate::default()
                 },
             )
             .expect("outcome should record");
-        let refused = store
-            .attach_twin_prediction(&late_episode.id, draft, "test/model", "ctx-test")
-            .expect("late attach should not error");
-        assert!(refused.twin_prediction.is_none());
+        // Free text that matches no option is preserved verbatim.
         assert_eq!(
-            refused.prediction_status.as_deref(),
-            Some("outcome_recorded_first")
+            updated.chosen_option.as_deref(),
+            Some("Negotiated a remote arrangement instead")
         );
+        assert!(updated.agreement.is_none());
+    }
+
+    #[test]
+    fn memory_digest_caps_review_items_and_updates_record_state() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        let mut record_ids = Vec::new();
+        for index in 0..6 {
+            let record = store
+                .create_user_record(UserRecordCreate {
+                    kind: UserRecordKind::ReasoningPattern,
+                    content: format!("Pattern {} benefits from evidence gates.", index),
+                    origin: RecordOrigin::Inferred,
+                    evidence_refs: vec![
+                        EvidenceRef {
+                            trace_id: "session-1".to_string(),
+                            event_id: format!("event-{}-1", index),
+                            session_id: "session-1".to_string(),
+                            tile_id: Some(format!("tile-{}", index)),
+                            model_id: None,
+                            note: None,
+                            source_type: Some("behavior".to_string()),
+                            source_id: None,
+                            source_label: None,
+                            excerpt: None,
+                            speaker_role: None,
+                        },
+                        EvidenceRef {
+                            trace_id: "session-1".to_string(),
+                            event_id: format!("event-{}-2", index),
+                            session_id: "session-1".to_string(),
+                            tile_id: Some(format!("tile-{}", index)),
+                            model_id: None,
+                            note: None,
+                            source_type: Some("behavior".to_string()),
+                            source_id: None,
+                            source_label: None,
+                            excerpt: None,
+                            speaker_role: None,
+                        },
+                        EvidenceRef {
+                            trace_id: "session-1".to_string(),
+                            event_id: format!("event-{}-3", index),
+                            session_id: "session-1".to_string(),
+                            tile_id: Some(format!("tile-{}", index)),
+                            model_id: None,
+                            note: None,
+                            source_type: Some("behavior".to_string()),
+                            source_id: None,
+                            source_label: None,
+                            excerpt: None,
+                            speaker_role: None,
+                        },
+                    ],
+                    confidence: 0.82,
+                    promotion_state: Some(PromotionState::Candidate),
+                    valid_from: None,
+                    valid_until: None,
+                    links: Vec::new(),
+                    metadata: HashMap::from([(
+                        "signal_family".to_string(),
+                        serde_json::json!(format!("evidence_gate_family_{}", index)),
+                    )]),
+                })
+                .expect("record should be created");
+            record_ids.push(record.id);
+        }
+
+        let digest = store.list_memory_digest().expect("digest should list");
+        assert_eq!(digest.len(), 5);
+        assert!(digest.iter().all(|item| item.evidence_count == 3));
+
+        let reviewed = store
+            .review_memory_digest_item(
+                &digest[0].id,
+                MemoryDigestReviewRequest {
+                    action: MemoryDigestAction::NoTrain,
+                    rationale: Some("Do not use this in twin context".to_string()),
+                },
+            )
+            .expect("digest item should update");
+        assert_eq!(reviewed.state, MemoryDigestState::NoTrain);
+
+        let linked_record = store
+            .get_user_record(&reviewed.record_ids[0])
+            .expect("linked record should still exist");
+        assert_eq!(linked_record.promotion_state, PromotionState::NoTrain);
+
+        let (approved, candidates) = store
+            .select_context_records("evidence gates")
+            .expect("context records should select");
+        assert!(!approved
+            .iter()
+            .any(|record| record.id == reviewed.record_ids[0]));
+        assert!(!candidates
+            .iter()
+            .any(|record| record.id == reviewed.record_ids[0]));
+        assert_eq!(record_ids.len(), 6);
+    }
+
+    #[test]
+    fn memory_digest_clusters_related_records() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        for index in 0..3 {
+            store
+                .create_user_record(UserRecordCreate {
+                    kind: UserRecordKind::ReasoningPattern,
+                    content: format!(
+                        "Pattern {} says the user benefits from hard evidence gates before scaling.",
+                        index
+                    ),
+                    origin: RecordOrigin::Inferred,
+                    evidence_refs: vec![
+                        EvidenceRef {
+                            trace_id: "session-1".to_string(),
+                            event_id: format!("cluster-event-{}-1", index),
+                            session_id: "session-1".to_string(),
+                            tile_id: Some(format!("cluster-tile-{}", index)),
+                            model_id: None,
+                            note: None,
+                            source_type: Some("behavior".to_string()),
+                            source_id: None,
+                            source_label: None,
+                            excerpt: None,
+                            speaker_role: None,
+                        },
+                        EvidenceRef {
+                            trace_id: "session-1".to_string(),
+                            event_id: format!("cluster-event-{}-2", index),
+                            session_id: "session-1".to_string(),
+                            tile_id: Some(format!("cluster-tile-{}", index)),
+                            model_id: None,
+                            note: None,
+                            source_type: Some("behavior".to_string()),
+                            source_id: None,
+                            source_label: None,
+                            excerpt: None,
+                            speaker_role: None,
+                        },
+                        EvidenceRef {
+                            trace_id: "session-1".to_string(),
+                            event_id: format!("cluster-event-{}-3", index),
+                            session_id: "session-1".to_string(),
+                            tile_id: Some(format!("cluster-tile-{}", index)),
+                            model_id: None,
+                            note: None,
+                            source_type: Some("behavior".to_string()),
+                            source_id: None,
+                            source_label: None,
+                            excerpt: None,
+                            speaker_role: None,
+                        },
+                    ],
+                    confidence: 0.84,
+                    promotion_state: Some(PromotionState::Candidate),
+                    valid_from: None,
+                    valid_until: None,
+                    links: Vec::new(),
+                    metadata: HashMap::from([(
+                        "signal_family".to_string(),
+                        serde_json::json!("evidence_gates"),
+                    )]),
+                })
+                .expect("record should be created");
+        }
+
+        let digest = store.list_memory_digest().expect("digest should list");
+        assert_eq!(digest.len(), 1);
+        assert_eq!(digest[0].record_ids.len(), 3);
+        assert_eq!(digest[0].evidence_count, 9);
+        assert!(digest[0].trigger_reason.contains("clustered"));
     }
 
     #[test]
-    fn outcome_computes_agreement_and_canonicalizes_choice() {
+    fn export_separates_approved_candidate_and_rejected_records() {
         let temp_dir = tempdir().expect("temp dir should be created");
         let mut store = TwinStore::new(temp_dir.path().to_path_buf());
 
-        let episode = store
-            .record_decision_episode(DecisionEpisodeCreate {
-                id: "decision-agree".to_string(),
-                session_id: "session-1".to_string(),
-                tile_id: "tile-1".to_string(),
-                decision: "Take the Denver job?".to_string(),
-                options: prediction_options(),
-                stakes: None,
-                initial_leaning: None,
-                review_date: None,
-                primitive_assessment: PrimitiveDecisionAssessment::default(),
-                context_version: Some("ctx-test".to_string()),
+        store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::Fact,
+                content: "Approved".to_string(),
+                origin: RecordOrigin::User,
+                evidence_refs: Vec::new(),
+                confidence: 0.9,
+                promotion_state: Some(PromotionState::Endorsed),
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
             })
-            .expect("episode should persist");
-        let draft = parse_twin_prediction("Stay in Austin", &prediction_options());
+            .expect("approved record should be created");
         store
-            .attach_twin_prediction(&episode.id, draft, "test/model", "ctx-test")
-            .expect("prediction should seal");
-
-        // Label + case variant resolves to the canonical option text and
-        // agreement computes via index comparison.
-        let updated = store
-            .update_decision_outcome(
-                &episode.id,
-                DecisionOutcomeUpdate {
-                    chosen_option: Some("option 2".to_string()),
-                    correction_note: None,
-                    ..DecisionOutcomeUpdate::default()
-                },
-            )
-            .expect("outcome should record");
-        assert_eq!(updated.chosen_option.as_deref(), Some("Stay in Austin"));
-        assert_eq!(updated.agreement, Some(true));
-        assert!(updated.outcome_recorded_at.is_some());
-
-        // Editing the choice recomputes agreement and accepts a correction
-        // note; outcome_recorded_at is not reset.
-        let first_recorded_at = updated.outcome_recorded_at;
-        let edited = store
-            .update_decision_outcome(
-                &episode.id,
-                DecisionOutcomeUpdate {
-                    chosen_option: Some("  TAKE the denver JOB ".to_string()),
-                    correction_note: Some("Twin overweighted family proximity.".to_string()),
-                    ..DecisionOutcomeUpdate::default()
-                },
-            )
-            .expect("edited outcome should record");
-        assert_eq!(edited.chosen_option.as_deref(), Some("Take the Denver job"));
-        assert_eq!(edited.agreement, Some(false));
-        assert_eq!(
-            edited.correction_note.as_deref(),
-            Some("Twin overweighted family proximity.")
-        );
-        assert_eq!(edited.outcome_recorded_at, first_recorded_at);
-    }
-
-    #[test]
-    fn outcome_without_prediction_records_no_agreement_and_keeps_free_text() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        let episode = store
-            .record_decision_episode(DecisionEpisodeCreate {
-                id: "decision-free".to_string(),
-                session_id: "session-1".to_string(),
-                tile_id: "tile-1".to_string(),
-                decision: "Take the Denver job?".to_string(),
-                options: prediction_options(),
-                stakes: None,
-                initial_leaning: None,
-                review_date: None,
-                primitive_assessment: PrimitiveDecisionAssessment::default(),
-                context_version: None,
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::Preference,
+                content: "Candidate".to_string(),
+                origin: RecordOrigin::Inferred,
+                evidence_refs: Vec::new(),
+                confidence: 0.6,
+                promotion_state: Some(PromotionState::Candidate),
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
             })
-            .expect("episode should persist");
+            .expect("candidate record should be created");
+        store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::ReasoningPattern,
+                content: "Rejected".to_string(),
+                origin: RecordOrigin::Inferred,
+                evidence_refs: Vec::new(),
+                confidence: 0.8,
+                promotion_state: Some(PromotionState::Rejected),
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
+            })
+            .expect("rejected record should be created");
 
-        let updated = store
-            .update_decision_outcome(
-                &episode.id,
-                DecisionOutcomeUpdate {
-                    chosen_option: Some("Negotiated a remote arrangement instead".to_string()),
-                    ..DecisionOutcomeUpdate::default()
-                },
-            )
-            .expect("outcome should record");
-        // Free text that matches no option is preserved verbatim.
-        assert_eq!(
-            updated.chosen_option.as_deref(),
-            Some("Negotiated a remote arrangement instead")
-        );
-        assert!(updated.agreement.is_none());
+        let bundle = store
+            .export_bundle(TwinExportRequest::default())
+            .expect("export should succeed");
+
+        assert_eq!(bundle.approved_user_records.count, 1);
+        assert_eq!(bundle.candidate_user_records.count, 1);
+        assert_eq!(bundle.rejected_user_records.count, 1);
+        assert!(std::path::Path::new(&bundle.approved_user_records.path).exists());
+        assert!(std::path::Path::new(&bundle.candidate_user_records.path).exists());
+        assert!(std::path::Path::new(&bundle.rejected_user_records.path).exists());
     }
 
     #[test]
@@ -6453,345 +6243,4 @@ mod tests {
         assert!(!feedback_content.contains(&private_event.id));
         assert!(feedback_content.contains(&exportable_event.id));
     }
-
-    /// Corrupt-file quarantine sweep (Task 1.5): a directory listing must never brick
-    /// entirely because of one unparsable file. Covers the two sites named in the audit
-    /// (`ensure_record_cache`, `list_session_traces`) plus every sibling loop found with
-    /// the same `?`-propagate-on-per-file-parse-failure pattern (`list_decision_episodes`,
-    /// `list_constitution_items`, `list_action_gaps`, `list_reflection_cards`).
-    mod corrupt_file_quarantine {
-        use super::*;
-
-        /// Return the `.corrupt-*` sibling files in `dir`, if any.
-        fn quarantined_siblings(dir: &Path) -> Vec<std::path::PathBuf> {
-            std::fs::read_dir(dir)
-                .expect("read dir")
-                .filter_map(|entry| entry.ok())
-                .map(|entry| entry.path())
-                .filter(|p| {
-                    p.file_name()
-                        .and_then(|n| n.to_str())
-                        .map(|n| n.contains(".corrupt-"))
-                        .unwrap_or(false)
-                })
-                .collect()
-        }
-
-        #[test]
-        fn load_or_quarantine_skips_unreadable_file_without_quarantining() {
-            let temp_dir = tempdir().expect("temp dir should be created");
-            // A directory standing in for a file triggers a genuine read error (not a
-            // parse error) deterministically, without relying on OS permission quirks.
-            let bogus_path = temp_dir.path().join("not-a-file.json");
-            std::fs::create_dir(&bogus_path).expect("create directory standing in for a file");
-
-            let result = load_or_quarantine::<UserRecord>(&bogus_path, "record");
-            assert!(result.is_none());
-            assert!(
-                bogus_path.exists(),
-                "a read failure may be transient (permissions, AV lock) — the path must be left untouched"
-            );
-            assert!(quarantined_siblings(temp_dir.path()).is_empty());
-        }
-
-        #[test]
-        fn list_user_records_quarantines_corrupt_record_and_returns_healthy_ones() {
-            let temp_dir = tempdir().expect("temp dir should be created");
-            let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-            for i in 0..2 {
-                let record = UserRecord {
-                    id: format!("record-{i}"),
-                    kind: UserRecordKind::Preference,
-                    content: format!("Healthy record {i}"),
-                    evidence_refs: Vec::new(),
-                    confidence: default_record_confidence(),
-                    origin: RecordOrigin::User,
-                    promotion_state: PromotionState::default_for_origin(&RecordOrigin::User),
-                    created_at: Utc::now(),
-                    updated_at: Utc::now(),
-                    valid_from: None,
-                    valid_until: None,
-                    links: Vec::new(),
-                    metadata: HashMap::new(),
-                };
-                store
-                    .write_record_file(&record)
-                    .expect("healthy record should write");
-            }
-
-            let corrupt_path = store.records_path.join("truncated-record.json");
-            std::fs::write(&corrupt_path, b"{ \"id\": \"broken\", \"content\": \"trunc")
-                .expect("seed truncated record file");
-
-            let records = store
-                .list_user_records()
-                .expect("one corrupt file must not brick the listing");
-
-            assert_eq!(records.len(), 2, "both healthy records should still load");
-            assert!(
-                !corrupt_path.exists(),
-                "corrupt file should be moved out of place"
-            );
-            assert_eq!(quarantined_siblings(&store.records_path).len(), 1);
-        }
-
-        #[test]
-        fn list_session_traces_quarantines_corrupt_trace_and_returns_healthy_ones() {
-            let temp_dir = tempdir().expect("temp dir should be created");
-            let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-            store
-                .append_trace_event(
-                    "session-a",
-                    TraceEventType::RankingRecorded,
-                    json!({"ranking": ["a"]}),
-                )
-                .expect("trace a should append");
-            store
-                .append_trace_event(
-                    "session-b",
-                    TraceEventType::RankingRecorded,
-                    json!({"ranking": ["b"]}),
-                )
-                .expect("trace b should append");
-
-            let corrupt_path = store.traces_path.join("truncated-trace.json");
-            std::fs::write(
-                &corrupt_path,
-                b"{ \"session_id\": \"broken\", \"events\": [",
-            )
-            .expect("seed truncated trace file");
-
-            let traces = store
-                .list_session_traces()
-                .expect("one corrupt file must not brick the listing");
-
-            assert_eq!(traces.len(), 2, "both healthy traces should still load");
-            assert!(
-                !corrupt_path.exists(),
-                "corrupt file should be moved out of place"
-            );
-            assert_eq!(quarantined_siblings(&store.traces_path).len(), 1);
-        }
-
-        #[test]
-        fn list_decision_episodes_quarantines_corrupt_episode_and_returns_healthy_ones() {
-            let temp_dir = tempdir().expect("temp dir should be created");
-            let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-            for i in 0..2 {
-                store
-                    .record_decision_episode(DecisionEpisodeCreate {
-                        id: format!("decision-{i}"),
-                        session_id: "session-1".to_string(),
-                        tile_id: "tile-1".to_string(),
-                        decision: format!("Decision {i}"),
-                        options: vec!["A".to_string(), "B".to_string()],
-                        stakes: None,
-                        initial_leaning: None,
-                        review_date: None,
-                        primitive_assessment: PrimitiveDecisionAssessment::default(),
-                        context_version: None,
-                    })
-                    .expect("healthy decision episode should persist");
-            }
-
-            let corrupt_path = store.decisions_path.join("truncated-decision.json");
-            std::fs::write(
-                &corrupt_path,
-                b"{ \"id\": \"broken\", \"decision\": \"trunc",
-            )
-            .expect("seed truncated decision file");
-
-            let episodes = store
-                .list_decision_episodes()
-                .expect("one corrupt file must not brick the listing");
-
-            assert_eq!(episodes.len(), 2, "both healthy episodes should still load");
-            assert!(
-                !corrupt_path.exists(),
-                "corrupt file should be moved out of place"
-            );
-            assert_eq!(quarantined_siblings(&store.decisions_path).len(), 1);
-        }
-
-        #[test]
-        fn list_constitution_items_quarantines_corrupt_item_and_returns_healthy_ones() {
-            let temp_dir = tempdir().expect("temp dir should be created");
-            let store = TwinStore::new(temp_dir.path().to_path_buf());
-
-            for i in 0..2 {
-                store
-                    .create_constitution_item(ConstitutionItemCreate {
-                        claim: format!("Claim {i}"),
-                        dimension: "general".to_string(),
-                        scope: Vec::new(),
-                        priority: default_record_confidence(),
-                        confidence: default_record_confidence(),
-                        status: ConstitutionStatus::Candidate,
-                        evidence_refs: Vec::new(),
-                        tensions: Vec::new(),
-                        linked_record_ids: Vec::new(),
-                        source: None,
-                    })
-                    .expect("healthy constitution item should persist");
-            }
-
-            let corrupt_path = store.constitution_path.join("truncated-item.json");
-            std::fs::write(&corrupt_path, b"{ \"id\": \"broken\", \"claim\": \"trunc")
-                .expect("seed truncated constitution item file");
-
-            let items = store
-                .list_constitution_items()
-                .expect("one corrupt file must not brick the listing");
-
-            assert_eq!(items.len(), 2, "both healthy items should still load");
-            assert!(
-                !corrupt_path.exists(),
-                "corrupt file should be moved out of place"
-            );
-            assert_eq!(quarantined_siblings(&store.constitution_path).len(), 1);
-        }
-
-        #[test]
-        fn list_action_gaps_quarantines_corrupt_gap_and_returns_healthy_ones() {
-            let temp_dir = tempdir().expect("temp dir should be created");
-            let store = TwinStore::new(temp_dir.path().to_path_buf());
-
-            for i in 0..2 {
-                store
-                    .create_action_gap(ActionGapCreate {
-                        stated_value: format!("Stated {i}"),
-                        revealed_behavior: format!("Revealed {i}"),
-                        driver_hypothesis: None,
-                        somatic_taste_signal: None,
-                        decision_risk: "Some risk".to_string(),
-                        evidence_refs: Vec::new(),
-                        linked_record_ids: Vec::new(),
-                        confidence: default_record_confidence(),
-                        status: ConstitutionStatus::Candidate,
-                    })
-                    .expect("healthy action gap should persist");
-            }
-
-            let corrupt_path = store.action_gaps_path.join("truncated-gap.json");
-            std::fs::write(
-                &corrupt_path,
-                b"{ \"id\": \"broken\", \"stated_value\": \"trunc",
-            )
-            .expect("seed truncated action gap file");
-
-            let gaps = store
-                .list_action_gaps()
-                .expect("one corrupt file must not brick the listing");
-
-            assert_eq!(gaps.len(), 2, "both healthy gaps should still load");
-            assert!(
-                !corrupt_path.exists(),
-                "corrupt file should be moved out of place"
-            );
-            assert_eq!(quarantined_siblings(&store.action_gaps_path).len(), 1);
-        }
-
-        #[test]
-        fn list_reflection_cards_quarantines_corrupt_card_and_returns_healthy_ones() {
-            let temp_dir = tempdir().expect("temp dir should be created");
-            let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-            let episode = store
-                .record_decision_episode(DecisionEpisodeCreate {
-                    id: "decision-1".to_string(),
-                    session_id: "session-1".to_string(),
-                    tile_id: "tile-1".to_string(),
-                    decision: "Should Grafyn build Decision Mirror first?".to_string(),
-                    options: vec!["Decision Mirror".to_string(), "Topology".to_string()],
-                    stakes: None,
-                    initial_leaning: None,
-                    review_date: None,
-                    primitive_assessment: PrimitiveDecisionAssessment::default(),
-                    context_version: None,
-                })
-                .expect("decision episode should persist");
-
-            for i in 0..2 {
-                store
-                    .record_reflection_card(ReflectionCardCreate {
-                        decision_episode_id: episode.id.clone(),
-                        session_id: episode.session_id.clone(),
-                        tile_id: episode.tile_id.clone(),
-                        model_id: "openai/gpt-4".to_string(),
-                        content: format!("## Reflection {i}\nSome content here."),
-                        cited_note_ids: Vec::new(),
-                        cited_user_record_ids: Vec::new(),
-                        cited_constitution_item_ids: Vec::new(),
-                        cited_action_gap_ids: Vec::new(),
-                        evidence_packet: None,
-                    })
-                    .expect("healthy reflection card should persist");
-            }
-
-            let corrupt_path = store.reflections_path.join("truncated-card.json");
-            std::fs::write(&corrupt_path, b"{ \"id\": \"broken\", \"content\": \"trunc")
-                .expect("seed truncated reflection card file");
-
-            let cards = store
-                .list_reflection_cards()
-                .expect("one corrupt file must not brick the listing");
-
-            assert_eq!(cards.len(), 2, "both healthy cards should still load");
-            assert!(
-                !corrupt_path.exists(),
-                "corrupt file should be moved out of place"
-            );
-            assert_eq!(quarantined_siblings(&store.reflections_path).len(), 1);
-        }
-
-        #[test]
-        fn decision_evidence_refs_quarantines_corrupt_trace_and_returns_healthy_refs() {
-            let temp_dir = tempdir().expect("temp dir should be created");
-            let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-            // Two healthy traces, each carrying one event tied to the decision.
-            store
-                .append_trace_event(
-                    "session-a",
-                    TraceEventType::DecisionEpisodeCreated,
-                    json!({"decision_episode_id": "decision-1"}),
-                )
-                .expect("trace a should append");
-            store
-                .append_trace_event(
-                    "session-b",
-                    TraceEventType::FeedbackRecorded,
-                    json!({"decision_episode_id": "decision-1"}),
-                )
-                .expect("trace b should append");
-
-            let corrupt_path = store.traces_path.join("truncated-trace.json");
-            std::fs::write(
-                &corrupt_path,
-                b"{ \"session_id\": \"broken\", \"events\": [",
-            )
-            .expect("seed truncated trace file");
-
-            let refs = store
-                .decision_evidence_refs("decision-1")
-                .expect("one corrupt trace must not brick evidence collection");
-
-            assert_eq!(
-                refs.len(),
-                2,
-                "evidence refs from both healthy traces should still be collected"
-            );
-            let mut session_ids: Vec<_> = refs.iter().map(|r| r.session_id.as_str()).collect();
-            session_ids.sort_unstable();
-            assert_eq!(session_ids, vec!["session-a", "session-b"]);
-            assert!(
-                !corrupt_path.exists(),
-                "corrupt file should be moved out of place"
-            );
-            assert_eq!(quarantined_siblings(&store.traces_path).len(), 1);
-        }
-    }
 }
diff --git a/frontend/src-tauri/src/services/twin/shared.rs b/frontend/src-tauri/src/services/twin/shared.rs
new file mode 100644
index 0000000..52e814b
--- /dev/null
+++ b/frontend/src-tauri/src/services/twin/shared.rs
@@ -0,0 +1,600 @@
+use super::TwinStore;
+use crate::models::note::Note;
+use crate::models::twin::{
+    ActionGap, ActionGapCreate, ConstitutionInferenceSummary, ConstitutionItem,
+    ConstitutionItemCreate, ConstitutionItemUpdate, ConstitutionReviewRequest, ConstitutionSetup,
+    ConstitutionStatus, DecisionEpisode, DecisionEpisodeCreate, DecisionEpisodeWithReflections,
+    DecisionEvidencePacket, DecisionEvidenceSource, DecisionMirrorConfig,
+    DecisionMirrorConfigUpdate, DecisionMirrorWeights, DecisionOutcomeUpdate, EvidenceRef,
+    ExportBundle, ExportFileSummary, MemoryDigestAction, MemoryDigestItem,
+    MemoryDigestReviewRequest, MemoryDigestState, PromotionState, RecordOrigin, ReflectionCard,
+    ReflectionCardCreate, ReflectionScores, ResolvedEvidenceRef, SessionTrace, TraceEvent,
+    TraceEventType, TwinContextRecord, TwinExportRequest, TwinInferenceRunSummary, TwinPrediction,
+    TwinPredictionDraft, TwinReviewRecord, UserRecord, UserRecordCreate, UserRecordKind,
+    UserRecordUpdate,
+};
+#[cfg(test)]
+use crate::models::twin::{DecisionMirrorPreset, PrimitiveDecisionAssessment};
+use crate::services::atomic_io::write_atomic;
+use anyhow::{Context, Result};
+use chrono::Utc;
+use serde::de::DeserializeOwned;
+use serde::Serialize;
+use serde_json::{json, Value};
+use std::collections::hash_map::DefaultHasher;
+use std::collections::HashMap;
+use std::collections::HashSet;
+use std::hash::{Hash, Hasher};
+use std::path::{Path, PathBuf};
+use std::time::{SystemTime, UNIX_EPOCH};
+use walkdir::WalkDir;
+
+const EXCERPT_MAX_CHARS: usize = 220;
+
+/// Outcome of attempting to load a single JSON file within a per-file directory listing.
+pub(super) enum FileLoadOutcome<T> {
+    Loaded(T),
+    /// The file couldn't be read (permissions, transient lock, etc). This is not
+    /// necessarily corruption — the file may be fine — so it must not be quarantined.
+    ReadFailed(anyhow::Error),
+    /// The file was read successfully but its content didn't parse as JSON. This is
+    /// genuine corruption (truncated write, hand-edit gone wrong) and should be
+    /// quarantined so it never bricks the listing again.
+    ParseFailed(anyhow::Error),
+}
+
+pub(super) fn load_json_file<T: DeserializeOwned>(path: &Path) -> FileLoadOutcome<T> {
+    let content = match std::fs::read_to_string(path) {
+        Ok(content) => content,
+        Err(e) => return FileLoadOutcome::ReadFailed(anyhow::Error::new(e)),
+    };
+    match serde_json::from_str::<T>(&content) {
+        Ok(value) => FileLoadOutcome::Loaded(value),
+        Err(e) => FileLoadOutcome::ParseFailed(anyhow::Error::new(e)),
+    }
+}
+
+/// Rename a corrupt file to `{name}.corrupt-{unix-timestamp}` in the same directory so
+/// the bytes aren't lost. Best-effort: if the rename itself fails, log and leave the
+/// file in place (it's still skipped for this pass by the caller).
+fn quarantine_corrupt_file(path: &Path) {
+    let timestamp = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_secs())
+        .unwrap_or(0);
+    let Some(file_name) = path.file_name().and_then(|n| n.to_str()) else {
+        log::error!(
+            "Cannot quarantine file with non-UTF8 name: {}",
+            path.display()
+        );
+        return;
+    };
+    let quarantine_path = path.with_file_name(format!("{file_name}.corrupt-{timestamp}"));
+
+    match std::fs::rename(path, &quarantine_path) {
+        Ok(()) => log::error!(
+            "Quarantined corrupt file {} to {}",
+            path.display(),
+            quarantine_path.display()
+        ),
+        Err(e) => log::error!(
+            "Failed to quarantine corrupt file {} to {}: {}",
+            path.display(),
+            quarantine_path.display(),
+            e
+        ),
+    }
+}
+
+/// Load a single JSON file within a per-file directory-listing loop (record cache fill,
+/// session-trace listing, decision episodes, constitution items, action gaps, reflection
+/// cards). Instead of `?`-propagating and letting one bad file brick the whole listing,
+/// this skips the offending file and returns `None`:
+/// - a parse failure quarantines the file (renamed + logged) so it's never retried, and
+/// - a read failure is skipped without quarantine, since it may be transient/permissions
+///   and the file itself could be perfectly fine.
+pub(super) fn load_or_quarantine<T: DeserializeOwned>(path: &Path, kind: &str) -> Option<T> {
+    match load_json_file::<T>(path) {
+        FileLoadOutcome::Loaded(value) => Some(value),
+        FileLoadOutcome::ReadFailed(e) => {
+            log::error!(
+                "Skipping unreadable {} file {}: {}",
+                kind,
+                path.display(),
+                e
+            );
+            None
+        }
+        FileLoadOutcome::ParseFailed(e) => {
+            log::error!(
+                "Skipping corrupt {} file {}: {} — quarantining",
+                kind,
+                path.display(),
+                e
+            );
+            quarantine_corrupt_file(path);
+            None
+        }
+    }
+}
+
+pub(super) fn lexical_terms(text: &str) -> HashSet<String> {
+    const STOPWORDS: &[&str] = &[
+        "a", "an", "and", "are", "as", "at", "be", "by", "can", "do", "for", "from", "how", "i",
+        "if", "in", "into", "is", "it", "its", "me", "my", "of", "on", "or", "our", "so", "that",
+        "the", "their", "them", "this", "to", "up", "use", "was", "we", "what", "when", "where",
+        "which", "who", "why", "with", "would", "you", "your",
+    ];
+
+    text.split(|ch: char| !ch.is_alphanumeric())
+        .filter_map(|token| {
+            let token = token.trim().to_lowercase();
+            if token.len() < 3 || STOPWORDS.contains(&token.as_str()) {
+                None
+            } else {
+                Some(token)
+            }
+        })
+        .collect()
+}
+
+pub(super) fn evidence_note(event: &TraceEvent) -> Option<String> {
+    match &event.event_type {
+        TraceEventType::NoteExported => payload_string(&event.payload, &["title"]),
+        TraceEventType::FeedbackRecorded
+        | TraceEventType::RankingRecorded
+        | TraceEventType::InsightCaptured => payload_string(&event.payload, &["rationale"]),
+        _ => None,
+    }
+}
+
+pub(super) fn event_text(event: &TraceEvent) -> String {
+    let mut parts = Vec::new();
+    collect_strings(&event.payload, &mut parts);
+    parts.join("\n").to_lowercase()
+}
+
+pub(super) fn collect_strings(value: &Value, out: &mut Vec<String>) {
+    match value {
+        Value::String(value) => out.push(value.clone()),
+        Value::Array(items) => {
+            for item in items {
+                collect_strings(item, out);
+            }
+        }
+        Value::Object(map) => {
+            for value in map.values() {
+                collect_strings(value, out);
+            }
+        }
+        _ => {}
+    }
+}
+
+pub(super) fn extract_event_tile_id(payload: &Value) -> Option<String> {
+    first_payload_string(
+        payload,
+        &[
+            &["tile_id"],
+            &["response", "tile_id"],
+            &["evidence", "tile_id"],
+            &["ranked_responses", "0", "response", "tile_id"],
+        ],
+    )
+}
+
+pub(super) fn extract_event_model_id(payload: &Value) -> Option<String> {
+    first_payload_string(
+        payload,
+        &[
+            &["model_id"],
+            &["response", "model_id"],
+            &["evidence", "model_id"],
+            &["ranked_responses", "0", "response", "model_id"],
+        ],
+    )
+}
+
+pub(super) fn first_payload_string(payload: &Value, paths: &[&[&str]]) -> Option<String> {
+    paths
+        .iter()
+        .find_map(|path| payload_string(payload, path))
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+}
+
+pub(super) fn payload_string(payload: &Value, path: &[&str]) -> Option<String> {
+    let mut current = payload;
+    for part in path {
+        if let Ok(index) = part.parse::<usize>() {
+            current = current.as_array()?.get(index)?;
+        } else {
+            current = current.get(*part)?;
+        }
+    }
+
+    current
+        .as_str()
+        .map(ToOwned::to_owned)
+        .or_else(|| match current {
+            Value::Bool(value) => Some(value.to_string()),
+            Value::Number(value) => Some(value.to_string()),
+            _ => None,
+        })
+}
+
+pub(super) fn value_contains_key(value: &Value, key: &str) -> bool {
+    match value {
+        Value::Object(map) => {
+            map.contains_key(key) || map.values().any(|value| value_contains_key(value, key))
+        }
+        Value::Array(items) => items.iter().any(|value| value_contains_key(value, key)),
+        _ => false,
+    }
+}
+
+pub(super) fn text_contains_any(text: &str, needles: &[&str]) -> bool {
+    let text = text.to_lowercase();
+    needles.iter().any(|needle| text.contains(needle))
+}
+
+pub(super) fn excerpt(content: &str) -> String {
+    if content.chars().count() <= EXCERPT_MAX_CHARS {
+        return content.to_string();
+    }
+
+    let mut excerpt = content.chars().take(EXCERPT_MAX_CHARS).collect::<String>();
+    excerpt.push_str("...");
+    excerpt
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::models::note::{Note, NoteStatus};
+    use crate::models::twin::{
+        default_record_confidence, PromotionState, RecordLink, RecordLinkType, UserRecordKind,
+    };
+    use tempfile::tempdir;
+
+    /// Corrupt-file quarantine sweep (Task 1.5): a directory listing must never brick
+    /// entirely because of one unparsable file. Covers the two sites named in the audit
+    /// (`ensure_record_cache`, `list_session_traces`) plus every sibling loop found with
+    /// the same `?`-propagate-on-per-file-parse-failure pattern (`list_decision_episodes`,
+    /// `list_constitution_items`, `list_action_gaps`, `list_reflection_cards`).
+    mod corrupt_file_quarantine {
+        use super::*;
+
+        /// Return the `.corrupt-*` sibling files in `dir`, if any.
+        fn quarantined_siblings(dir: &Path) -> Vec<std::path::PathBuf> {
+            std::fs::read_dir(dir)
+                .expect("read dir")
+                .filter_map(|entry| entry.ok())
+                .map(|entry| entry.path())
+                .filter(|p| {
+                    p.file_name()
+                        .and_then(|n| n.to_str())
+                        .map(|n| n.contains(".corrupt-"))
+                        .unwrap_or(false)
+                })
+                .collect()
+        }
+
+        #[test]
+        fn load_or_quarantine_skips_unreadable_file_without_quarantining() {
+            let temp_dir = tempdir().expect("temp dir should be created");
+            // A directory standing in for a file triggers a genuine read error (not a
+            // parse error) deterministically, without relying on OS permission quirks.
+            let bogus_path = temp_dir.path().join("not-a-file.json");
+            std::fs::create_dir(&bogus_path).expect("create directory standing in for a file");
+
+            let result = load_or_quarantine::<UserRecord>(&bogus_path, "record");
+            assert!(result.is_none());
+            assert!(
+                bogus_path.exists(),
+                "a read failure may be transient (permissions, AV lock) — the path must be left untouched"
+            );
+            assert!(quarantined_siblings(temp_dir.path()).is_empty());
+        }
+
+        #[test]
+        fn list_user_records_quarantines_corrupt_record_and_returns_healthy_ones() {
+            let temp_dir = tempdir().expect("temp dir should be created");
+            let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+            for i in 0..2 {
+                let record = UserRecord {
+                    id: format!("record-{i}"),
+                    kind: UserRecordKind::Preference,
+                    content: format!("Healthy record {i}"),
+                    evidence_refs: Vec::new(),
+                    confidence: default_record_confidence(),
+                    origin: RecordOrigin::User,
+                    promotion_state: PromotionState::default_for_origin(&RecordOrigin::User),
+                    created_at: Utc::now(),
+                    updated_at: Utc::now(),
+                    valid_from: None,
+                    valid_until: None,
+                    links: Vec::new(),
+                    metadata: HashMap::new(),
+                };
+                store
+                    .write_record_file(&record)
+                    .expect("healthy record should write");
+            }
+
+            let corrupt_path = store.records_path.join("truncated-record.json");
+            std::fs::write(&corrupt_path, b"{ \"id\": \"broken\", \"content\": \"trunc")
+                .expect("seed truncated record file");
+
+            let records = store
+                .list_user_records()
+                .expect("one corrupt file must not brick the listing");
+
+            assert_eq!(records.len(), 2, "both healthy records should still load");
+            assert!(
+                !corrupt_path.exists(),
+                "corrupt file should be moved out of place"
+            );
+            assert_eq!(quarantined_siblings(&store.records_path).len(), 1);
+        }
+
+        #[test]
+        fn list_session_traces_quarantines_corrupt_trace_and_returns_healthy_ones() {
+            let temp_dir = tempdir().expect("temp dir should be created");
+            let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+            store
+                .append_trace_event(
+                    "session-a",
+                    TraceEventType::RankingRecorded,
+                    json!({"ranking": ["a"]}),
+                )
+                .expect("trace a should append");
+            store
+                .append_trace_event(
+                    "session-b",
+                    TraceEventType::RankingRecorded,
+                    json!({"ranking": ["b"]}),
+                )
+                .expect("trace b should append");
+
+            let corrupt_path = store.traces_path.join("truncated-trace.json");
+            std::fs::write(
+                &corrupt_path,
+                b"{ \"session_id\": \"broken\", \"events\": [",
+            )
+            .expect("seed truncated trace file");
+
+            let traces = store
+                .list_session_traces()
+                .expect("one corrupt file must not brick the listing");
+
+            assert_eq!(traces.len(), 2, "both healthy traces should still load");
+            assert!(
+                !corrupt_path.exists(),
+                "corrupt file should be moved out of place"
+            );
+            assert_eq!(quarantined_siblings(&store.traces_path).len(), 1);
+        }
+
+        #[test]
+        fn list_decision_episodes_quarantines_corrupt_episode_and_returns_healthy_ones() {
+            let temp_dir = tempdir().expect("temp dir should be created");
+            let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+            for i in 0..2 {
+                store
+                    .record_decision_episode(DecisionEpisodeCreate {
+                        id: format!("decision-{i}"),
+                        session_id: "session-1".to_string(),
+                        tile_id: "tile-1".to_string(),
+                        decision: format!("Decision {i}"),
+                        options: vec!["A".to_string(), "B".to_string()],
+                        stakes: None,
+                        initial_leaning: None,
+                        review_date: None,
+                        primitive_assessment: PrimitiveDecisionAssessment::default(),
+                        context_version: None,
+                    })
+                    .expect("healthy decision episode should persist");
+            }
+
+            let corrupt_path = store.decisions_path.join("truncated-decision.json");
+            std::fs::write(
+                &corrupt_path,
+                b"{ \"id\": \"broken\", \"decision\": \"trunc",
+            )
+            .expect("seed truncated decision file");
+
+            let episodes = store
+                .list_decision_episodes()
+                .expect("one corrupt file must not brick the listing");
+
+            assert_eq!(episodes.len(), 2, "both healthy episodes should still load");
+            assert!(
+                !corrupt_path.exists(),
+                "corrupt file should be moved out of place"
+            );
+            assert_eq!(quarantined_siblings(&store.decisions_path).len(), 1);
+        }
+
+        #[test]
+        fn list_constitution_items_quarantines_corrupt_item_and_returns_healthy_ones() {
+            let temp_dir = tempdir().expect("temp dir should be created");
+            let store = TwinStore::new(temp_dir.path().to_path_buf());
+
+            for i in 0..2 {
+                store
+                    .create_constitution_item(ConstitutionItemCreate {
+                        claim: format!("Claim {i}"),
+                        dimension: "general".to_string(),
+                        scope: Vec::new(),
+                        priority: default_record_confidence(),
+                        confidence: default_record_confidence(),
+                        status: ConstitutionStatus::Candidate,
+                        evidence_refs: Vec::new(),
+                        tensions: Vec::new(),
+                        linked_record_ids: Vec::new(),
+                        source: None,
+                    })
+                    .expect("healthy constitution item should persist");
+            }
+
+            let corrupt_path = store.constitution_path.join("truncated-item.json");
+            std::fs::write(&corrupt_path, b"{ \"id\": \"broken\", \"claim\": \"trunc")
+                .expect("seed truncated constitution item file");
+
+            let items = store
+                .list_constitution_items()
+                .expect("one corrupt file must not brick the listing");
+
+            assert_eq!(items.len(), 2, "both healthy items should still load");
+            assert!(
+                !corrupt_path.exists(),
+                "corrupt file should be moved out of place"
+            );
+            assert_eq!(quarantined_siblings(&store.constitution_path).len(), 1);
+        }
+
+        #[test]
+        fn list_action_gaps_quarantines_corrupt_gap_and_returns_healthy_ones() {
+            let temp_dir = tempdir().expect("temp dir should be created");
+            let store = TwinStore::new(temp_dir.path().to_path_buf());
+
+            for i in 0..2 {
+                store
+                    .create_action_gap(ActionGapCreate {
+                        stated_value: format!("Stated {i}"),
+                        revealed_behavior: format!("Revealed {i}"),
+                        driver_hypothesis: None,
+                        somatic_taste_signal: None,
+                        decision_risk: "Some risk".to_string(),
+                        evidence_refs: Vec::new(),
+                        linked_record_ids: Vec::new(),
+                        confidence: default_record_confidence(),
+                        status: ConstitutionStatus::Candidate,
+                    })
+                    .expect("healthy action gap should persist");
+            }
+
+            let corrupt_path = store.action_gaps_path.join("truncated-gap.json");
+            std::fs::write(
+                &corrupt_path,
+                b"{ \"id\": \"broken\", \"stated_value\": \"trunc",
+            )
+            .expect("seed truncated action gap file");
+
+            let gaps = store
+                .list_action_gaps()
+                .expect("one corrupt file must not brick the listing");
+
+            assert_eq!(gaps.len(), 2, "both healthy gaps should still load");
+            assert!(
+                !corrupt_path.exists(),
+                "corrupt file should be moved out of place"
+            );
+            assert_eq!(quarantined_siblings(&store.action_gaps_path).len(), 1);
+        }
+
+        #[test]
+        fn list_reflection_cards_quarantines_corrupt_card_and_returns_healthy_ones() {
+            let temp_dir = tempdir().expect("temp dir should be created");
+            let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+            let episode = store
+                .record_decision_episode(DecisionEpisodeCreate {
+                    id: "decision-1".to_string(),
+                    session_id: "session-1".to_string(),
+                    tile_id: "tile-1".to_string(),
+                    decision: "Should Grafyn build Decision Mirror first?".to_string(),
+                    options: vec!["Decision Mirror".to_string(), "Topology".to_string()],
+                    stakes: None,
+                    initial_leaning: None,
+                    review_date: None,
+                    primitive_assessment: PrimitiveDecisionAssessment::default(),
+                    context_version: None,
+                })
+                .expect("decision episode should persist");
+
+            for i in 0..2 {
+                store
+                    .record_reflection_card(ReflectionCardCreate {
+                        decision_episode_id: episode.id.clone(),
+                        session_id: episode.session_id.clone(),
+                        tile_id: episode.tile_id.clone(),
+                        model_id: "openai/gpt-4".to_string(),
+                        content: format!("## Reflection {i}\nSome content here."),
+                        cited_note_ids: Vec::new(),
+                        cited_user_record_ids: Vec::new(),
+                        cited_constitution_item_ids: Vec::new(),
+                        cited_action_gap_ids: Vec::new(),
+                        evidence_packet: None,
+                    })
+                    .expect("healthy reflection card should persist");
+            }
+
+            let corrupt_path = store.reflections_path.join("truncated-card.json");
+            std::fs::write(&corrupt_path, b"{ \"id\": \"broken\", \"content\": \"trunc")
+                .expect("seed truncated reflection card file");
+
+            let cards = store
+                .list_reflection_cards()
+                .expect("one corrupt file must not brick the listing");
+
+            assert_eq!(cards.len(), 2, "both healthy cards should still load");
+            assert!(
+                !corrupt_path.exists(),
+                "corrupt file should be moved out of place"
+            );
+            assert_eq!(quarantined_siblings(&store.reflections_path).len(), 1);
+        }
+
+        #[test]
+        fn decision_evidence_refs_quarantines_corrupt_trace_and_returns_healthy_refs() {
+            let temp_dir = tempdir().expect("temp dir should be created");
+            let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+            // Two healthy traces, each carrying one event tied to the decision.
+            store
+                .append_trace_event(
+                    "session-a",
+                    TraceEventType::DecisionEpisodeCreated,
+                    json!({"decision_episode_id": "decision-1"}),
+                )
+                .expect("trace a should append");
+            store
+                .append_trace_event(
+                    "session-b",
+                    TraceEventType::FeedbackRecorded,
+                    json!({"decision_episode_id": "decision-1"}),
+                )
+                .expect("trace b should append");
+
+            let corrupt_path = store.traces_path.join("truncated-trace.json");
+            std::fs::write(
+                &corrupt_path,
+                b"{ \"session_id\": \"broken\", \"events\": [",
+            )
+            .expect("seed truncated trace file");
+
+            let refs = store
+                .decision_evidence_refs("decision-1")
+                .expect("one corrupt trace must not brick evidence collection");
+
+            assert_eq!(
+                refs.len(),
+                2,
+                "evidence refs from both healthy traces should still be collected"
+            );
+            let mut session_ids: Vec<_> = refs.iter().map(|r| r.session_id.as_str()).collect();
+            session_ids.sort_unstable();
+            assert_eq!(session_ids, vec!["session-a", "session-b"]);
+            assert!(
+                !corrupt_path.exists(),
+                "corrupt file should be moved out of place"
+            );
+            assert_eq!(quarantined_siblings(&store.traces_path).len(), 1);
+        }
+    }
+}

From 07272e4814af89163738168cbcada495ebe9deaf Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 15:49:41 +0800
Subject: [PATCH 10/30] refactor: extract twin::traces

Moves session trace append/read (append_trace_event, get_session_trace,
get_or_create_trace_mut), the session-trace listing loop, and
evidence-ref resolution (resolve_evidence_refs, resolve_event_evidence,
event_summary) into services/twin/traces.rs. list_session_traces,
resolve_evidence_refs, trace_file_path, and read_trace_file are marked
pub(super) since decisions.rs (decision_feedback_events) and
records.rs/digest.rs (evidence resolution) still call them across
module boundaries. Verbatim move; tests move with their code.
---
 frontend/src-tauri/src/services/twin/mod.rs   | 321 +--------------
 .../src-tauri/src/services/twin/traces.rs     | 366 ++++++++++++++++++
 2 files changed, 367 insertions(+), 320 deletions(-)
 create mode 100644 frontend/src-tauri/src/services/twin/traces.rs

diff --git a/frontend/src-tauri/src/services/twin/mod.rs b/frontend/src-tauri/src/services/twin/mod.rs
index 195ee13..bebc8ac 100644
--- a/frontend/src-tauri/src/services/twin/mod.rs
+++ b/frontend/src-tauri/src/services/twin/mod.rs
@@ -29,6 +29,7 @@ use std::time::{SystemTime, UNIX_EPOCH};
 use walkdir::WalkDir;
 
 mod shared;
+mod traces;
 
 use shared::*;
 
@@ -49,117 +50,6 @@ enum ExportSplit {
     Holdout,
 }
 
-fn resolve_event_evidence(
-    trace: &SessionTrace,
-    event: &TraceEvent,
-    evidence_ref: &EvidenceRef,
-) -> ResolvedEvidenceRef {
-    let prompt_excerpt = first_payload_string(
-        &event.payload,
-        &[
-            &["prompt"],
-            &["response", "prompt"],
-            &["evidence", "prompt"],
-            &["ranked_responses", "0", "response", "prompt"],
-        ],
-    )
-    .map(|value| excerpt(&value));
-
-    let response_excerpt = first_payload_string(
-        &event.payload,
-        &[
-            &["content"],
-            &["response", "response_content"],
-            &["response", "response_excerpt"],
-            &["evidence", "response_content"],
-            &["ranked_responses", "0", "response", "response_content"],
-            &["ranked_responses", "0", "response_excerpt"],
-        ],
-    )
-    .map(|value| excerpt(&value));
-
-    let model_name = first_payload_string(
-        &event.payload,
-        &[
-            &["model_name"],
-            &["response", "model_name"],
-            &["evidence", "model_name"],
-            &["ranked_responses", "0", "response", "model_name"],
-        ],
-    );
-
-    ResolvedEvidenceRef {
-        trace_id: evidence_ref.trace_id.clone(),
-        event_id: event.id.clone(),
-        session_id: trace.session_id.clone(),
-        tile_id: evidence_ref
-            .tile_id
-            .clone()
-            .or_else(|| extract_event_tile_id(&event.payload)),
-        model_id: evidence_ref
-            .model_id
-            .clone()
-            .or_else(|| extract_event_model_id(&event.payload)),
-        event_type: event.event_type.clone(),
-        created_at: event.created_at,
-        note: evidence_ref.note.clone(),
-        summary: Some(event_summary(
-            event,
-            prompt_excerpt.as_deref(),
-            response_excerpt.as_deref(),
-        )),
-        prompt_excerpt,
-        response_excerpt,
-        model_name,
-        source_type: evidence_ref.source_type.clone(),
-        source_id: evidence_ref.source_id.clone(),
-        source_label: evidence_ref.source_label.clone(),
-        excerpt: evidence_ref.excerpt.clone(),
-        speaker_role: evidence_ref.speaker_role.clone(),
-        payload: event.payload.clone(),
-    }
-}
-
-fn event_summary(
-    event: &TraceEvent,
-    prompt_excerpt: Option<&str>,
-    response_excerpt: Option<&str>,
-) -> String {
-    match &event.event_type {
-        TraceEventType::PromptSubmitted => {
-            format!(
-                "Prompt submitted: {}",
-                prompt_excerpt.unwrap_or("no prompt excerpt")
-            )
-        }
-        TraceEventType::ResponseCompleted => {
-            format!(
-                "Response completed: {}",
-                response_excerpt.unwrap_or("no response excerpt")
-            )
-        }
-        TraceEventType::FeedbackRecorded => {
-            let feedback_type = payload_string(&event.payload, &["feedback_type"])
-                .unwrap_or_else(|| "feedback".to_string());
-            format!("{} feedback recorded", feedback_type)
-        }
-        TraceEventType::RankingRecorded => "Response ranking recorded".to_string(),
-        TraceEventType::InsightCaptured => "Explicit twin insight captured".to_string(),
-        TraceEventType::ModelsAdded => "Additional models added for comparison".to_string(),
-        TraceEventType::DebateStarted => "Model debate started".to_string(),
-        TraceEventType::DebateContinued => "Model debate continued".to_string(),
-        TraceEventType::NoteExported => {
-            let title =
-                payload_string(&event.payload, &["title"]).unwrap_or_else(|| "note".to_string());
-            format!("Canvas exported to note: {}", title)
-        }
-        TraceEventType::NoteCanonicalPromoted => "Note promoted to canonical".to_string(),
-        TraceEventType::NoteCreated => "Note created".to_string(),
-        TraceEventType::NoteUpdated => "Note updated".to_string(),
-        _ => format!("{:?}", &event.event_type),
-    }
-}
-
 #[derive(Debug, Clone)]
 struct InferredRecordDraft {
     inference_key: String,
@@ -1823,130 +1713,6 @@ impl TwinStore {
         Ok(())
     }
 
-    pub fn append_trace_event(
-        &mut self,
-        session_id: &str,
-        event_type: TraceEventType,
-        payload: serde_json::Value,
-    ) -> Result<TraceEvent> {
-        Self::validate_file_id(session_id)?;
-        let now = Utc::now();
-        let event = TraceEvent {
-            id: uuid::Uuid::new_v4().to_string(),
-            event_type,
-            created_at: now,
-            payload,
-        };
-
-        let trace = self.get_or_create_trace_mut(session_id)?;
-        trace.updated_at = now;
-        trace.events.push(event.clone());
-        let trace = trace.clone();
-        self.write_trace_file(&trace)?;
-
-        Ok(event)
-    }
-
-    pub fn get_session_trace(&mut self, session_id: &str) -> Result<SessionTrace> {
-        Self::validate_file_id(session_id)?;
-        if let Some(trace) = self.trace_cache.get(session_id) {
-            return Ok(trace.clone());
-        }
-
-        let path = self.trace_file_path(session_id);
-        if !path.exists() {
-            let trace = SessionTrace::new(session_id);
-            self.trace_cache
-                .insert(session_id.to_string(), trace.clone());
-            return Ok(trace);
-        }
-
-        let trace = self.read_trace_file(&path)?;
-        self.trace_cache
-            .insert(session_id.to_string(), trace.clone());
-        Ok(trace)
-    }
-
-    pub(super) fn list_session_traces(&mut self) -> Result<Vec<SessionTrace>> {
-        for entry in WalkDir::new(&self.traces_path)
-            .min_depth(1)
-            .max_depth(1)
-            .into_iter()
-            .filter_map(|entry| entry.ok())
-        {
-            let path = entry.path();
-            if path.extension().is_some_and(|ext| ext == "json") {
-                if let Some(trace) = load_or_quarantine::<SessionTrace>(path, "trace") {
-                    self.trace_cache.insert(trace.session_id.clone(), trace);
-                }
-            }
-        }
-
-        let mut traces = self.trace_cache.values().cloned().collect::<Vec<_>>();
-        traces.sort_by(|a, b| a.session_id.cmp(&b.session_id));
-        Ok(traces)
-    }
-
-    pub(super) fn resolve_evidence_refs(
-        &mut self,
-        refs: &[EvidenceRef],
-    ) -> Result<Vec<ResolvedEvidenceRef>> {
-        let mut resolved = Vec::new();
-        for evidence_ref in refs {
-            let trace_id = if evidence_ref.trace_id.trim().is_empty() {
-                &evidence_ref.session_id
-            } else {
-                &evidence_ref.trace_id
-            };
-            let trace = self.get_session_trace(trace_id)?;
-            let Some(event) = trace
-                .events
-                .iter()
-                .find(|event| event.id == evidence_ref.event_id)
-            else {
-                continue;
-            };
-
-            resolved.push(resolve_event_evidence(&trace, event, evidence_ref));
-        }
-
-        resolved.sort_by(|a, b| b.created_at.cmp(&a.created_at));
-        Ok(resolved)
-    }
-
-    fn get_or_create_trace_mut(&mut self, session_id: &str) -> Result<&mut SessionTrace> {
-        if !self.trace_cache.contains_key(session_id) {
-            let path = self.trace_file_path(session_id);
-            let trace = if path.exists() {
-                self.read_trace_file(&path)?
-            } else {
-                SessionTrace::new(session_id)
-            };
-            self.trace_cache.insert(session_id.to_string(), trace);
-        }
-
-        Ok(self
-            .trace_cache
-            .get_mut(session_id)
-            .expect("trace inserted"))
-    }
-
-    pub(super) fn trace_file_path(&self, session_id: &str) -> PathBuf {
-        self.traces_path.join(format!("{}.json", session_id))
-    }
-
-    pub(super) fn read_trace_file(&self, path: &Path) -> Result<SessionTrace> {
-        let content = std::fs::read_to_string(path)
-            .with_context(|| format!("Failed to read trace file: {}", path.display()))?;
-        serde_json::from_str(&content)
-            .with_context(|| format!("Failed to parse trace file: {}", path.display()))
-    }
-
-    fn write_trace_file(&self, trace: &SessionTrace) -> Result<()> {
-        let path = self.trace_file_path(&trace.session_id);
-        self.write_pretty_json(&path, trace)
-    }
-
     pub fn list_user_records(&mut self) -> Result<Vec<UserRecord>> {
         self.ensure_record_cache()?;
         let mut records: Vec<UserRecord> = self.record_cache.values().cloned().collect();
@@ -4392,91 +4158,6 @@ mod tests {
     use tempfile::tempdir;
 
     use crate::models::twin::ConstitutionStatus;
-    #[test]
-    fn evidence_resolution_returns_trace_session_model_and_excerpts() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        let event = store
-            .append_trace_event(
-                "session-1",
-                TraceEventType::ResponseCompleted,
-                serde_json::json!({
-                    "tile_id": "tile-1",
-                    "model_id": "openai/gpt-4o",
-                    "model_name": "GPT-4o",
-                    "prompt": "Implement this with tests.",
-                    "content": "Updated frontend/src/api/client.js and ran npm run test:run.",
-                }),
-            )
-            .expect("trace event should append");
-        let record = store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::Preference,
-                content: "Prefers implementation detail.".to_string(),
-                origin: RecordOrigin::Inferred,
-                evidence_refs: vec![EvidenceRef {
-                    trace_id: "session-1".to_string(),
-                    event_id: event.id,
-                    session_id: "session-1".to_string(),
-                    tile_id: Some("tile-1".to_string()),
-                    model_id: Some("openai/gpt-4o".to_string()),
-                    note: None,
-                    source_type: Some("behavior".to_string()),
-                    source_id: None,
-                    source_label: None,
-                    excerpt: None,
-                    speaker_role: None,
-                }],
-                confidence: 0.8,
-                promotion_state: Some(PromotionState::Candidate),
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
-            })
-            .expect("record should be created");
-
-        let evidence = store
-            .resolve_user_record_evidence(&record.id)
-            .expect("evidence should resolve");
-
-        assert_eq!(evidence.len(), 1);
-        assert_eq!(evidence[0].session_id, "session-1");
-        assert_eq!(evidence[0].model_id.as_deref(), Some("openai/gpt-4o"));
-        assert_eq!(
-            evidence[0].prompt_excerpt.as_deref(),
-            Some("Implement this with tests.")
-        );
-        assert!(evidence[0]
-            .response_excerpt
-            .as_deref()
-            .unwrap_or_default()
-            .contains("frontend/src/api/client.js"));
-    }
-
-    #[test]
-    fn append_trace_event_creates_trace_file() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        let event = store
-            .append_trace_event(
-                "session-1",
-                TraceEventType::PromptSubmitted,
-                serde_json::json!({ "prompt": "hello" }),
-            )
-            .expect("trace event should append");
-
-        let trace = store
-            .get_session_trace("session-1")
-            .expect("trace should load");
-
-        assert_eq!(trace.events.len(), 1);
-        assert_eq!(trace.events[0].id, event.id);
-        assert_eq!(trace.events[0].event_type, TraceEventType::PromptSubmitted);
-    }
-
     #[test]
     fn user_record_writes_are_atomic_with_no_tmp_litter() {
         let temp_dir = tempdir().expect("temp dir should be created");
diff --git a/frontend/src-tauri/src/services/twin/traces.rs b/frontend/src-tauri/src/services/twin/traces.rs
new file mode 100644
index 0000000..4ff2487
--- /dev/null
+++ b/frontend/src-tauri/src/services/twin/traces.rs
@@ -0,0 +1,366 @@
+use super::shared::{
+    excerpt, extract_event_model_id, extract_event_tile_id, first_payload_string,
+    load_or_quarantine, payload_string,
+};
+use super::TwinStore;
+use crate::models::note::Note;
+use crate::models::twin::{
+    ActionGap, ActionGapCreate, ConstitutionInferenceSummary, ConstitutionItem,
+    ConstitutionItemCreate, ConstitutionItemUpdate, ConstitutionReviewRequest, ConstitutionSetup,
+    ConstitutionStatus, DecisionEpisode, DecisionEpisodeCreate, DecisionEpisodeWithReflections,
+    DecisionEvidencePacket, DecisionEvidenceSource, DecisionMirrorConfig,
+    DecisionMirrorConfigUpdate, DecisionMirrorWeights, DecisionOutcomeUpdate, EvidenceRef,
+    ExportBundle, ExportFileSummary, MemoryDigestAction, MemoryDigestItem,
+    MemoryDigestReviewRequest, MemoryDigestState, PromotionState, RecordOrigin, ReflectionCard,
+    ReflectionCardCreate, ReflectionScores, ResolvedEvidenceRef, SessionTrace, TraceEvent,
+    TraceEventType, TwinContextRecord, TwinExportRequest, TwinInferenceRunSummary, TwinPrediction,
+    TwinPredictionDraft, TwinReviewRecord, UserRecord, UserRecordCreate, UserRecordKind,
+    UserRecordUpdate,
+};
+#[cfg(test)]
+use crate::models::twin::{DecisionMirrorPreset, PrimitiveDecisionAssessment};
+use crate::services::atomic_io::write_atomic;
+use anyhow::{Context, Result};
+use chrono::Utc;
+use serde::de::DeserializeOwned;
+use serde::Serialize;
+use serde_json::{json, Value};
+use std::collections::hash_map::DefaultHasher;
+use std::collections::HashMap;
+use std::collections::HashSet;
+use std::hash::{Hash, Hasher};
+use std::path::{Path, PathBuf};
+use std::time::{SystemTime, UNIX_EPOCH};
+use walkdir::WalkDir;
+
+fn resolve_event_evidence(
+    trace: &SessionTrace,
+    event: &TraceEvent,
+    evidence_ref: &EvidenceRef,
+) -> ResolvedEvidenceRef {
+    let prompt_excerpt = first_payload_string(
+        &event.payload,
+        &[
+            &["prompt"],
+            &["response", "prompt"],
+            &["evidence", "prompt"],
+            &["ranked_responses", "0", "response", "prompt"],
+        ],
+    )
+    .map(|value| excerpt(&value));
+
+    let response_excerpt = first_payload_string(
+        &event.payload,
+        &[
+            &["content"],
+            &["response", "response_content"],
+            &["response", "response_excerpt"],
+            &["evidence", "response_content"],
+            &["ranked_responses", "0", "response", "response_content"],
+            &["ranked_responses", "0", "response_excerpt"],
+        ],
+    )
+    .map(|value| excerpt(&value));
+
+    let model_name = first_payload_string(
+        &event.payload,
+        &[
+            &["model_name"],
+            &["response", "model_name"],
+            &["evidence", "model_name"],
+            &["ranked_responses", "0", "response", "model_name"],
+        ],
+    );
+
+    ResolvedEvidenceRef {
+        trace_id: evidence_ref.trace_id.clone(),
+        event_id: event.id.clone(),
+        session_id: trace.session_id.clone(),
+        tile_id: evidence_ref
+            .tile_id
+            .clone()
+            .or_else(|| extract_event_tile_id(&event.payload)),
+        model_id: evidence_ref
+            .model_id
+            .clone()
+            .or_else(|| extract_event_model_id(&event.payload)),
+        event_type: event.event_type.clone(),
+        created_at: event.created_at,
+        note: evidence_ref.note.clone(),
+        summary: Some(event_summary(
+            event,
+            prompt_excerpt.as_deref(),
+            response_excerpt.as_deref(),
+        )),
+        prompt_excerpt,
+        response_excerpt,
+        model_name,
+        source_type: evidence_ref.source_type.clone(),
+        source_id: evidence_ref.source_id.clone(),
+        source_label: evidence_ref.source_label.clone(),
+        excerpt: evidence_ref.excerpt.clone(),
+        speaker_role: evidence_ref.speaker_role.clone(),
+        payload: event.payload.clone(),
+    }
+}
+
+fn event_summary(
+    event: &TraceEvent,
+    prompt_excerpt: Option<&str>,
+    response_excerpt: Option<&str>,
+) -> String {
+    match &event.event_type {
+        TraceEventType::PromptSubmitted => {
+            format!(
+                "Prompt submitted: {}",
+                prompt_excerpt.unwrap_or("no prompt excerpt")
+            )
+        }
+        TraceEventType::ResponseCompleted => {
+            format!(
+                "Response completed: {}",
+                response_excerpt.unwrap_or("no response excerpt")
+            )
+        }
+        TraceEventType::FeedbackRecorded => {
+            let feedback_type = payload_string(&event.payload, &["feedback_type"])
+                .unwrap_or_else(|| "feedback".to_string());
+            format!("{} feedback recorded", feedback_type)
+        }
+        TraceEventType::RankingRecorded => "Response ranking recorded".to_string(),
+        TraceEventType::InsightCaptured => "Explicit twin insight captured".to_string(),
+        TraceEventType::ModelsAdded => "Additional models added for comparison".to_string(),
+        TraceEventType::DebateStarted => "Model debate started".to_string(),
+        TraceEventType::DebateContinued => "Model debate continued".to_string(),
+        TraceEventType::NoteExported => {
+            let title =
+                payload_string(&event.payload, &["title"]).unwrap_or_else(|| "note".to_string());
+            format!("Canvas exported to note: {}", title)
+        }
+        TraceEventType::NoteCanonicalPromoted => "Note promoted to canonical".to_string(),
+        TraceEventType::NoteCreated => "Note created".to_string(),
+        TraceEventType::NoteUpdated => "Note updated".to_string(),
+        _ => format!("{:?}", &event.event_type),
+    }
+}
+
+impl TwinStore {
+    pub fn append_trace_event(
+        &mut self,
+        session_id: &str,
+        event_type: TraceEventType,
+        payload: serde_json::Value,
+    ) -> Result<TraceEvent> {
+        Self::validate_file_id(session_id)?;
+        let now = Utc::now();
+        let event = TraceEvent {
+            id: uuid::Uuid::new_v4().to_string(),
+            event_type,
+            created_at: now,
+            payload,
+        };
+
+        let trace = self.get_or_create_trace_mut(session_id)?;
+        trace.updated_at = now;
+        trace.events.push(event.clone());
+        let trace = trace.clone();
+        self.write_trace_file(&trace)?;
+
+        Ok(event)
+    }
+
+    pub fn get_session_trace(&mut self, session_id: &str) -> Result<SessionTrace> {
+        Self::validate_file_id(session_id)?;
+        if let Some(trace) = self.trace_cache.get(session_id) {
+            return Ok(trace.clone());
+        }
+
+        let path = self.trace_file_path(session_id);
+        if !path.exists() {
+            let trace = SessionTrace::new(session_id);
+            self.trace_cache
+                .insert(session_id.to_string(), trace.clone());
+            return Ok(trace);
+        }
+
+        let trace = self.read_trace_file(&path)?;
+        self.trace_cache
+            .insert(session_id.to_string(), trace.clone());
+        Ok(trace)
+    }
+
+    pub(super) fn list_session_traces(&mut self) -> Result<Vec<SessionTrace>> {
+        for entry in WalkDir::new(&self.traces_path)
+            .min_depth(1)
+            .max_depth(1)
+            .into_iter()
+            .filter_map(|entry| entry.ok())
+        {
+            let path = entry.path();
+            if path.extension().is_some_and(|ext| ext == "json") {
+                if let Some(trace) = load_or_quarantine::<SessionTrace>(path, "trace") {
+                    self.trace_cache.insert(trace.session_id.clone(), trace);
+                }
+            }
+        }
+
+        let mut traces = self.trace_cache.values().cloned().collect::<Vec<_>>();
+        traces.sort_by(|a, b| a.session_id.cmp(&b.session_id));
+        Ok(traces)
+    }
+
+    pub(super) fn resolve_evidence_refs(
+        &mut self,
+        refs: &[EvidenceRef],
+    ) -> Result<Vec<ResolvedEvidenceRef>> {
+        let mut resolved = Vec::new();
+        for evidence_ref in refs {
+            let trace_id = if evidence_ref.trace_id.trim().is_empty() {
+                &evidence_ref.session_id
+            } else {
+                &evidence_ref.trace_id
+            };
+            let trace = self.get_session_trace(trace_id)?;
+            let Some(event) = trace
+                .events
+                .iter()
+                .find(|event| event.id == evidence_ref.event_id)
+            else {
+                continue;
+            };
+
+            resolved.push(resolve_event_evidence(&trace, event, evidence_ref));
+        }
+
+        resolved.sort_by(|a, b| b.created_at.cmp(&a.created_at));
+        Ok(resolved)
+    }
+
+    fn get_or_create_trace_mut(&mut self, session_id: &str) -> Result<&mut SessionTrace> {
+        if !self.trace_cache.contains_key(session_id) {
+            let path = self.trace_file_path(session_id);
+            let trace = if path.exists() {
+                self.read_trace_file(&path)?
+            } else {
+                SessionTrace::new(session_id)
+            };
+            self.trace_cache.insert(session_id.to_string(), trace);
+        }
+
+        Ok(self
+            .trace_cache
+            .get_mut(session_id)
+            .expect("trace inserted"))
+    }
+
+    pub(super) fn trace_file_path(&self, session_id: &str) -> PathBuf {
+        self.traces_path.join(format!("{}.json", session_id))
+    }
+
+    pub(super) fn read_trace_file(&self, path: &Path) -> Result<SessionTrace> {
+        let content = std::fs::read_to_string(path)
+            .with_context(|| format!("Failed to read trace file: {}", path.display()))?;
+        serde_json::from_str(&content)
+            .with_context(|| format!("Failed to parse trace file: {}", path.display()))
+    }
+
+    fn write_trace_file(&self, trace: &SessionTrace) -> Result<()> {
+        let path = self.trace_file_path(&trace.session_id);
+        self.write_pretty_json(&path, trace)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::models::note::{Note, NoteStatus};
+    use crate::models::twin::{
+        default_record_confidence, PromotionState, RecordLink, RecordLinkType, UserRecordKind,
+    };
+    use tempfile::tempdir;
+
+    #[test]
+    fn evidence_resolution_returns_trace_session_model_and_excerpts() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        let event = store
+            .append_trace_event(
+                "session-1",
+                TraceEventType::ResponseCompleted,
+                serde_json::json!({
+                    "tile_id": "tile-1",
+                    "model_id": "openai/gpt-4o",
+                    "model_name": "GPT-4o",
+                    "prompt": "Implement this with tests.",
+                    "content": "Updated frontend/src/api/client.js and ran npm run test:run.",
+                }),
+            )
+            .expect("trace event should append");
+        let record = store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::Preference,
+                content: "Prefers implementation detail.".to_string(),
+                origin: RecordOrigin::Inferred,
+                evidence_refs: vec![EvidenceRef {
+                    trace_id: "session-1".to_string(),
+                    event_id: event.id,
+                    session_id: "session-1".to_string(),
+                    tile_id: Some("tile-1".to_string()),
+                    model_id: Some("openai/gpt-4o".to_string()),
+                    note: None,
+                    source_type: Some("behavior".to_string()),
+                    source_id: None,
+                    source_label: None,
+                    excerpt: None,
+                    speaker_role: None,
+                }],
+                confidence: 0.8,
+                promotion_state: Some(PromotionState::Candidate),
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
+            })
+            .expect("record should be created");
+
+        let evidence = store
+            .resolve_user_record_evidence(&record.id)
+            .expect("evidence should resolve");
+
+        assert_eq!(evidence.len(), 1);
+        assert_eq!(evidence[0].session_id, "session-1");
+        assert_eq!(evidence[0].model_id.as_deref(), Some("openai/gpt-4o"));
+        assert_eq!(
+            evidence[0].prompt_excerpt.as_deref(),
+            Some("Implement this with tests.")
+        );
+        assert!(evidence[0]
+            .response_excerpt
+            .as_deref()
+            .unwrap_or_default()
+            .contains("frontend/src/api/client.js"));
+    }
+
+    #[test]
+    fn append_trace_event_creates_trace_file() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        let event = store
+            .append_trace_event(
+                "session-1",
+                TraceEventType::PromptSubmitted,
+                serde_json::json!({ "prompt": "hello" }),
+            )
+            .expect("trace event should append");
+
+        let trace = store
+            .get_session_trace("session-1")
+            .expect("trace should load");
+
+        assert_eq!(trace.events.len(), 1);
+        assert_eq!(trace.events[0].id, event.id);
+        assert_eq!(trace.events[0].event_type, TraceEventType::PromptSubmitted);
+    }
+}

From 9b63a4fa614cf20e436fa586b9b7788d22e40ea9 Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 15:52:32 +0800
Subject: [PATCH 11/30] refactor: extract twin::records

Moves user record CRUD (list/get/create/update_user_record), promotion
(set_user_record_promotion), context selection (select_context_records),
and behavioral inference (run_twin_inference, SignalAccumulator,
infer_behavioral_records) into services/twin/records.rs. ensure_record_cache
and write_record_file are marked pub(super): constitution/digest/export
still call ensure_record_cache across module boundaries, and the shared
corrupt-file quarantine test suite calls write_record_file directly.
Verbatim move; tests move with their code.
---
 frontend/src-tauri/src/services/twin/mod.rs   | 1979 +++--------------
 .../src-tauri/src/services/twin/records.rs    | 1337 +++++++++++
 2 files changed, 1684 insertions(+), 1632 deletions(-)
 create mode 100644 frontend/src-tauri/src/services/twin/records.rs

diff --git a/frontend/src-tauri/src/services/twin/mod.rs b/frontend/src-tauri/src/services/twin/mod.rs
index bebc8ac..e092891 100644
--- a/frontend/src-tauri/src/services/twin/mod.rs
+++ b/frontend/src-tauri/src/services/twin/mod.rs
@@ -30,15 +30,12 @@ use walkdir::WalkDir;
 
 mod shared;
 mod traces;
+mod records;
 
 use shared::*;
 
 const AUTO_PROMOTE_CONFIDENCE: f32 = 0.75;
 const AUTO_PROMOTE_SUPPORT_COUNT: usize = 3;
-const TWIN_INFERENCE_VERSION: &str = "local-signal-v1";
-const MAX_TWIN_CANDIDATE_CONTEXT_RECORDS: usize = 8;
-const MAX_TWIN_APPROVED_CONTEXT_RECORDS: usize = 12;
-const MAX_TWIN_APPROVED_FALLBACK_RECORDS: usize = 3;
 const MAX_MEMORY_DIGEST_ITEMS: usize = 5;
 const DEFAULT_EVAL_PERCENTAGE: u8 = 10;
 const DEFAULT_HOLDOUT_PERCENTAGE: u8 = 10;
@@ -50,461 +47,6 @@ enum ExportSplit {
     Holdout,
 }
 
-#[derive(Debug, Clone)]
-struct InferredRecordDraft {
-    inference_key: String,
-    signal_family: String,
-    kind: UserRecordKind,
-    content: String,
-    evidence_refs: Vec<EvidenceRef>,
-    evidence_event_ids: Vec<String>,
-    support_count: usize,
-    confidence: f32,
-}
-
-#[derive(Debug, Default)]
-struct SignalAccumulator {
-    evidence_refs: Vec<EvidenceRef>,
-    evidence_event_ids: HashSet<String>,
-}
-
-impl SignalAccumulator {
-    fn add_event(&mut self, trace: &SessionTrace, event: &TraceEvent) {
-        if !self.evidence_event_ids.insert(event.id.clone()) {
-            return;
-        }
-
-        self.evidence_refs.push(EvidenceRef {
-            trace_id: trace.id.clone(),
-            event_id: event.id.clone(),
-            session_id: trace.session_id.clone(),
-            tile_id: extract_event_tile_id(&event.payload),
-            model_id: extract_event_model_id(&event.payload),
-            note: evidence_note(event),
-            source_type: Some("behavior".to_string()),
-            source_id: Some(event.id.clone()),
-            source_label: evidence_note(event),
-            excerpt: Some(excerpt(&event_text(event))),
-            speaker_role: None,
-        });
-    }
-}
-
-fn infer_behavioral_records(traces: &[SessionTrace]) -> Vec<InferredRecordDraft> {
-    let mut signals: HashMap<String, SignalAccumulator> = HashMap::new();
-
-    for trace in traces {
-        for event in &trace.events {
-            match &event.event_type {
-                TraceEventType::PromptSubmitted => {
-                    let prompt = payload_string(&event.payload, &["prompt"]).unwrap_or_default();
-                    if event
-                        .payload
-                        .get("parent_tile_id")
-                        .is_some_and(|value| !value.is_null())
-                    {
-                        add_signal(&mut signals, "reasoning.iterative_deepening", trace, event);
-                    }
-                    if text_contains_any(
-                        &prompt,
-                        &["think harder", "revisit", "improve your previous answer"],
-                    ) {
-                        add_signal(&mut signals, "reasoning.iterative_deepening", trace, event);
-                    }
-                    if text_contains_any(
-                        &prompt,
-                        &[
-                            "implement",
-                            "fix",
-                            "test",
-                            "build",
-                            "file",
-                            "branch",
-                            "worktree",
-                        ],
-                    ) {
-                        add_signal(
-                            &mut signals,
-                            "preference.implementation_detail",
-                            trace,
-                            event,
-                        );
-                    }
-                    if payload_string(&event.payload, &["context_mode"])
-                        .is_some_and(|mode| mode == "knowledge_search" || mode == "semantic")
-                    {
-                        add_signal(&mut signals, "preference.grounded_context", trace, event);
-                    }
-                    if value_contains_key(&event.payload, "twin_domain") {
-                        add_signal(&mut signals, "fact.twin_domain_metadata", trace, event);
-                    }
-                }
-                TraceEventType::FeedbackRecorded => {
-                    let feedback_type =
-                        payload_string(&event.payload, &["feedback_type"]).unwrap_or_default();
-                    let text = event_text(event);
-
-                    match feedback_type.as_str() {
-                        "accept" => {
-                            if looks_structured(&text) {
-                                add_signal(
-                                    &mut signals,
-                                    "preference.structured_answers",
-                                    trace,
-                                    event,
-                                );
-                            }
-                            if looks_evidence_backed(&text) {
-                                add_signal(
-                                    &mut signals,
-                                    "preference.evidence_backed_detail",
-                                    trace,
-                                    event,
-                                );
-                            }
-                            if looks_implementation_detailed(&text) {
-                                add_signal(
-                                    &mut signals,
-                                    "preference.implementation_detail",
-                                    trace,
-                                    event,
-                                );
-                            }
-                        }
-                        "reject" => {
-                            add_signal(&mut signals, "preference.rejects_mismatch", trace, event);
-                        }
-                        "correction" => {
-                            add_signal(&mut signals, "preference.rejects_mismatch", trace, event);
-                            add_signal(&mut signals, "reasoning.corrects_ai_outputs", trace, event);
-                        }
-                        _ => {}
-                    }
-                }
-                TraceEventType::RankingRecorded => {
-                    add_signal(&mut signals, "reasoning.model_comparison", trace, event);
-                    let text = event_text(event);
-                    if looks_structured(&text) {
-                        add_signal(&mut signals, "preference.structured_answers", trace, event);
-                    }
-                    if looks_evidence_backed(&text) {
-                        add_signal(
-                            &mut signals,
-                            "preference.evidence_backed_detail",
-                            trace,
-                            event,
-                        );
-                    }
-                    if looks_implementation_detailed(&text) {
-                        add_signal(
-                            &mut signals,
-                            "preference.implementation_detail",
-                            trace,
-                            event,
-                        );
-                    }
-                }
-                TraceEventType::InsightCaptured => {
-                    add_signal(
-                        &mut signals,
-                        "reasoning.captures_self_knowledge",
-                        trace,
-                        event,
-                    );
-                }
-                TraceEventType::ModelsAdded => {
-                    add_signal(&mut signals, "reasoning.model_comparison", trace, event);
-                }
-                TraceEventType::DebateStarted | TraceEventType::DebateContinued => {
-                    add_signal(&mut signals, "reasoning.model_comparison", trace, event);
-                    add_signal(&mut signals, "reasoning.uses_debate", trace, event);
-                }
-                TraceEventType::NoteExported => {
-                    add_signal(
-                        &mut signals,
-                        "reasoning.curates_evidence_notes",
-                        trace,
-                        event,
-                    );
-                }
-                TraceEventType::NoteCanonicalPromoted => {
-                    add_signal(&mut signals, "reasoning.canonical_validation", trace, event);
-                }
-                TraceEventType::NoteCreated | TraceEventType::NoteUpdated => {
-                    if value_contains_key(&event.payload, "twin_domain") {
-                        add_signal(&mut signals, "fact.twin_domain_metadata", trace, event);
-                    }
-                    if payload_string(&event.payload, &["status"])
-                        .is_some_and(|status| status == "canonical")
-                    {
-                        add_signal(&mut signals, "reasoning.canonical_validation", trace, event);
-                    }
-                }
-                _ => {}
-            }
-        }
-    }
-
-    let mut drafts = signals
-        .into_iter()
-        .filter_map(|(key, accumulator)| {
-            let support_count = accumulator.evidence_refs.len();
-            if support_count == 0 {
-                return None;
-            }
-
-            let (kind, signal_family, content) = signal_definition(&key)?;
-            let mut evidence_event_ids = accumulator
-                .evidence_event_ids
-                .into_iter()
-                .collect::<Vec<_>>();
-            evidence_event_ids.sort();
-
-            Some(InferredRecordDraft {
-                inference_key: key,
-                signal_family: signal_family.to_string(),
-                kind,
-                content: content.to_string(),
-                confidence: confidence_for_support(support_count),
-                support_count,
-                evidence_refs: accumulator.evidence_refs,
-                evidence_event_ids,
-            })
-        })
-        .collect::<Vec<_>>();
-
-    drafts.sort_by(|a, b| a.inference_key.cmp(&b.inference_key));
-    drafts
-}
-
-fn add_signal(
-    signals: &mut HashMap<String, SignalAccumulator>,
-    key: &str,
-    trace: &SessionTrace,
-    event: &TraceEvent,
-) {
-    signals
-        .entry(key.to_string())
-        .or_default()
-        .add_event(trace, event);
-}
-
-fn signal_definition(key: &str) -> Option<(UserRecordKind, &'static str, &'static str)> {
-    match key {
-        "fact.twin_domain_metadata" => Some((
-            UserRecordKind::Fact,
-            "twin_domain",
-            "Uses twin_domain metadata to separate captured knowledge by the domain it belongs to.",
-        )),
-        "preference.structured_answers" => Some((
-            UserRecordKind::Preference,
-            "explicit_feedback",
-            "Prefers structured answers with headings, lists, or clear steps when judging model output.",
-        )),
-        "preference.evidence_backed_detail" => Some((
-            UserRecordKind::Preference,
-            "explicit_feedback",
-            "Prefers evidence-backed implementation detail over generic summary.",
-        )),
-        "preference.implementation_detail" => Some((
-            UserRecordKind::Preference,
-            "passive_prompting",
-            "Prefers answers that include concrete implementation details such as files, commands, tests, or code.",
-        )),
-        "preference.grounded_context" => Some((
-            UserRecordKind::Preference,
-            "passive_prompting",
-            "Uses existing notes as grounding context when asking models to reason.",
-        )),
-        "preference.rejects_mismatch" => Some((
-            UserRecordKind::Preference,
-            "explicit_feedback",
-            "Rejects or corrects responses that do not match their knowledge instead of saving them as truth.",
-        )),
-        "reasoning.corrects_ai_outputs" => Some((
-            UserRecordKind::ReasoningPattern,
-            "explicit_feedback",
-            "Provides corrections when model output conflicts with what they know.",
-        )),
-        "reasoning.iterative_deepening" => Some((
-            UserRecordKind::ReasoningPattern,
-            "branching",
-            "Revisits answers through branches or think-harder passes before treating them as settled.",
-        )),
-        "reasoning.model_comparison" => Some((
-            UserRecordKind::ReasoningPattern,
-            "model_selection",
-            "Compares multiple model outputs before selecting what matches their thinking.",
-        )),
-        "reasoning.uses_debate" => Some((
-            UserRecordKind::ReasoningPattern,
-            "debate_selection",
-            "Uses model debate or disagreement to test alternatives before deciding what to keep.",
-        )),
-        "reasoning.captures_self_knowledge" => Some((
-            UserRecordKind::ReasoningPattern,
-            "explicit_feedback",
-            "Captures durable facts, preferences, or reasoning patterns as explicit twin records.",
-        )),
-        "reasoning.curates_evidence_notes" => Some((
-            UserRecordKind::ReasoningPattern,
-            "note_export",
-            "Turns useful canvas work into durable evidence notes.",
-        )),
-        "reasoning.canonical_validation" => Some((
-            UserRecordKind::ReasoningPattern,
-            "canonical_promotion",
-            "Promotes knowledge to canonical notes after review or repeated validation.",
-        )),
-        _ => None,
-    }
-}
-
-fn confidence_for_support(support_count: usize) -> f32 {
-    (0.45 + support_count as f32 * 0.10).min(0.95)
-}
-
-fn build_inference_metadata(
-    draft: &InferredRecordDraft,
-    auto_promoted: bool,
-) -> HashMap<String, Value> {
-    json!({
-        "inference_key": draft.inference_key,
-        "inference_version": TWIN_INFERENCE_VERSION,
-        "signal_family": draft.signal_family,
-        "support_count": draft.support_count,
-        "evidence_event_ids": draft.evidence_event_ids,
-        "auto_promoted": auto_promoted,
-    })
-    .as_object()
-    .cloned()
-    .unwrap_or_default()
-    .into_iter()
-    .collect()
-}
-
-fn merge_promotion_history(
-    existing: HashMap<String, Value>,
-    mut next: HashMap<String, Value>,
-) -> HashMap<String, Value> {
-    for (key, value) in existing {
-        next.entry(key).or_insert(value);
-    }
-    next
-}
-
-fn append_promotion_history(
-    metadata: &mut HashMap<String, Value>,
-    from: &PromotionState,
-    to: &PromotionState,
-    rationale: Option<&str>,
-    automatic: bool,
-) {
-    let mut history = metadata
-        .get("promotion_history")
-        .and_then(Value::as_array)
-        .cloned()
-        .unwrap_or_default();
-
-    history.push(json!({
-        "from": from,
-        "to": to,
-        "at": Utc::now(),
-        "rationale": rationale,
-        "automatic": automatic,
-    }));
-    metadata.insert("promotion_history".to_string(), Value::Array(history));
-}
-
-fn promotion_state_sort_key(state: &PromotionState) -> u8 {
-    match state {
-        PromotionState::AutoPromoted => 0,
-        PromotionState::Candidate => 1,
-        PromotionState::Endorsed => 2,
-        PromotionState::Rejected => 3,
-        PromotionState::Private => 4,
-        PromotionState::NoTrain => 5,
-    }
-}
-
-fn twin_context_record(record: &UserRecord, source_label: &str) -> TwinContextRecord {
-    TwinContextRecord {
-        id: record.id.clone(),
-        kind: record.kind.clone(),
-        content: record.content.clone(),
-        confidence: record.confidence,
-        promotion_state: record.promotion_state.clone(),
-        evidence_count: record.evidence_refs.len(),
-        source_label: Some(source_label.to_string()),
-    }
-}
-
-fn twin_record_relevance(record: &UserRecord, query_terms: &HashSet<String>) -> usize {
-    if query_terms.is_empty() {
-        return 0;
-    }
-
-    let mut haystack = record.content.clone();
-    for evidence in &record.evidence_refs {
-        if let Some(note) = &evidence.note {
-            haystack.push(' ');
-            haystack.push_str(note);
-        }
-    }
-    for value in record.metadata.values() {
-        haystack.push(' ');
-        haystack.push_str(&value.to_string());
-    }
-
-    let record_terms = lexical_terms(&haystack);
-    query_terms.intersection(&record_terms).count()
-}
-
-fn looks_structured(text: &str) -> bool {
-    text.contains("\n- ")
-        || text.contains("\n* ")
-        || text.contains("\n1. ")
-        || text.contains("##")
-        || text.contains("```")
-}
-
-fn looks_evidence_backed(text: &str) -> bool {
-    text_contains_any(
-        text,
-        &[
-            "evidence",
-            "source",
-            "according",
-            "because",
-            "verify",
-            "verified",
-            "test",
-            "logs",
-            "tradeoff",
-        ],
-    )
-}
-
-fn looks_implementation_detailed(text: &str) -> bool {
-    text_contains_any(
-        text,
-        &[
-            ".rs",
-            ".js",
-            ".vue",
-            "frontend/",
-            "src/",
-            "cargo ",
-            "npm ",
-            "test",
-            "function ",
-            "```",
-            "command",
-            "file",
-        ],
-    )
-}
-
 fn clean_setup_entries(entries: Vec<String>) -> Vec<String> {
     let mut seen = HashSet::new();
     entries
@@ -1638,6 +1180,7 @@ fn memory_digest_state_for_action(action: &MemoryDigestAction) -> MemoryDigestSt
     }
 }
 
+
 pub struct TwinStore {
     root_path: PathBuf,
     traces_path: PathBuf,
@@ -1713,614 +1256,214 @@ impl TwinStore {
         Ok(())
     }
 
-    pub fn list_user_records(&mut self) -> Result<Vec<UserRecord>> {
-        self.ensure_record_cache()?;
-        let mut records: Vec<UserRecord> = self.record_cache.values().cloned().collect();
-        records.sort_by(|a, b| b.updated_at.cmp(&a.updated_at));
-        Ok(records)
-    }
+    pub fn list_constitution_items(&self) -> Result<Vec<ConstitutionItem>> {
+        let mut items = Vec::new();
+        if !self.constitution_path.exists() {
+            return Ok(items);
+        }
 
-    pub fn get_user_record(&mut self, id: &str) -> Result<UserRecord> {
-        Self::validate_file_id(id)?;
-        if let Some(record) = self.record_cache.get(id) {
-            return Ok(record.clone());
+        for entry in WalkDir::new(&self.constitution_path)
+            .min_depth(1)
+            .max_depth(1)
+            .into_iter()
+            .filter_map(|entry| entry.ok())
+        {
+            let path = entry.path();
+            if path.extension().is_some_and(|ext| ext == "json") {
+                if let Some(item) =
+                    load_or_quarantine::<ConstitutionItem>(path, "constitution item")
+                {
+                    items.push(item);
+                }
+            }
         }
 
-        let path = self.record_file_path(id);
-        let record = self.read_record_file(&path)?;
-        self.record_cache.insert(id.to_string(), record.clone());
-        Ok(record)
+        items.sort_by(|a, b| {
+            constitution_status_sort_key(&a.status)
+                .cmp(&constitution_status_sort_key(&b.status))
+                .then_with(|| {
+                    b.priority
+                        .partial_cmp(&a.priority)
+                        .unwrap_or(std::cmp::Ordering::Equal)
+                })
+                .then_with(|| b.updated_at.cmp(&a.updated_at))
+        });
+        Ok(items)
     }
 
-    pub fn create_user_record(&mut self, create: UserRecordCreate) -> Result<UserRecord> {
-        self.ensure_record_cache()?;
-
+    pub fn create_constitution_item(
+        &self,
+        create: ConstitutionItemCreate,
+    ) -> Result<ConstitutionItem> {
         let now = Utc::now();
-        let promotion_state = create
-            .promotion_state
-            .unwrap_or_else(|| PromotionState::default_for_origin(&create.origin));
-
-        let record = UserRecord {
+        let item = ConstitutionItem {
             id: uuid::Uuid::new_v4().to_string(),
-            kind: create.kind,
-            content: create.content,
-            evidence_refs: create.evidence_refs,
+            claim: create.claim,
+            dimension: create.dimension,
+            scope: create.scope,
+            priority: create.priority.clamp(0.0, 1.0),
             confidence: create.confidence.clamp(0.0, 1.0),
-            origin: create.origin,
-            promotion_state,
+            status: create.status,
+            evidence_refs: create.evidence_refs,
+            tensions: create.tensions,
+            linked_record_ids: create.linked_record_ids,
+            source: create.source,
             created_at: now,
             updated_at: now,
-            valid_from: create.valid_from,
-            valid_until: create.valid_until,
-            links: create.links,
-            metadata: create.metadata,
         };
-
-        self.record_cache.insert(record.id.clone(), record.clone());
-        self.write_record_file(&record)?;
-
-        Ok(record)
+        self.write_constitution_file(&item)?;
+        Ok(item)
     }
 
-    pub fn update_user_record(&mut self, id: &str, update: UserRecordUpdate) -> Result<UserRecord> {
-        self.ensure_record_cache()?;
-        let mut record = self.get_user_record(id)?;
-
-        if let Some(content) = update.content {
-            record.content = content;
+    pub fn update_constitution_item(
+        &self,
+        id: &str,
+        update: ConstitutionItemUpdate,
+    ) -> Result<ConstitutionItem> {
+        Self::validate_file_id(id)?;
+        let path = self.constitution_file_path(id);
+        let mut item = self.read_constitution_file(&path)?;
+        if let Some(claim) = update.claim {
+            item.claim = claim;
         }
-        if let Some(confidence) = update.confidence {
-            record.confidence = confidence.clamp(0.0, 1.0);
+        if let Some(dimension) = update.dimension {
+            item.dimension = dimension;
         }
-        if let Some(promotion_state) = update.promotion_state {
-            record.promotion_state = promotion_state;
+        if let Some(scope) = update.scope {
+            item.scope = scope;
         }
-        if let Some(valid_from) = update.valid_from {
-            record.valid_from = Some(valid_from);
+        if let Some(priority) = update.priority {
+            item.priority = priority.clamp(0.0, 1.0);
         }
-        if let Some(valid_until) = update.valid_until {
-            record.valid_until = Some(valid_until);
+        if let Some(confidence) = update.confidence {
+            item.confidence = confidence.clamp(0.0, 1.0);
         }
-        if let Some(links) = update.links {
-            record.links = links;
+        if let Some(status) = update.status {
+            item.status = status;
         }
-        if let Some(metadata) = update.metadata {
-            record.metadata = metadata;
+        if let Some(tensions) = update.tensions {
+            item.tensions = tensions;
         }
+        item.updated_at = Utc::now();
+        self.write_constitution_file(&item)?;
+        Ok(item)
+    }
 
-        record.updated_at = Utc::now();
-        self.record_cache.insert(record.id.clone(), record.clone());
-        self.write_record_file(&record)?;
-
-        Ok(record)
+    pub fn review_constitution_item(
+        &mut self,
+        id: &str,
+        request: ConstitutionReviewRequest,
+    ) -> Result<ConstitutionItem> {
+        Self::validate_file_id(id)?;
+        let mut item = self.read_constitution_file(&self.constitution_file_path(id))?;
+        item.status = constitution_status_for_action(&request.action);
+        item.updated_at = Utc::now();
+        self.write_constitution_file(&item)?;
+        self.append_trace_event(
+            "constitution-review",
+            TraceEventType::ConstitutionItemReviewed,
+            json!({
+                "constitution_item_id": item.id,
+                "action": request.action,
+                "rationale": request.rationale,
+            }),
+        )?;
+        Ok(item)
     }
 
-    pub fn run_twin_inference(&mut self) -> Result<TwinInferenceRunSummary> {
-        self.ensure_record_cache()?;
-        let traces = self.list_session_traces()?;
-        let scanned_events = traces.iter().map(|trace| trace.events.len()).sum::<usize>();
-        let drafts = infer_behavioral_records(&traces);
-
-        let mut existing_by_key = HashMap::new();
-        let mut rejected_keys = HashSet::new();
-        for record in self.record_cache.values() {
-            if let Some(inference_key) = record
-                .metadata
-                .get("inference_key")
-                .and_then(Value::as_str)
-                .map(ToOwned::to_owned)
-            {
-                existing_by_key.insert(inference_key.clone(), record.id.clone());
-                if record.promotion_state == PromotionState::Rejected {
-                    rejected_keys.insert(inference_key);
+    pub fn list_action_gaps(&self) -> Result<Vec<ActionGap>> {
+        let mut gaps = Vec::new();
+        if !self.action_gaps_path.exists() {
+            return Ok(gaps);
+        }
+
+        for entry in WalkDir::new(&self.action_gaps_path)
+            .min_depth(1)
+            .max_depth(1)
+            .into_iter()
+            .filter_map(|entry| entry.ok())
+        {
+            let path = entry.path();
+            if path.extension().is_some_and(|ext| ext == "json") {
+                if let Some(gap) = load_or_quarantine::<ActionGap>(path, "action gap") {
+                    gaps.push(gap);
                 }
             }
         }
 
-        let mut created_records = 0_usize;
-        let mut updated_records = 0_usize;
-        let mut auto_promoted_records = 0_usize;
-        let mut candidate_records = 0_usize;
-        let mut skipped_rejected_records = 0_usize;
+        gaps.sort_by(|a, b| {
+            constitution_status_sort_key(&a.status)
+                .cmp(&constitution_status_sort_key(&b.status))
+                .then_with(|| {
+                    b.confidence
+                        .partial_cmp(&a.confidence)
+                        .unwrap_or(std::cmp::Ordering::Equal)
+                })
+                .then_with(|| b.updated_at.cmp(&a.updated_at))
+        });
+        Ok(gaps)
+    }
 
-        for draft in drafts {
-            let desired_state = if draft.confidence >= AUTO_PROMOTE_CONFIDENCE
-                && draft.support_count >= AUTO_PROMOTE_SUPPORT_COUNT
-            {
-                PromotionState::AutoPromoted
-            } else {
-                PromotionState::Candidate
-            };
-            let mut metadata =
-                build_inference_metadata(&draft, desired_state == PromotionState::AutoPromoted);
-
-            if let Some(existing_id) = existing_by_key.get(&draft.inference_key).cloned() {
-                let mut record = self.get_user_record(&existing_id)?;
-                let previous_state = record.promotion_state.clone();
-                let is_rejected_key = rejected_keys.contains(&draft.inference_key);
-
-                record.kind = draft.kind.clone();
-                record.content = draft.content.clone();
-                record.evidence_refs = draft.evidence_refs.clone();
-                record.confidence = draft.confidence;
-                record.origin = RecordOrigin::Inferred;
-
-                if is_rejected_key {
-                    metadata.insert("auto_promoted".to_string(), Value::Bool(false));
-                    record.promotion_state = PromotionState::Rejected;
-                    skipped_rejected_records += 1;
-                } else if matches!(
-                    record.promotion_state,
-                    PromotionState::Candidate | PromotionState::AutoPromoted
-                ) {
-                    record.promotion_state = desired_state.clone();
-                }
-
-                metadata = merge_promotion_history(record.metadata.clone(), metadata);
-                if previous_state != record.promotion_state {
-                    append_promotion_history(
-                        &mut metadata,
-                        &previous_state,
-                        &record.promotion_state,
-                        Some("local signal inference threshold"),
-                        true,
-                    );
-                }
-
-                record.metadata = metadata;
-                record.updated_at = Utc::now();
-                self.record_cache.insert(record.id.clone(), record.clone());
-                self.write_record_file(&record)?;
-                updated_records += 1;
-            } else {
-                let mut metadata = metadata;
-                if desired_state == PromotionState::AutoPromoted {
-                    append_promotion_history(
-                        &mut metadata,
-                        &PromotionState::Candidate,
-                        &PromotionState::AutoPromoted,
-                        Some("confidence >= 0.75 and support_count >= 3"),
-                        true,
-                    );
-                }
-
-                self.create_user_record(UserRecordCreate {
-                    kind: draft.kind,
-                    content: draft.content,
-                    evidence_refs: draft.evidence_refs,
-                    confidence: draft.confidence,
-                    origin: RecordOrigin::Inferred,
-                    promotion_state: Some(desired_state),
-                    valid_from: None,
-                    valid_until: None,
-                    links: Vec::new(),
-                    metadata,
-                })?;
-                created_records += 1;
-            }
-        }
-
-        for record in self.record_cache.values() {
-            if record.origin != RecordOrigin::Inferred {
-                continue;
-            }
-            match record.promotion_state {
-                PromotionState::AutoPromoted => auto_promoted_records += 1,
-                PromotionState::Candidate => candidate_records += 1,
-                _ => {}
-            }
-        }
-
-        Ok(TwinInferenceRunSummary {
-            inference_version: TWIN_INFERENCE_VERSION.to_string(),
-            scanned_traces: traces.len(),
-            scanned_events,
-            created_records,
-            updated_records,
-            auto_promoted_records,
-            candidate_records,
-            skipped_rejected_records,
-            generated_at: Utc::now(),
-        })
-    }
-
-    pub fn get_twin_review(&mut self) -> Result<Vec<TwinReviewRecord>> {
-        let records = self.list_user_records()?;
-        let mut review = Vec::with_capacity(records.len());
-
-        for record in records {
-            let evidence = self.resolve_evidence_refs(&record.evidence_refs)?;
-            review.push(TwinReviewRecord {
-                evidence_count: record.evidence_refs.len(),
-                latest_evidence: evidence.into_iter().max_by_key(|item| item.created_at),
-                record,
-            });
-        }
-
-        review.sort_by(|a, b| {
-            promotion_state_sort_key(&a.record.promotion_state)
-                .cmp(&promotion_state_sort_key(&b.record.promotion_state))
-                .then_with(|| b.record.updated_at.cmp(&a.record.updated_at))
-        });
-
-        Ok(review)
-    }
-
-    pub fn select_context_records(
-        &mut self,
-        query: &str,
-    ) -> Result<(Vec<TwinContextRecord>, Vec<TwinContextRecord>)> {
-        self.ensure_record_cache()?;
-
-        let query_terms = lexical_terms(query);
-        let mut approved = Vec::new();
-        let mut approved_fallback = Vec::new();
-        let mut candidates = Vec::new();
-
-        for record in self.record_cache.values() {
-            match record.promotion_state {
-                PromotionState::Endorsed | PromotionState::AutoPromoted => {
-                    let relevance = twin_record_relevance(record, &query_terms);
-                    if relevance > 0 {
-                        approved.push((relevance, twin_context_record(record, "approved")));
-                    } else {
-                        approved_fallback.push(twin_context_record(record, "approved"));
-                    }
-                }
-                PromotionState::Candidate => {
-                    let relevance = twin_record_relevance(record, &query_terms);
-                    if relevance > 0 {
-                        candidates.push((
-                            relevance,
-                            record.updated_at,
-                            twin_context_record(record, "candidate"),
-                        ));
-                    }
-                }
-                PromotionState::Rejected | PromotionState::Private | PromotionState::NoTrain => {}
-            }
-        }
-
-        approved.sort_by(|a, b| {
-            b.0.cmp(&a.0).then_with(|| {
-                b.1.confidence
-                    .partial_cmp(&a.1.confidence)
-                    .unwrap_or(std::cmp::Ordering::Equal)
-                    .then_with(|| b.1.evidence_count.cmp(&a.1.evidence_count))
-            })
-        });
-
-        let approved: Vec<TwinContextRecord> = if approved.is_empty() {
-            // Never assemble an empty behavioral context just because the
-            // query shares no keywords with any approved record.
-            approved_fallback.sort_by(|a, b| {
-                b.confidence
-                    .partial_cmp(&a.confidence)
-                    .unwrap_or(std::cmp::Ordering::Equal)
-                    .then_with(|| b.evidence_count.cmp(&a.evidence_count))
-            });
-            approved_fallback
-                .into_iter()
-                .take(MAX_TWIN_APPROVED_FALLBACK_RECORDS)
-                .collect()
-        } else {
-            approved
-                .into_iter()
-                .take(MAX_TWIN_APPROVED_CONTEXT_RECORDS)
-                .map(|(_, record)| record)
-                .collect()
-        };
-
-        candidates.sort_by(|a, b| {
-            b.0.cmp(&a.0).then_with(|| b.1.cmp(&a.1)).then_with(|| {
-                b.2.confidence
-                    .partial_cmp(&a.2.confidence)
-                    .unwrap_or(std::cmp::Ordering::Equal)
-            })
-        });
-
-        Ok((
-            approved,
-            candidates
-                .into_iter()
-                .take(MAX_TWIN_CANDIDATE_CONTEXT_RECORDS)
-                .map(|(_, _, record)| record)
-                .collect(),
-        ))
-    }
-
-    pub fn resolve_user_record_evidence(&mut self, id: &str) -> Result<Vec<ResolvedEvidenceRef>> {
-        let record = self.get_user_record(id)?;
-        self.resolve_evidence_refs(&record.evidence_refs)
-    }
-
-    pub fn set_user_record_promotion(
-        &mut self,
-        id: &str,
-        promotion_state: PromotionState,
-        rationale: Option<String>,
-    ) -> Result<UserRecord> {
-        self.ensure_record_cache()?;
-        let mut record = self.get_user_record(id)?;
-        let previous_state = record.promotion_state.clone();
-        let now = Utc::now();
-
-        record.promotion_state = promotion_state.clone();
-        record.updated_at = now;
-
-        append_promotion_history(
-            &mut record.metadata,
-            &previous_state,
-            &promotion_state,
-            rationale.as_deref(),
-            false,
-        );
-
-        if promotion_state == PromotionState::Rejected {
-            record
-                .metadata
-                .insert("reverted_at".to_string(), json!(now));
-            record
-                .metadata
-                .insert("revert_reason".to_string(), json!(rationale));
-            record
-                .metadata
-                .insert("auto_promoted".to_string(), Value::Bool(false));
-        }
-
-        self.record_cache.insert(record.id.clone(), record.clone());
-        self.write_record_file(&record)?;
-
-        Ok(record)
-    }
-
-    pub(super) fn ensure_record_cache(&mut self) -> Result<()> {
-        if self.records_cache_ready {
-            return Ok(());
-        }
-
-        for entry in WalkDir::new(&self.records_path)
-            .min_depth(1)
-            .max_depth(1)
-            .into_iter()
-            .filter_map(|entry| entry.ok())
-        {
-            let path = entry.path();
-            if path.extension().is_some_and(|ext| ext == "json") {
-                if let Some(record) = load_or_quarantine::<UserRecord>(path, "record") {
-                    self.record_cache.insert(record.id.clone(), record);
-                }
-            }
-        }
-
-        self.records_cache_ready = true;
-        Ok(())
-    }
-
-    fn record_file_path(&self, record_id: &str) -> PathBuf {
-        self.records_path.join(format!("{}.json", record_id))
-    }
-
-    fn read_record_file(&self, path: &Path) -> Result<UserRecord> {
-        let content = std::fs::read_to_string(path)
-            .with_context(|| format!("Failed to read record file: {}", path.display()))?;
-        serde_json::from_str(&content)
-            .with_context(|| format!("Failed to parse record file: {}", path.display()))
-    }
-
-    pub(super) fn write_record_file(&self, record: &UserRecord) -> Result<()> {
-        let path = self.record_file_path(&record.id);
-        self.write_pretty_json(&path, record)
-    }
-
-    pub fn list_constitution_items(&self) -> Result<Vec<ConstitutionItem>> {
-        let mut items = Vec::new();
-        if !self.constitution_path.exists() {
-            return Ok(items);
-        }
-
-        for entry in WalkDir::new(&self.constitution_path)
-            .min_depth(1)
-            .max_depth(1)
-            .into_iter()
-            .filter_map(|entry| entry.ok())
-        {
-            let path = entry.path();
-            if path.extension().is_some_and(|ext| ext == "json") {
-                if let Some(item) =
-                    load_or_quarantine::<ConstitutionItem>(path, "constitution item")
-                {
-                    items.push(item);
-                }
-            }
-        }
-
-        items.sort_by(|a, b| {
-            constitution_status_sort_key(&a.status)
-                .cmp(&constitution_status_sort_key(&b.status))
-                .then_with(|| {
-                    b.priority
-                        .partial_cmp(&a.priority)
-                        .unwrap_or(std::cmp::Ordering::Equal)
-                })
-                .then_with(|| b.updated_at.cmp(&a.updated_at))
-        });
-        Ok(items)
-    }
-
-    pub fn create_constitution_item(
-        &self,
-        create: ConstitutionItemCreate,
-    ) -> Result<ConstitutionItem> {
+    pub fn create_action_gap(&self, create: ActionGapCreate) -> Result<ActionGap> {
         let now = Utc::now();
-        let item = ConstitutionItem {
+        let gap = ActionGap {
             id: uuid::Uuid::new_v4().to_string(),
-            claim: create.claim,
-            dimension: create.dimension,
-            scope: create.scope,
-            priority: create.priority.clamp(0.0, 1.0),
-            confidence: create.confidence.clamp(0.0, 1.0),
-            status: create.status,
+            stated_value: create.stated_value,
+            revealed_behavior: create.revealed_behavior,
+            driver_hypothesis: create.driver_hypothesis,
+            somatic_taste_signal: create.somatic_taste_signal,
+            decision_risk: create.decision_risk,
             evidence_refs: create.evidence_refs,
-            tensions: create.tensions,
             linked_record_ids: create.linked_record_ids,
-            source: create.source,
+            confidence: create.confidence.clamp(0.0, 1.0),
+            status: create.status,
             created_at: now,
             updated_at: now,
         };
-        self.write_constitution_file(&item)?;
-        Ok(item)
-    }
-
-    pub fn update_constitution_item(
-        &self,
-        id: &str,
-        update: ConstitutionItemUpdate,
-    ) -> Result<ConstitutionItem> {
-        Self::validate_file_id(id)?;
-        let path = self.constitution_file_path(id);
-        let mut item = self.read_constitution_file(&path)?;
-        if let Some(claim) = update.claim {
-            item.claim = claim;
-        }
-        if let Some(dimension) = update.dimension {
-            item.dimension = dimension;
-        }
-        if let Some(scope) = update.scope {
-            item.scope = scope;
-        }
-        if let Some(priority) = update.priority {
-            item.priority = priority.clamp(0.0, 1.0);
-        }
-        if let Some(confidence) = update.confidence {
-            item.confidence = confidence.clamp(0.0, 1.0);
-        }
-        if let Some(status) = update.status {
-            item.status = status;
-        }
-        if let Some(tensions) = update.tensions {
-            item.tensions = tensions;
-        }
-        item.updated_at = Utc::now();
-        self.write_constitution_file(&item)?;
-        Ok(item)
+        self.write_action_gap_file(&gap)?;
+        Ok(gap)
     }
 
-    pub fn review_constitution_item(
+    pub fn review_action_gap(
         &mut self,
         id: &str,
         request: ConstitutionReviewRequest,
-    ) -> Result<ConstitutionItem> {
+    ) -> Result<ActionGap> {
         Self::validate_file_id(id)?;
-        let mut item = self.read_constitution_file(&self.constitution_file_path(id))?;
-        item.status = constitution_status_for_action(&request.action);
-        item.updated_at = Utc::now();
-        self.write_constitution_file(&item)?;
+        let mut gap = self.read_action_gap_file(&self.action_gap_file_path(id))?;
+        gap.status = constitution_status_for_action(&request.action);
+        gap.updated_at = Utc::now();
+        self.write_action_gap_file(&gap)?;
         self.append_trace_event(
             "constitution-review",
-            TraceEventType::ConstitutionItemReviewed,
+            TraceEventType::ActionGapReviewed,
             json!({
-                "constitution_item_id": item.id,
+                "action_gap_id": gap.id,
                 "action": request.action,
                 "rationale": request.rationale,
             }),
         )?;
-        Ok(item)
+        Ok(gap)
     }
 
-    pub fn list_action_gaps(&self) -> Result<Vec<ActionGap>> {
-        let mut gaps = Vec::new();
-        if !self.action_gaps_path.exists() {
-            return Ok(gaps);
+    pub fn get_constitution_setup(&self) -> Result<ConstitutionSetup> {
+        if !self.setup_path.exists() {
+            return Ok(ConstitutionSetup::default());
         }
 
-        for entry in WalkDir::new(&self.action_gaps_path)
-            .min_depth(1)
-            .max_depth(1)
-            .into_iter()
-            .filter_map(|entry| entry.ok())
-        {
-            let path = entry.path();
-            if path.extension().is_some_and(|ext| ext == "json") {
-                if let Some(gap) = load_or_quarantine::<ActionGap>(path, "action gap") {
-                    gaps.push(gap);
-                }
-            }
-        }
-
-        gaps.sort_by(|a, b| {
-            constitution_status_sort_key(&a.status)
-                .cmp(&constitution_status_sort_key(&b.status))
-                .then_with(|| {
-                    b.confidence
-                        .partial_cmp(&a.confidence)
-                        .unwrap_or(std::cmp::Ordering::Equal)
-                })
-                .then_with(|| b.updated_at.cmp(&a.updated_at))
-        });
-        Ok(gaps)
-    }
-
-    pub fn create_action_gap(&self, create: ActionGapCreate) -> Result<ActionGap> {
-        let now = Utc::now();
-        let gap = ActionGap {
-            id: uuid::Uuid::new_v4().to_string(),
-            stated_value: create.stated_value,
-            revealed_behavior: create.revealed_behavior,
-            driver_hypothesis: create.driver_hypothesis,
-            somatic_taste_signal: create.somatic_taste_signal,
-            decision_risk: create.decision_risk,
-            evidence_refs: create.evidence_refs,
-            linked_record_ids: create.linked_record_ids,
-            confidence: create.confidence.clamp(0.0, 1.0),
-            status: create.status,
-            created_at: now,
-            updated_at: now,
-        };
-        self.write_action_gap_file(&gap)?;
-        Ok(gap)
-    }
-
-    pub fn review_action_gap(
-        &mut self,
-        id: &str,
-        request: ConstitutionReviewRequest,
-    ) -> Result<ActionGap> {
-        Self::validate_file_id(id)?;
-        let mut gap = self.read_action_gap_file(&self.action_gap_file_path(id))?;
-        gap.status = constitution_status_for_action(&request.action);
-        gap.updated_at = Utc::now();
-        self.write_action_gap_file(&gap)?;
-        self.append_trace_event(
-            "constitution-review",
-            TraceEventType::ActionGapReviewed,
-            json!({
-                "action_gap_id": gap.id,
-                "action": request.action,
-                "rationale": request.rationale,
-            }),
-        )?;
-        Ok(gap)
-    }
-
-    pub fn get_constitution_setup(&self) -> Result<ConstitutionSetup> {
-        if !self.setup_path.exists() {
-            return Ok(ConstitutionSetup::default());
-        }
-
-        let content = std::fs::read_to_string(&self.setup_path).with_context(|| {
-            format!(
-                "Failed to read constitution setup file: {}",
-                self.setup_path.display()
-            )
-        })?;
-        serde_json::from_str(&content).with_context(|| {
-            format!(
-                "Failed to parse constitution setup file: {}",
-                self.setup_path.display()
-            )
-        })
-    }
+        let content = std::fs::read_to_string(&self.setup_path).with_context(|| {
+            format!(
+                "Failed to read constitution setup file: {}",
+                self.setup_path.display()
+            )
+        })?;
+        serde_json::from_str(&content).with_context(|| {
+            format!(
+                "Failed to parse constitution setup file: {}",
+                self.setup_path.display()
+            )
+        })
+    }
 
     pub fn save_constitution_setup(
         &mut self,
@@ -3955,639 +3098,210 @@ impl TwinStore {
                     PromotionState::Rejected | PromotionState::Private | PromotionState::NoTrain
                 )
             })
-            .flat_map(|record| {
-                record
-                    .evidence_refs
-                    .iter()
-                    .map(|evidence| evidence.event_id.clone())
-            })
-            .collect();
-        let feedback_event_lines = self
-            .list_session_traces()?
-            .into_iter()
-            .flat_map(|trace| {
-                let session_id = trace.session_id.clone();
-                let trace_id = trace.id.clone();
-                trace
-                    .events
-                    .into_iter()
-                    .filter(|event| {
-                        matches!(
-                            event.event_type,
-                            TraceEventType::FeedbackRecorded
-                                | TraceEventType::RankingRecorded
-                                | TraceEventType::InsightCaptured
-                        ) && !excluded_event_ids.contains(&event.id)
-                    })
-                    .map(move |event| {
-                        serde_json::to_string(&serde_json::json!({
-                            "session_id": session_id,
-                            "trace_id": trace_id,
-                            "event": event,
-                        }))
-                        .map_err(anyhow::Error::from)
-                    })
-                    .collect::<Vec<_>>()
-            })
-            .collect::<Result<Vec<_>>>()?;
-        self.write_jsonl_file(&feedback_events_path, &feedback_event_lines)?;
-
-        let manifest = serde_json::json!({
-            "bundle_schema_version": 2,
-            "generated_at": Utc::now(),
-            "root_path": self.root_path.display().to_string(),
-            "eval_percentage": eval_percentage,
-            "holdout_percentage": holdout_percentage,
-            "included_record_ids": included_record_ids,
-            "record_files": {
-                "approved_user_records": {
-                    "path": approved_path.display().to_string(),
-                    "count": approved_lines.len(),
-                },
-                "candidate_user_records": {
-                    "path": candidate_path.display().to_string(),
-                    "count": candidate_lines.len(),
-                },
-                "rejected_user_records": {
-                    "path": rejected_path.display().to_string(),
-                    "count": rejected_lines.len(),
-                },
-                "decision_mirror_benchmark": {
-                    "path": benchmark_path.display().to_string(),
-                    "count": benchmark_lines.len(),
-                },
-                "constitution_items": {
-                    "path": constitution_path.display().to_string(),
-                    "count": constitution_lines.len(),
-                },
-                "action_gaps": {
-                    "path": action_gaps_path.display().to_string(),
-                    "count": action_gap_lines.len(),
-                },
-                "decision_episodes": {
-                    "path": decision_episodes_path.display().to_string(),
-                    "count": decision_episode_lines.len(),
-                },
-                "feedback_events": {
-                    "path": feedback_events_path.display().to_string(),
-                    "count": feedback_event_lines.len(),
-                },
-            },
-            "excluded_counts": {
-                "private_or_no_train": private_or_no_train_record_ids.len(),
-            }
-        });
-        self.write_pretty_json(&manifest_path, &manifest)?;
-
-        Ok(ExportBundle {
-            output_dir: output_dir.display().to_string(),
-            approved_user_records: ExportFileSummary {
-                path: approved_path.display().to_string(),
-                count: approved_lines.len(),
-            },
-            candidate_user_records: ExportFileSummary {
-                path: candidate_path.display().to_string(),
-                count: candidate_lines.len(),
-            },
-            rejected_user_records: ExportFileSummary {
-                path: rejected_path.display().to_string(),
-                count: rejected_lines.len(),
-            },
-            decision_mirror_benchmark: ExportFileSummary {
-                path: benchmark_path.display().to_string(),
-                count: benchmark_lines.len(),
-            },
-            constitution_items: ExportFileSummary {
-                path: constitution_path.display().to_string(),
-                count: constitution_lines.len(),
-            },
-            action_gaps: ExportFileSummary {
-                path: action_gaps_path.display().to_string(),
-                count: action_gap_lines.len(),
-            },
-            decision_episodes: ExportFileSummary {
-                path: decision_episodes_path.display().to_string(),
-                count: decision_episode_lines.len(),
-            },
-            feedback_events: ExportFileSummary {
-                path: feedback_events_path.display().to_string(),
-                count: feedback_event_lines.len(),
-            },
-            train: ExportFileSummary {
-                path: train_path.display().to_string(),
-                count: train_lines.len(),
-            },
-            eval: ExportFileSummary {
-                path: eval_path.display().to_string(),
-                count: eval_lines.len(),
-            },
-            holdout: ExportFileSummary {
-                path: holdout_path.display().to_string(),
-                count: holdout_lines.len(),
-            },
-            manifest_path: manifest_path.display().to_string(),
-            included_records: train_lines.len() + eval_lines.len() + holdout_lines.len(),
-            excluded_records: private_or_no_train_record_ids.len(),
-        })
-    }
-
-    fn split_for_record(
-        record: &UserRecord,
-        eval_percentage: u8,
-        holdout_percentage: u8,
-    ) -> ExportSplit {
-        let key = format!(
-            "{}:{}:{}:{}",
-            record.id,
-            serde_json::to_string(&record.kind).unwrap_or_default(),
-            record.content,
-            record.updated_at
-        );
-        let bucket = Self::stable_bucket(&key);
-
-        if bucket < holdout_percentage {
-            ExportSplit::Holdout
-        } else if bucket < holdout_percentage + eval_percentage {
-            ExportSplit::Eval
-        } else {
-            ExportSplit::Train
-        }
-    }
-
-    fn stable_bucket(key: &str) -> u8 {
-        let mut hasher = DefaultHasher::new();
-        key.hash(&mut hasher);
-        (hasher.finish() % 100) as u8
-    }
-
-    fn record_to_export_value(record: &UserRecord) -> serde_json::Value {
-        serde_json::json!({
-            "id": record.id,
-            "kind": record.kind,
-            "content": record.content,
-            "origin": record.origin,
-            "promotion_state": record.promotion_state,
-            "confidence": record.confidence,
-            "created_at": record.created_at,
-            "updated_at": record.updated_at,
-            "valid_from": record.valid_from,
-            "valid_until": record.valid_until,
-            "links": record.links,
-            "evidence_refs": record.evidence_refs,
-            "metadata": record.metadata,
-        })
-    }
-
-    fn write_jsonl_file(&self, path: &Path, lines: &[String]) -> Result<()> {
-        let mut content = lines.join("\n");
-        if !content.is_empty() {
-            content.push('\n');
-        }
-        write_atomic(path, content.as_bytes())
-            .with_context(|| format!("Failed to write JSONL file: {}", path.display()))
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::models::note::{Note, NoteStatus};
-    use crate::models::twin::{
-        default_record_confidence, PromotionState, RecordLink, RecordLinkType, UserRecordKind,
-    };
-    use tempfile::tempdir;
-
-    use crate::models::twin::ConstitutionStatus;
-    #[test]
-    fn user_record_writes_are_atomic_with_no_tmp_litter() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        let record = store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::Preference,
-                content: "Prefers atomic writes".to_string(),
-                origin: RecordOrigin::User,
-                evidence_refs: Vec::new(),
-                confidence: default_record_confidence(),
-                promotion_state: None,
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
-            })
-            .expect("record should be created");
-
-        let record_file = store.records_path.join(format!("{}.json", record.id));
-        let persisted = std::fs::read_to_string(&record_file).expect("record file should exist");
-        assert!(persisted.contains("Prefers atomic writes"));
-        crate::services::atomic_io::assert_no_tmp_siblings(&store.records_path);
-    }
-
-    #[test]
-    fn synthetic_records_require_endorsement_for_export() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        let synthetic = store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::Preference,
-                content: "Synthesized summary".to_string(),
-                origin: RecordOrigin::Synthetic,
-                evidence_refs: Vec::new(),
-                confidence: default_record_confidence(),
-                promotion_state: None,
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
-            })
-            .expect("synthetic record should be created");
-
-        let bundle = store
-            .export_bundle(TwinExportRequest::default())
-            .expect("export should succeed");
-        assert_eq!(bundle.included_records, 0);
-
-        store
-            .update_user_record(
-                &synthetic.id,
-                UserRecordUpdate {
-                    promotion_state: Some(PromotionState::Endorsed),
-                    ..UserRecordUpdate::default()
-                },
-            )
-            .expect("synthetic record should update");
-
-        let bundle = store
-            .export_bundle(TwinExportRequest::default())
-            .expect("endorsed export should succeed");
-        assert_eq!(bundle.included_records, 1);
-    }
-
-    #[test]
-    fn user_records_auto_promote_and_export() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        let record = store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::Fact,
-                content: "I prefer blunt feedback over flattery.".to_string(),
-                origin: RecordOrigin::User,
-                evidence_refs: Vec::new(),
-                confidence: 0.9,
-                promotion_state: None,
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
-            })
-            .expect("user record should be created");
-
-        assert_eq!(record.promotion_state, PromotionState::AutoPromoted);
-
-        let bundle = store
-            .export_bundle(TwinExportRequest::default())
-            .expect("export should succeed");
-        assert_eq!(bundle.included_records, 1);
-        assert_eq!(bundle.approved_user_records.count, 1);
-    }
-
-    #[test]
-    fn inference_creates_candidate_below_threshold_and_auto_promotes_at_threshold() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        for index in 0..2 {
-            store
-                .append_trace_event(
-                    "session-1",
-                    TraceEventType::PromptSubmitted,
-                    serde_json::json!({
-                        "tile_id": format!("tile-{}", index),
-                        "prompt": "Please implement this with files and tests.",
-                        "models": ["openai/gpt-4o"],
-                    }),
-                )
-                .expect("trace event should append");
-        }
-
-        store.run_twin_inference().expect("inference should run");
-        let records = store.list_user_records().expect("records should list");
-        let record = records
-            .iter()
-            .find(|record| {
-                record.metadata.get("inference_key").and_then(Value::as_str)
-                    == Some("preference.implementation_detail")
-            })
-            .expect("implementation detail record should exist");
-        assert_eq!(record.promotion_state, PromotionState::Candidate);
-        assert_eq!(
-            record.metadata.get("support_count").and_then(Value::as_u64),
-            Some(2)
-        );
-
-        store
-            .append_trace_event(
-                "session-1",
-                TraceEventType::PromptSubmitted,
-                serde_json::json!({
-                    "tile_id": "tile-3",
-                    "prompt": "Fix the build and show exact commands.",
-                    "models": ["openai/gpt-4o"],
-                }),
-            )
-            .expect("trace event should append");
-
-        store.run_twin_inference().expect("inference should rerun");
-        let records = store.list_user_records().expect("records should list");
-        let record = records
-            .iter()
-            .find(|record| {
-                record.metadata.get("inference_key").and_then(Value::as_str)
-                    == Some("preference.implementation_detail")
-            })
-            .expect("implementation detail record should exist");
-        assert_eq!(record.promotion_state, PromotionState::AutoPromoted);
-        assert!(record.confidence >= AUTO_PROMOTE_CONFIDENCE);
-    }
-
-    #[test]
-    fn repeated_inference_updates_by_key_instead_of_duplicating() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        store
-            .append_trace_event(
-                "session-1",
-                TraceEventType::ModelsAdded,
-                serde_json::json!({
-                    "tile_id": "tile-1",
-                    "model_ids": ["openai/gpt-4o", "anthropic/claude"],
-                }),
-            )
-            .expect("trace event should append");
-
-        store
-            .run_twin_inference()
-            .expect("first inference should run");
-        store
-            .run_twin_inference()
-            .expect("second inference should run");
-
-        let inferred = store
-            .list_user_records()
-            .expect("records should list")
-            .into_iter()
-            .filter(|record| record.origin == RecordOrigin::Inferred)
-            .collect::<Vec<_>>();
-        assert_eq!(inferred.len(), 1);
-        assert_eq!(
-            inferred[0]
-                .metadata
-                .get("inference_key")
-                .and_then(Value::as_str),
-            Some("reasoning.model_comparison")
-        );
-    }
-
-    #[test]
-    fn rejected_inference_keys_are_not_auto_promoted_again() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        for index in 0..3 {
-            store
-                .append_trace_event(
-                    "session-1",
-                    TraceEventType::DebateStarted,
-                    serde_json::json!({
-                        "debate_id": format!("debate-{}", index),
-                        "source_tile_ids": ["tile-1"],
-                        "participating_models": ["a", "b"],
-                    }),
-                )
-                .expect("trace event should append");
-        }
-
-        store.run_twin_inference().expect("inference should run");
-        let record = store
-            .list_user_records()
-            .expect("records should list")
-            .into_iter()
-            .find(|record| {
-                record.metadata.get("inference_key").and_then(Value::as_str)
-                    == Some("reasoning.uses_debate")
-            })
-            .expect("debate record should exist");
-        assert_eq!(record.promotion_state, PromotionState::AutoPromoted);
-
-        store
-            .set_user_record_promotion(
-                &record.id,
-                PromotionState::Rejected,
-                Some("too broad".to_string()),
-            )
-            .expect("record should reject");
-        let summary = store.run_twin_inference().expect("inference should rerun");
-        let record = store
-            .get_user_record(&record.id)
-            .expect("record should load");
-
-        assert_eq!(record.promotion_state, PromotionState::Rejected);
-        assert!(summary.skipped_rejected_records >= 1);
-    }
-
-    #[test]
-    fn context_records_include_approved_and_only_relevant_candidates() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::Preference,
-                content: "Prefers evidence-backed implementation detail.".to_string(),
-                origin: RecordOrigin::User,
-                evidence_refs: Vec::new(),
-                confidence: 0.9,
-                promotion_state: Some(PromotionState::Endorsed),
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
-            })
-            .expect("approved record should create");
-        let relevant_candidate = store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::ReasoningPattern,
-                content: "May prefer red-team critique for shipping decisions.".to_string(),
-                origin: RecordOrigin::Inferred,
-                evidence_refs: Vec::new(),
-                confidence: 0.6,
-                promotion_state: Some(PromotionState::Candidate),
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
-            })
-            .expect("candidate should create");
-        store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::ReasoningPattern,
-                content: "May prefer visual design exploration.".to_string(),
-                origin: RecordOrigin::Inferred,
-                evidence_refs: Vec::new(),
-                confidence: 0.6,
-                promotion_state: Some(PromotionState::Candidate),
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
+            .flat_map(|record| {
+                record
+                    .evidence_refs
+                    .iter()
+                    .map(|evidence| evidence.event_id.clone())
+            })
+            .collect();
+        let feedback_event_lines = self
+            .list_session_traces()?
+            .into_iter()
+            .flat_map(|trace| {
+                let session_id = trace.session_id.clone();
+                let trace_id = trace.id.clone();
+                trace
+                    .events
+                    .into_iter()
+                    .filter(|event| {
+                        matches!(
+                            event.event_type,
+                            TraceEventType::FeedbackRecorded
+                                | TraceEventType::RankingRecorded
+                                | TraceEventType::InsightCaptured
+                        ) && !excluded_event_ids.contains(&event.id)
+                    })
+                    .map(move |event| {
+                        serde_json::to_string(&serde_json::json!({
+                            "session_id": session_id,
+                            "trace_id": trace_id,
+                            "event": event,
+                        }))
+                        .map_err(anyhow::Error::from)
+                    })
+                    .collect::<Vec<_>>()
             })
-            .expect("irrelevant candidate should create");
+            .collect::<Result<Vec<_>>>()?;
+        self.write_jsonl_file(&feedback_events_path, &feedback_event_lines)?;
 
-        let (approved, candidates) = store
-            .select_context_records("Need red-team critique for this shipping decision")
-            .expect("context records should select");
+        let manifest = serde_json::json!({
+            "bundle_schema_version": 2,
+            "generated_at": Utc::now(),
+            "root_path": self.root_path.display().to_string(),
+            "eval_percentage": eval_percentage,
+            "holdout_percentage": holdout_percentage,
+            "included_record_ids": included_record_ids,
+            "record_files": {
+                "approved_user_records": {
+                    "path": approved_path.display().to_string(),
+                    "count": approved_lines.len(),
+                },
+                "candidate_user_records": {
+                    "path": candidate_path.display().to_string(),
+                    "count": candidate_lines.len(),
+                },
+                "rejected_user_records": {
+                    "path": rejected_path.display().to_string(),
+                    "count": rejected_lines.len(),
+                },
+                "decision_mirror_benchmark": {
+                    "path": benchmark_path.display().to_string(),
+                    "count": benchmark_lines.len(),
+                },
+                "constitution_items": {
+                    "path": constitution_path.display().to_string(),
+                    "count": constitution_lines.len(),
+                },
+                "action_gaps": {
+                    "path": action_gaps_path.display().to_string(),
+                    "count": action_gap_lines.len(),
+                },
+                "decision_episodes": {
+                    "path": decision_episodes_path.display().to_string(),
+                    "count": decision_episode_lines.len(),
+                },
+                "feedback_events": {
+                    "path": feedback_events_path.display().to_string(),
+                    "count": feedback_event_lines.len(),
+                },
+            },
+            "excluded_counts": {
+                "private_or_no_train": private_or_no_train_record_ids.len(),
+            }
+        });
+        self.write_pretty_json(&manifest_path, &manifest)?;
 
-        assert_eq!(approved.len(), 1);
-        assert_eq!(candidates.len(), 1);
-        assert_eq!(candidates[0].id, relevant_candidate.id);
+        Ok(ExportBundle {
+            output_dir: output_dir.display().to_string(),
+            approved_user_records: ExportFileSummary {
+                path: approved_path.display().to_string(),
+                count: approved_lines.len(),
+            },
+            candidate_user_records: ExportFileSummary {
+                path: candidate_path.display().to_string(),
+                count: candidate_lines.len(),
+            },
+            rejected_user_records: ExportFileSummary {
+                path: rejected_path.display().to_string(),
+                count: rejected_lines.len(),
+            },
+            decision_mirror_benchmark: ExportFileSummary {
+                path: benchmark_path.display().to_string(),
+                count: benchmark_lines.len(),
+            },
+            constitution_items: ExportFileSummary {
+                path: constitution_path.display().to_string(),
+                count: constitution_lines.len(),
+            },
+            action_gaps: ExportFileSummary {
+                path: action_gaps_path.display().to_string(),
+                count: action_gap_lines.len(),
+            },
+            decision_episodes: ExportFileSummary {
+                path: decision_episodes_path.display().to_string(),
+                count: decision_episode_lines.len(),
+            },
+            feedback_events: ExportFileSummary {
+                path: feedback_events_path.display().to_string(),
+                count: feedback_event_lines.len(),
+            },
+            train: ExportFileSummary {
+                path: train_path.display().to_string(),
+                count: train_lines.len(),
+            },
+            eval: ExportFileSummary {
+                path: eval_path.display().to_string(),
+                count: eval_lines.len(),
+            },
+            holdout: ExportFileSummary {
+                path: holdout_path.display().to_string(),
+                count: holdout_lines.len(),
+            },
+            manifest_path: manifest_path.display().to_string(),
+            included_records: train_lines.len() + eval_lines.len() + holdout_lines.len(),
+            excluded_records: private_or_no_train_record_ids.len(),
+        })
     }
 
-    #[test]
-    fn context_records_exclude_rejected_private_and_no_train() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+    fn split_for_record(
+        record: &UserRecord,
+        eval_percentage: u8,
+        holdout_percentage: u8,
+    ) -> ExportSplit {
+        let key = format!(
+            "{}:{}:{}:{}",
+            record.id,
+            serde_json::to_string(&record.kind).unwrap_or_default(),
+            record.content,
+            record.updated_at
+        );
+        let bucket = Self::stable_bucket(&key);
 
-        for state in [
-            PromotionState::Rejected,
-            PromotionState::Private,
-            PromotionState::NoTrain,
-        ] {
-            store
-                .create_user_record(UserRecordCreate {
-                    kind: UserRecordKind::Preference,
-                    content: format!("Excluded record for red-team decision: {:?}", state),
-                    origin: RecordOrigin::User,
-                    evidence_refs: Vec::new(),
-                    confidence: 0.9,
-                    promotion_state: Some(state),
-                    valid_from: None,
-                    valid_until: None,
-                    links: Vec::new(),
-                    metadata: HashMap::new(),
-                })
-                .expect("record should create");
+        if bucket < holdout_percentage {
+            ExportSplit::Holdout
+        } else if bucket < holdout_percentage + eval_percentage {
+            ExportSplit::Eval
+        } else {
+            ExportSplit::Train
         }
-
-        let (approved, candidates) = store
-            .select_context_records("red-team decision")
-            .expect("context records should select");
-
-        assert!(approved.is_empty());
-        assert!(candidates.is_empty());
     }
 
-    #[test]
-    fn export_preserves_history_through_links_instead_of_overwriting() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        let old_record = store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::Preference,
-                content: "Preferred shorter answers earlier.".to_string(),
-                origin: RecordOrigin::User,
-                evidence_refs: Vec::new(),
-                confidence: 0.7,
-                promotion_state: Some(PromotionState::Endorsed),
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
-            })
-            .expect("old record should be created");
-
-        let new_record = store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::Preference,
-                content: "Now prefers blunt, longer answers when accuracy matters.".to_string(),
-                origin: RecordOrigin::User,
-                evidence_refs: Vec::new(),
-                confidence: 0.9,
-                promotion_state: Some(PromotionState::Endorsed),
-                valid_from: None,
-                valid_until: None,
-                links: vec![RecordLink {
-                    relation: RecordLinkType::Supersedes,
-                    target_record_id: old_record.id.clone(),
-                }],
-                metadata: HashMap::new(),
-            })
-            .expect("new record should be created");
-
-        let listed = store.list_user_records().expect("records should list");
-        let old = listed
-            .iter()
-            .find(|record| record.id == old_record.id)
-            .expect("old record should remain present");
-        let new = listed
-            .iter()
-            .find(|record| record.id == new_record.id)
-            .expect("new record should remain present");
-
-        assert!(old.links.is_empty());
-        assert_eq!(new.links.len(), 1);
-        assert_eq!(new.links[0].target_record_id, old_record.id);
+    fn stable_bucket(key: &str) -> u8 {
+        let mut hasher = DefaultHasher::new();
+        key.hash(&mut hasher);
+        (hasher.finish() % 100) as u8
     }
 
-    fn endorsed_record(store: &mut TwinStore, content: &str, confidence: f32) -> UserRecord {
-        store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::Preference,
-                content: content.to_string(),
-                origin: RecordOrigin::User,
-                evidence_refs: Vec::new(),
-                confidence,
-                promotion_state: Some(PromotionState::Endorsed),
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
-            })
-            .expect("record should be created")
+    fn record_to_export_value(record: &UserRecord) -> serde_json::Value {
+        serde_json::json!({
+            "id": record.id,
+            "kind": record.kind,
+            "content": record.content,
+            "origin": record.origin,
+            "promotion_state": record.promotion_state,
+            "confidence": record.confidence,
+            "created_at": record.created_at,
+            "updated_at": record.updated_at,
+            "valid_from": record.valid_from,
+            "valid_until": record.valid_until,
+            "links": record.links,
+            "evidence_refs": record.evidence_refs,
+            "metadata": record.metadata,
+        })
     }
 
-    #[test]
-    fn approved_records_are_relevance_gated_with_confidence_fallback() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        endorsed_record(
-            &mut store,
-            "Prefers remote work over relocation for salary",
-            0.6,
-        );
-        endorsed_record(&mut store, "Enjoys woodworking podcasts on weekends", 0.9);
+    fn write_jsonl_file(&self, path: &Path, lines: &[String]) -> Result<()> {
+        let mut content = lines.join("\n");
+        if !content.is_empty() {
+            content.push('\n');
+        }
+        write_atomic(path, content.as_bytes())
+            .with_context(|| format!("Failed to write JSONL file: {}", path.display()))
+    }
 
-        let (approved, _) = store
-            .select_context_records("Should I accept the relocation offer for more salary?")
-            .expect("selection should succeed");
-        assert_eq!(approved.len(), 1);
-        assert!(approved[0].content.contains("relocation"));
+}
 
-        // No keyword overlap at all: fall back to top-confidence records
-        // instead of an empty behavioral context.
-        let (fallback, _) = store
-            .select_context_records("zzz qqq xyzzy")
-            .expect("fallback selection should succeed");
-        assert!(!fallback.is_empty());
-        assert!(fallback.len() <= MAX_TWIN_APPROVED_FALLBACK_RECORDS);
-        assert!(fallback[0].content.contains("woodworking"));
-    }
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::models::note::{Note, NoteStatus};
+    use crate::models::twin::{
+        default_record_confidence, PromotionState, RecordLink, RecordLinkType, UserRecordKind,
+    };
+    use tempfile::tempdir;
 
+    use crate::models::twin::ConstitutionStatus;
     fn test_note(id: &str, title: &str, content: &str, source_type: Option<&str>) -> Note {
         let now = Utc::now();
         let mut properties = HashMap::new();
@@ -5924,4 +4638,5 @@ mod tests {
         assert!(!feedback_content.contains(&private_event.id));
         assert!(feedback_content.contains(&exportable_event.id));
     }
+
 }
diff --git a/frontend/src-tauri/src/services/twin/records.rs b/frontend/src-tauri/src/services/twin/records.rs
new file mode 100644
index 0000000..be0b205
--- /dev/null
+++ b/frontend/src-tauri/src/services/twin/records.rs
@@ -0,0 +1,1337 @@
+use crate::models::note::Note;
+use crate::models::twin::{
+    ActionGap, ActionGapCreate, ConstitutionInferenceSummary, ConstitutionItem,
+    ConstitutionItemCreate, ConstitutionItemUpdate, ConstitutionReviewRequest, ConstitutionSetup,
+    ConstitutionStatus, DecisionEpisode, DecisionEpisodeCreate, DecisionEpisodeWithReflections,
+    DecisionEvidencePacket, DecisionEvidenceSource, DecisionMirrorConfig,
+    DecisionMirrorConfigUpdate, DecisionMirrorWeights, DecisionOutcomeUpdate, EvidenceRef,
+    ExportBundle, ExportFileSummary, MemoryDigestAction, MemoryDigestItem,
+    MemoryDigestReviewRequest, MemoryDigestState, PromotionState, RecordOrigin, ReflectionCard,
+    ReflectionCardCreate, ReflectionScores, ResolvedEvidenceRef, SessionTrace, TraceEvent,
+    TraceEventType, TwinContextRecord, TwinExportRequest, TwinInferenceRunSummary, TwinPrediction,
+    TwinPredictionDraft, TwinReviewRecord, UserRecord, UserRecordCreate, UserRecordKind,
+    UserRecordUpdate,
+};
+#[cfg(test)]
+use crate::models::twin::{DecisionMirrorPreset, PrimitiveDecisionAssessment};
+use crate::services::atomic_io::write_atomic;
+use anyhow::{Context, Result};
+use chrono::Utc;
+use serde::de::DeserializeOwned;
+use serde::Serialize;
+use serde_json::{json, Value};
+use std::collections::hash_map::DefaultHasher;
+use std::collections::HashMap;
+use std::collections::HashSet;
+use std::hash::{Hash, Hasher};
+use std::path::{Path, PathBuf};
+use std::time::{SystemTime, UNIX_EPOCH};
+use walkdir::WalkDir;
+use super::TwinStore;
+use super::shared::{event_text, evidence_note, excerpt, extract_event_model_id, extract_event_tile_id, lexical_terms, load_or_quarantine, payload_string, text_contains_any, value_contains_key};
+use super::{AUTO_PROMOTE_CONFIDENCE, AUTO_PROMOTE_SUPPORT_COUNT};
+
+const TWIN_INFERENCE_VERSION: &str = "local-signal-v1";
+const MAX_TWIN_CANDIDATE_CONTEXT_RECORDS: usize = 8;
+const MAX_TWIN_APPROVED_CONTEXT_RECORDS: usize = 12;
+const MAX_TWIN_APPROVED_FALLBACK_RECORDS: usize = 3;
+
+#[derive(Debug, Clone)]
+struct InferredRecordDraft {
+    inference_key: String,
+    signal_family: String,
+    kind: UserRecordKind,
+    content: String,
+    evidence_refs: Vec<EvidenceRef>,
+    evidence_event_ids: Vec<String>,
+    support_count: usize,
+    confidence: f32,
+}
+
+#[derive(Debug, Default)]
+struct SignalAccumulator {
+    evidence_refs: Vec<EvidenceRef>,
+    evidence_event_ids: HashSet<String>,
+}
+
+impl SignalAccumulator {
+    fn add_event(&mut self, trace: &SessionTrace, event: &TraceEvent) {
+        if !self.evidence_event_ids.insert(event.id.clone()) {
+            return;
+        }
+
+        self.evidence_refs.push(EvidenceRef {
+            trace_id: trace.id.clone(),
+            event_id: event.id.clone(),
+            session_id: trace.session_id.clone(),
+            tile_id: extract_event_tile_id(&event.payload),
+            model_id: extract_event_model_id(&event.payload),
+            note: evidence_note(event),
+            source_type: Some("behavior".to_string()),
+            source_id: Some(event.id.clone()),
+            source_label: evidence_note(event),
+            excerpt: Some(excerpt(&event_text(event))),
+            speaker_role: None,
+        });
+    }
+}
+
+fn infer_behavioral_records(traces: &[SessionTrace]) -> Vec<InferredRecordDraft> {
+    let mut signals: HashMap<String, SignalAccumulator> = HashMap::new();
+
+    for trace in traces {
+        for event in &trace.events {
+            match &event.event_type {
+                TraceEventType::PromptSubmitted => {
+                    let prompt = payload_string(&event.payload, &["prompt"]).unwrap_or_default();
+                    if event
+                        .payload
+                        .get("parent_tile_id")
+                        .is_some_and(|value| !value.is_null())
+                    {
+                        add_signal(&mut signals, "reasoning.iterative_deepening", trace, event);
+                    }
+                    if text_contains_any(
+                        &prompt,
+                        &["think harder", "revisit", "improve your previous answer"],
+                    ) {
+                        add_signal(&mut signals, "reasoning.iterative_deepening", trace, event);
+                    }
+                    if text_contains_any(
+                        &prompt,
+                        &[
+                            "implement",
+                            "fix",
+                            "test",
+                            "build",
+                            "file",
+                            "branch",
+                            "worktree",
+                        ],
+                    ) {
+                        add_signal(
+                            &mut signals,
+                            "preference.implementation_detail",
+                            trace,
+                            event,
+                        );
+                    }
+                    if payload_string(&event.payload, &["context_mode"])
+                        .is_some_and(|mode| mode == "knowledge_search" || mode == "semantic")
+                    {
+                        add_signal(&mut signals, "preference.grounded_context", trace, event);
+                    }
+                    if value_contains_key(&event.payload, "twin_domain") {
+                        add_signal(&mut signals, "fact.twin_domain_metadata", trace, event);
+                    }
+                }
+                TraceEventType::FeedbackRecorded => {
+                    let feedback_type =
+                        payload_string(&event.payload, &["feedback_type"]).unwrap_or_default();
+                    let text = event_text(event);
+
+                    match feedback_type.as_str() {
+                        "accept" => {
+                            if looks_structured(&text) {
+                                add_signal(
+                                    &mut signals,
+                                    "preference.structured_answers",
+                                    trace,
+                                    event,
+                                );
+                            }
+                            if looks_evidence_backed(&text) {
+                                add_signal(
+                                    &mut signals,
+                                    "preference.evidence_backed_detail",
+                                    trace,
+                                    event,
+                                );
+                            }
+                            if looks_implementation_detailed(&text) {
+                                add_signal(
+                                    &mut signals,
+                                    "preference.implementation_detail",
+                                    trace,
+                                    event,
+                                );
+                            }
+                        }
+                        "reject" => {
+                            add_signal(&mut signals, "preference.rejects_mismatch", trace, event);
+                        }
+                        "correction" => {
+                            add_signal(&mut signals, "preference.rejects_mismatch", trace, event);
+                            add_signal(&mut signals, "reasoning.corrects_ai_outputs", trace, event);
+                        }
+                        _ => {}
+                    }
+                }
+                TraceEventType::RankingRecorded => {
+                    add_signal(&mut signals, "reasoning.model_comparison", trace, event);
+                    let text = event_text(event);
+                    if looks_structured(&text) {
+                        add_signal(&mut signals, "preference.structured_answers", trace, event);
+                    }
+                    if looks_evidence_backed(&text) {
+                        add_signal(
+                            &mut signals,
+                            "preference.evidence_backed_detail",
+                            trace,
+                            event,
+                        );
+                    }
+                    if looks_implementation_detailed(&text) {
+                        add_signal(
+                            &mut signals,
+                            "preference.implementation_detail",
+                            trace,
+                            event,
+                        );
+                    }
+                }
+                TraceEventType::InsightCaptured => {
+                    add_signal(
+                        &mut signals,
+                        "reasoning.captures_self_knowledge",
+                        trace,
+                        event,
+                    );
+                }
+                TraceEventType::ModelsAdded => {
+                    add_signal(&mut signals, "reasoning.model_comparison", trace, event);
+                }
+                TraceEventType::DebateStarted | TraceEventType::DebateContinued => {
+                    add_signal(&mut signals, "reasoning.model_comparison", trace, event);
+                    add_signal(&mut signals, "reasoning.uses_debate", trace, event);
+                }
+                TraceEventType::NoteExported => {
+                    add_signal(
+                        &mut signals,
+                        "reasoning.curates_evidence_notes",
+                        trace,
+                        event,
+                    );
+                }
+                TraceEventType::NoteCanonicalPromoted => {
+                    add_signal(&mut signals, "reasoning.canonical_validation", trace, event);
+                }
+                TraceEventType::NoteCreated | TraceEventType::NoteUpdated => {
+                    if value_contains_key(&event.payload, "twin_domain") {
+                        add_signal(&mut signals, "fact.twin_domain_metadata", trace, event);
+                    }
+                    if payload_string(&event.payload, &["status"])
+                        .is_some_and(|status| status == "canonical")
+                    {
+                        add_signal(&mut signals, "reasoning.canonical_validation", trace, event);
+                    }
+                }
+                _ => {}
+            }
+        }
+    }
+
+    let mut drafts = signals
+        .into_iter()
+        .filter_map(|(key, accumulator)| {
+            let support_count = accumulator.evidence_refs.len();
+            if support_count == 0 {
+                return None;
+            }
+
+            let (kind, signal_family, content) = signal_definition(&key)?;
+            let mut evidence_event_ids = accumulator
+                .evidence_event_ids
+                .into_iter()
+                .collect::<Vec<_>>();
+            evidence_event_ids.sort();
+
+            Some(InferredRecordDraft {
+                inference_key: key,
+                signal_family: signal_family.to_string(),
+                kind,
+                content: content.to_string(),
+                confidence: confidence_for_support(support_count),
+                support_count,
+                evidence_refs: accumulator.evidence_refs,
+                evidence_event_ids,
+            })
+        })
+        .collect::<Vec<_>>();
+
+    drafts.sort_by(|a, b| a.inference_key.cmp(&b.inference_key));
+    drafts
+}
+
+fn add_signal(
+    signals: &mut HashMap<String, SignalAccumulator>,
+    key: &str,
+    trace: &SessionTrace,
+    event: &TraceEvent,
+) {
+    signals
+        .entry(key.to_string())
+        .or_default()
+        .add_event(trace, event);
+}
+
+fn signal_definition(key: &str) -> Option<(UserRecordKind, &'static str, &'static str)> {
+    match key {
+        "fact.twin_domain_metadata" => Some((
+            UserRecordKind::Fact,
+            "twin_domain",
+            "Uses twin_domain metadata to separate captured knowledge by the domain it belongs to.",
+        )),
+        "preference.structured_answers" => Some((
+            UserRecordKind::Preference,
+            "explicit_feedback",
+            "Prefers structured answers with headings, lists, or clear steps when judging model output.",
+        )),
+        "preference.evidence_backed_detail" => Some((
+            UserRecordKind::Preference,
+            "explicit_feedback",
+            "Prefers evidence-backed implementation detail over generic summary.",
+        )),
+        "preference.implementation_detail" => Some((
+            UserRecordKind::Preference,
+            "passive_prompting",
+            "Prefers answers that include concrete implementation details such as files, commands, tests, or code.",
+        )),
+        "preference.grounded_context" => Some((
+            UserRecordKind::Preference,
+            "passive_prompting",
+            "Uses existing notes as grounding context when asking models to reason.",
+        )),
+        "preference.rejects_mismatch" => Some((
+            UserRecordKind::Preference,
+            "explicit_feedback",
+            "Rejects or corrects responses that do not match their knowledge instead of saving them as truth.",
+        )),
+        "reasoning.corrects_ai_outputs" => Some((
+            UserRecordKind::ReasoningPattern,
+            "explicit_feedback",
+            "Provides corrections when model output conflicts with what they know.",
+        )),
+        "reasoning.iterative_deepening" => Some((
+            UserRecordKind::ReasoningPattern,
+            "branching",
+            "Revisits answers through branches or think-harder passes before treating them as settled.",
+        )),
+        "reasoning.model_comparison" => Some((
+            UserRecordKind::ReasoningPattern,
+            "model_selection",
+            "Compares multiple model outputs before selecting what matches their thinking.",
+        )),
+        "reasoning.uses_debate" => Some((
+            UserRecordKind::ReasoningPattern,
+            "debate_selection",
+            "Uses model debate or disagreement to test alternatives before deciding what to keep.",
+        )),
+        "reasoning.captures_self_knowledge" => Some((
+            UserRecordKind::ReasoningPattern,
+            "explicit_feedback",
+            "Captures durable facts, preferences, or reasoning patterns as explicit twin records.",
+        )),
+        "reasoning.curates_evidence_notes" => Some((
+            UserRecordKind::ReasoningPattern,
+            "note_export",
+            "Turns useful canvas work into durable evidence notes.",
+        )),
+        "reasoning.canonical_validation" => Some((
+            UserRecordKind::ReasoningPattern,
+            "canonical_promotion",
+            "Promotes knowledge to canonical notes after review or repeated validation.",
+        )),
+        _ => None,
+    }
+}
+
+fn confidence_for_support(support_count: usize) -> f32 {
+    (0.45 + support_count as f32 * 0.10).min(0.95)
+}
+
+fn build_inference_metadata(
+    draft: &InferredRecordDraft,
+    auto_promoted: bool,
+) -> HashMap<String, Value> {
+    json!({
+        "inference_key": draft.inference_key,
+        "inference_version": TWIN_INFERENCE_VERSION,
+        "signal_family": draft.signal_family,
+        "support_count": draft.support_count,
+        "evidence_event_ids": draft.evidence_event_ids,
+        "auto_promoted": auto_promoted,
+    })
+    .as_object()
+    .cloned()
+    .unwrap_or_default()
+    .into_iter()
+    .collect()
+}
+
+fn merge_promotion_history(
+    existing: HashMap<String, Value>,
+    mut next: HashMap<String, Value>,
+) -> HashMap<String, Value> {
+    for (key, value) in existing {
+        next.entry(key).or_insert(value);
+    }
+    next
+}
+
+fn append_promotion_history(
+    metadata: &mut HashMap<String, Value>,
+    from: &PromotionState,
+    to: &PromotionState,
+    rationale: Option<&str>,
+    automatic: bool,
+) {
+    let mut history = metadata
+        .get("promotion_history")
+        .and_then(Value::as_array)
+        .cloned()
+        .unwrap_or_default();
+
+    history.push(json!({
+        "from": from,
+        "to": to,
+        "at": Utc::now(),
+        "rationale": rationale,
+        "automatic": automatic,
+    }));
+    metadata.insert("promotion_history".to_string(), Value::Array(history));
+}
+
+fn promotion_state_sort_key(state: &PromotionState) -> u8 {
+    match state {
+        PromotionState::AutoPromoted => 0,
+        PromotionState::Candidate => 1,
+        PromotionState::Endorsed => 2,
+        PromotionState::Rejected => 3,
+        PromotionState::Private => 4,
+        PromotionState::NoTrain => 5,
+    }
+}
+
+fn twin_context_record(record: &UserRecord, source_label: &str) -> TwinContextRecord {
+    TwinContextRecord {
+        id: record.id.clone(),
+        kind: record.kind.clone(),
+        content: record.content.clone(),
+        confidence: record.confidence,
+        promotion_state: record.promotion_state.clone(),
+        evidence_count: record.evidence_refs.len(),
+        source_label: Some(source_label.to_string()),
+    }
+}
+
+fn twin_record_relevance(record: &UserRecord, query_terms: &HashSet<String>) -> usize {
+    if query_terms.is_empty() {
+        return 0;
+    }
+
+    let mut haystack = record.content.clone();
+    for evidence in &record.evidence_refs {
+        if let Some(note) = &evidence.note {
+            haystack.push(' ');
+            haystack.push_str(note);
+        }
+    }
+    for value in record.metadata.values() {
+        haystack.push(' ');
+        haystack.push_str(&value.to_string());
+    }
+
+    let record_terms = lexical_terms(&haystack);
+    query_terms.intersection(&record_terms).count()
+}
+
+fn looks_structured(text: &str) -> bool {
+    text.contains("\n- ")
+        || text.contains("\n* ")
+        || text.contains("\n1. ")
+        || text.contains("##")
+        || text.contains("```")
+}
+
+fn looks_evidence_backed(text: &str) -> bool {
+    text_contains_any(
+        text,
+        &[
+            "evidence",
+            "source",
+            "according",
+            "because",
+            "verify",
+            "verified",
+            "test",
+            "logs",
+            "tradeoff",
+        ],
+    )
+}
+
+fn looks_implementation_detailed(text: &str) -> bool {
+    text_contains_any(
+        text,
+        &[
+            ".rs",
+            ".js",
+            ".vue",
+            "frontend/",
+            "src/",
+            "cargo ",
+            "npm ",
+            "test",
+            "function ",
+            "```",
+            "command",
+            "file",
+        ],
+    )
+}
+
+
+impl TwinStore {
+    pub fn list_user_records(&mut self) -> Result<Vec<UserRecord>> {
+        self.ensure_record_cache()?;
+        let mut records: Vec<UserRecord> = self.record_cache.values().cloned().collect();
+        records.sort_by(|a, b| b.updated_at.cmp(&a.updated_at));
+        Ok(records)
+    }
+
+    pub fn get_user_record(&mut self, id: &str) -> Result<UserRecord> {
+        Self::validate_file_id(id)?;
+        if let Some(record) = self.record_cache.get(id) {
+            return Ok(record.clone());
+        }
+
+        let path = self.record_file_path(id);
+        let record = self.read_record_file(&path)?;
+        self.record_cache.insert(id.to_string(), record.clone());
+        Ok(record)
+    }
+
+    pub fn create_user_record(&mut self, create: UserRecordCreate) -> Result<UserRecord> {
+        self.ensure_record_cache()?;
+
+        let now = Utc::now();
+        let promotion_state = create
+            .promotion_state
+            .unwrap_or_else(|| PromotionState::default_for_origin(&create.origin));
+
+        let record = UserRecord {
+            id: uuid::Uuid::new_v4().to_string(),
+            kind: create.kind,
+            content: create.content,
+            evidence_refs: create.evidence_refs,
+            confidence: create.confidence.clamp(0.0, 1.0),
+            origin: create.origin,
+            promotion_state,
+            created_at: now,
+            updated_at: now,
+            valid_from: create.valid_from,
+            valid_until: create.valid_until,
+            links: create.links,
+            metadata: create.metadata,
+        };
+
+        self.record_cache.insert(record.id.clone(), record.clone());
+        self.write_record_file(&record)?;
+
+        Ok(record)
+    }
+
+    pub fn update_user_record(&mut self, id: &str, update: UserRecordUpdate) -> Result<UserRecord> {
+        self.ensure_record_cache()?;
+        let mut record = self.get_user_record(id)?;
+
+        if let Some(content) = update.content {
+            record.content = content;
+        }
+        if let Some(confidence) = update.confidence {
+            record.confidence = confidence.clamp(0.0, 1.0);
+        }
+        if let Some(promotion_state) = update.promotion_state {
+            record.promotion_state = promotion_state;
+        }
+        if let Some(valid_from) = update.valid_from {
+            record.valid_from = Some(valid_from);
+        }
+        if let Some(valid_until) = update.valid_until {
+            record.valid_until = Some(valid_until);
+        }
+        if let Some(links) = update.links {
+            record.links = links;
+        }
+        if let Some(metadata) = update.metadata {
+            record.metadata = metadata;
+        }
+
+        record.updated_at = Utc::now();
+        self.record_cache.insert(record.id.clone(), record.clone());
+        self.write_record_file(&record)?;
+
+        Ok(record)
+    }
+
+    pub fn run_twin_inference(&mut self) -> Result<TwinInferenceRunSummary> {
+        self.ensure_record_cache()?;
+        let traces = self.list_session_traces()?;
+        let scanned_events = traces.iter().map(|trace| trace.events.len()).sum::<usize>();
+        let drafts = infer_behavioral_records(&traces);
+
+        let mut existing_by_key = HashMap::new();
+        let mut rejected_keys = HashSet::new();
+        for record in self.record_cache.values() {
+            if let Some(inference_key) = record
+                .metadata
+                .get("inference_key")
+                .and_then(Value::as_str)
+                .map(ToOwned::to_owned)
+            {
+                existing_by_key.insert(inference_key.clone(), record.id.clone());
+                if record.promotion_state == PromotionState::Rejected {
+                    rejected_keys.insert(inference_key);
+                }
+            }
+        }
+
+        let mut created_records = 0_usize;
+        let mut updated_records = 0_usize;
+        let mut auto_promoted_records = 0_usize;
+        let mut candidate_records = 0_usize;
+        let mut skipped_rejected_records = 0_usize;
+
+        for draft in drafts {
+            let desired_state = if draft.confidence >= AUTO_PROMOTE_CONFIDENCE
+                && draft.support_count >= AUTO_PROMOTE_SUPPORT_COUNT
+            {
+                PromotionState::AutoPromoted
+            } else {
+                PromotionState::Candidate
+            };
+            let mut metadata =
+                build_inference_metadata(&draft, desired_state == PromotionState::AutoPromoted);
+
+            if let Some(existing_id) = existing_by_key.get(&draft.inference_key).cloned() {
+                let mut record = self.get_user_record(&existing_id)?;
+                let previous_state = record.promotion_state.clone();
+                let is_rejected_key = rejected_keys.contains(&draft.inference_key);
+
+                record.kind = draft.kind.clone();
+                record.content = draft.content.clone();
+                record.evidence_refs = draft.evidence_refs.clone();
+                record.confidence = draft.confidence;
+                record.origin = RecordOrigin::Inferred;
+
+                if is_rejected_key {
+                    metadata.insert("auto_promoted".to_string(), Value::Bool(false));
+                    record.promotion_state = PromotionState::Rejected;
+                    skipped_rejected_records += 1;
+                } else if matches!(
+                    record.promotion_state,
+                    PromotionState::Candidate | PromotionState::AutoPromoted
+                ) {
+                    record.promotion_state = desired_state.clone();
+                }
+
+                metadata = merge_promotion_history(record.metadata.clone(), metadata);
+                if previous_state != record.promotion_state {
+                    append_promotion_history(
+                        &mut metadata,
+                        &previous_state,
+                        &record.promotion_state,
+                        Some("local signal inference threshold"),
+                        true,
+                    );
+                }
+
+                record.metadata = metadata;
+                record.updated_at = Utc::now();
+                self.record_cache.insert(record.id.clone(), record.clone());
+                self.write_record_file(&record)?;
+                updated_records += 1;
+            } else {
+                let mut metadata = metadata;
+                if desired_state == PromotionState::AutoPromoted {
+                    append_promotion_history(
+                        &mut metadata,
+                        &PromotionState::Candidate,
+                        &PromotionState::AutoPromoted,
+                        Some("confidence >= 0.75 and support_count >= 3"),
+                        true,
+                    );
+                }
+
+                self.create_user_record(UserRecordCreate {
+                    kind: draft.kind,
+                    content: draft.content,
+                    evidence_refs: draft.evidence_refs,
+                    confidence: draft.confidence,
+                    origin: RecordOrigin::Inferred,
+                    promotion_state: Some(desired_state),
+                    valid_from: None,
+                    valid_until: None,
+                    links: Vec::new(),
+                    metadata,
+                })?;
+                created_records += 1;
+            }
+        }
+
+        for record in self.record_cache.values() {
+            if record.origin != RecordOrigin::Inferred {
+                continue;
+            }
+            match record.promotion_state {
+                PromotionState::AutoPromoted => auto_promoted_records += 1,
+                PromotionState::Candidate => candidate_records += 1,
+                _ => {}
+            }
+        }
+
+        Ok(TwinInferenceRunSummary {
+            inference_version: TWIN_INFERENCE_VERSION.to_string(),
+            scanned_traces: traces.len(),
+            scanned_events,
+            created_records,
+            updated_records,
+            auto_promoted_records,
+            candidate_records,
+            skipped_rejected_records,
+            generated_at: Utc::now(),
+        })
+    }
+
+    pub fn get_twin_review(&mut self) -> Result<Vec<TwinReviewRecord>> {
+        let records = self.list_user_records()?;
+        let mut review = Vec::with_capacity(records.len());
+
+        for record in records {
+            let evidence = self.resolve_evidence_refs(&record.evidence_refs)?;
+            review.push(TwinReviewRecord {
+                evidence_count: record.evidence_refs.len(),
+                latest_evidence: evidence.into_iter().max_by_key(|item| item.created_at),
+                record,
+            });
+        }
+
+        review.sort_by(|a, b| {
+            promotion_state_sort_key(&a.record.promotion_state)
+                .cmp(&promotion_state_sort_key(&b.record.promotion_state))
+                .then_with(|| b.record.updated_at.cmp(&a.record.updated_at))
+        });
+
+        Ok(review)
+    }
+
+    pub fn select_context_records(
+        &mut self,
+        query: &str,
+    ) -> Result<(Vec<TwinContextRecord>, Vec<TwinContextRecord>)> {
+        self.ensure_record_cache()?;
+
+        let query_terms = lexical_terms(query);
+        let mut approved = Vec::new();
+        let mut approved_fallback = Vec::new();
+        let mut candidates = Vec::new();
+
+        for record in self.record_cache.values() {
+            match record.promotion_state {
+                PromotionState::Endorsed | PromotionState::AutoPromoted => {
+                    let relevance = twin_record_relevance(record, &query_terms);
+                    if relevance > 0 {
+                        approved.push((relevance, twin_context_record(record, "approved")));
+                    } else {
+                        approved_fallback.push(twin_context_record(record, "approved"));
+                    }
+                }
+                PromotionState::Candidate => {
+                    let relevance = twin_record_relevance(record, &query_terms);
+                    if relevance > 0 {
+                        candidates.push((
+                            relevance,
+                            record.updated_at,
+                            twin_context_record(record, "candidate"),
+                        ));
+                    }
+                }
+                PromotionState::Rejected | PromotionState::Private | PromotionState::NoTrain => {}
+            }
+        }
+
+        approved.sort_by(|a, b| {
+            b.0.cmp(&a.0).then_with(|| {
+                b.1.confidence
+                    .partial_cmp(&a.1.confidence)
+                    .unwrap_or(std::cmp::Ordering::Equal)
+                    .then_with(|| b.1.evidence_count.cmp(&a.1.evidence_count))
+            })
+        });
+
+        let approved: Vec<TwinContextRecord> = if approved.is_empty() {
+            // Never assemble an empty behavioral context just because the
+            // query shares no keywords with any approved record.
+            approved_fallback.sort_by(|a, b| {
+                b.confidence
+                    .partial_cmp(&a.confidence)
+                    .unwrap_or(std::cmp::Ordering::Equal)
+                    .then_with(|| b.evidence_count.cmp(&a.evidence_count))
+            });
+            approved_fallback
+                .into_iter()
+                .take(MAX_TWIN_APPROVED_FALLBACK_RECORDS)
+                .collect()
+        } else {
+            approved
+                .into_iter()
+                .take(MAX_TWIN_APPROVED_CONTEXT_RECORDS)
+                .map(|(_, record)| record)
+                .collect()
+        };
+
+        candidates.sort_by(|a, b| {
+            b.0.cmp(&a.0).then_with(|| b.1.cmp(&a.1)).then_with(|| {
+                b.2.confidence
+                    .partial_cmp(&a.2.confidence)
+                    .unwrap_or(std::cmp::Ordering::Equal)
+            })
+        });
+
+        Ok((
+            approved,
+            candidates
+                .into_iter()
+                .take(MAX_TWIN_CANDIDATE_CONTEXT_RECORDS)
+                .map(|(_, _, record)| record)
+                .collect(),
+        ))
+    }
+
+    pub fn resolve_user_record_evidence(&mut self, id: &str) -> Result<Vec<ResolvedEvidenceRef>> {
+        let record = self.get_user_record(id)?;
+        self.resolve_evidence_refs(&record.evidence_refs)
+    }
+
+    pub fn set_user_record_promotion(
+        &mut self,
+        id: &str,
+        promotion_state: PromotionState,
+        rationale: Option<String>,
+    ) -> Result<UserRecord> {
+        self.ensure_record_cache()?;
+        let mut record = self.get_user_record(id)?;
+        let previous_state = record.promotion_state.clone();
+        let now = Utc::now();
+
+        record.promotion_state = promotion_state.clone();
+        record.updated_at = now;
+
+        append_promotion_history(
+            &mut record.metadata,
+            &previous_state,
+            &promotion_state,
+            rationale.as_deref(),
+            false,
+        );
+
+        if promotion_state == PromotionState::Rejected {
+            record
+                .metadata
+                .insert("reverted_at".to_string(), json!(now));
+            record
+                .metadata
+                .insert("revert_reason".to_string(), json!(rationale));
+            record
+                .metadata
+                .insert("auto_promoted".to_string(), Value::Bool(false));
+        }
+
+        self.record_cache.insert(record.id.clone(), record.clone());
+        self.write_record_file(&record)?;
+
+        Ok(record)
+    }
+
+    pub(super) fn ensure_record_cache(&mut self) -> Result<()> {
+        if self.records_cache_ready {
+            return Ok(());
+        }
+
+        for entry in WalkDir::new(&self.records_path)
+            .min_depth(1)
+            .max_depth(1)
+            .into_iter()
+            .filter_map(|entry| entry.ok())
+        {
+            let path = entry.path();
+            if path.extension().is_some_and(|ext| ext == "json") {
+                if let Some(record) = load_or_quarantine::<UserRecord>(path, "record") {
+                    self.record_cache.insert(record.id.clone(), record);
+                }
+            }
+        }
+
+        self.records_cache_ready = true;
+        Ok(())
+    }
+
+    fn record_file_path(&self, record_id: &str) -> PathBuf {
+        self.records_path.join(format!("{}.json", record_id))
+    }
+
+    fn read_record_file(&self, path: &Path) -> Result<UserRecord> {
+        let content = std::fs::read_to_string(path)
+            .with_context(|| format!("Failed to read record file: {}", path.display()))?;
+        serde_json::from_str(&content)
+            .with_context(|| format!("Failed to parse record file: {}", path.display()))
+    }
+
+    pub(super) fn write_record_file(&self, record: &UserRecord) -> Result<()> {
+        let path = self.record_file_path(&record.id);
+        self.write_pretty_json(&path, record)
+    }
+
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::models::note::{Note, NoteStatus};
+    use crate::models::twin::{
+        default_record_confidence, PromotionState, RecordLink, RecordLinkType, UserRecordKind,
+    };
+    use tempfile::tempdir;
+
+    #[test]
+    fn user_record_writes_are_atomic_with_no_tmp_litter() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        let record = store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::Preference,
+                content: "Prefers atomic writes".to_string(),
+                origin: RecordOrigin::User,
+                evidence_refs: Vec::new(),
+                confidence: default_record_confidence(),
+                promotion_state: None,
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
+            })
+            .expect("record should be created");
+
+        let record_file = store.records_path.join(format!("{}.json", record.id));
+        let persisted = std::fs::read_to_string(&record_file).expect("record file should exist");
+        assert!(persisted.contains("Prefers atomic writes"));
+        crate::services::atomic_io::assert_no_tmp_siblings(&store.records_path);
+    }
+
+    #[test]
+    fn synthetic_records_require_endorsement_for_export() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        let synthetic = store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::Preference,
+                content: "Synthesized summary".to_string(),
+                origin: RecordOrigin::Synthetic,
+                evidence_refs: Vec::new(),
+                confidence: default_record_confidence(),
+                promotion_state: None,
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
+            })
+            .expect("synthetic record should be created");
+
+        let bundle = store
+            .export_bundle(TwinExportRequest::default())
+            .expect("export should succeed");
+        assert_eq!(bundle.included_records, 0);
+
+        store
+            .update_user_record(
+                &synthetic.id,
+                UserRecordUpdate {
+                    promotion_state: Some(PromotionState::Endorsed),
+                    ..UserRecordUpdate::default()
+                },
+            )
+            .expect("synthetic record should update");
+
+        let bundle = store
+            .export_bundle(TwinExportRequest::default())
+            .expect("endorsed export should succeed");
+        assert_eq!(bundle.included_records, 1);
+    }
+
+    #[test]
+    fn user_records_auto_promote_and_export() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        let record = store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::Fact,
+                content: "I prefer blunt feedback over flattery.".to_string(),
+                origin: RecordOrigin::User,
+                evidence_refs: Vec::new(),
+                confidence: 0.9,
+                promotion_state: None,
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
+            })
+            .expect("user record should be created");
+
+        assert_eq!(record.promotion_state, PromotionState::AutoPromoted);
+
+        let bundle = store
+            .export_bundle(TwinExportRequest::default())
+            .expect("export should succeed");
+        assert_eq!(bundle.included_records, 1);
+        assert_eq!(bundle.approved_user_records.count, 1);
+    }
+
+    #[test]
+    fn inference_creates_candidate_below_threshold_and_auto_promotes_at_threshold() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        for index in 0..2 {
+            store
+                .append_trace_event(
+                    "session-1",
+                    TraceEventType::PromptSubmitted,
+                    serde_json::json!({
+                        "tile_id": format!("tile-{}", index),
+                        "prompt": "Please implement this with files and tests.",
+                        "models": ["openai/gpt-4o"],
+                    }),
+                )
+                .expect("trace event should append");
+        }
+
+        store.run_twin_inference().expect("inference should run");
+        let records = store.list_user_records().expect("records should list");
+        let record = records
+            .iter()
+            .find(|record| {
+                record.metadata.get("inference_key").and_then(Value::as_str)
+                    == Some("preference.implementation_detail")
+            })
+            .expect("implementation detail record should exist");
+        assert_eq!(record.promotion_state, PromotionState::Candidate);
+        assert_eq!(
+            record.metadata.get("support_count").and_then(Value::as_u64),
+            Some(2)
+        );
+
+        store
+            .append_trace_event(
+                "session-1",
+                TraceEventType::PromptSubmitted,
+                serde_json::json!({
+                    "tile_id": "tile-3",
+                    "prompt": "Fix the build and show exact commands.",
+                    "models": ["openai/gpt-4o"],
+                }),
+            )
+            .expect("trace event should append");
+
+        store.run_twin_inference().expect("inference should rerun");
+        let records = store.list_user_records().expect("records should list");
+        let record = records
+            .iter()
+            .find(|record| {
+                record.metadata.get("inference_key").and_then(Value::as_str)
+                    == Some("preference.implementation_detail")
+            })
+            .expect("implementation detail record should exist");
+        assert_eq!(record.promotion_state, PromotionState::AutoPromoted);
+        assert!(record.confidence >= AUTO_PROMOTE_CONFIDENCE);
+    }
+
+    #[test]
+    fn repeated_inference_updates_by_key_instead_of_duplicating() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        store
+            .append_trace_event(
+                "session-1",
+                TraceEventType::ModelsAdded,
+                serde_json::json!({
+                    "tile_id": "tile-1",
+                    "model_ids": ["openai/gpt-4o", "anthropic/claude"],
+                }),
+            )
+            .expect("trace event should append");
+
+        store
+            .run_twin_inference()
+            .expect("first inference should run");
+        store
+            .run_twin_inference()
+            .expect("second inference should run");
+
+        let inferred = store
+            .list_user_records()
+            .expect("records should list")
+            .into_iter()
+            .filter(|record| record.origin == RecordOrigin::Inferred)
+            .collect::<Vec<_>>();
+        assert_eq!(inferred.len(), 1);
+        assert_eq!(
+            inferred[0]
+                .metadata
+                .get("inference_key")
+                .and_then(Value::as_str),
+            Some("reasoning.model_comparison")
+        );
+    }
+
+    #[test]
+    fn rejected_inference_keys_are_not_auto_promoted_again() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        for index in 0..3 {
+            store
+                .append_trace_event(
+                    "session-1",
+                    TraceEventType::DebateStarted,
+                    serde_json::json!({
+                        "debate_id": format!("debate-{}", index),
+                        "source_tile_ids": ["tile-1"],
+                        "participating_models": ["a", "b"],
+                    }),
+                )
+                .expect("trace event should append");
+        }
+
+        store.run_twin_inference().expect("inference should run");
+        let record = store
+            .list_user_records()
+            .expect("records should list")
+            .into_iter()
+            .find(|record| {
+                record.metadata.get("inference_key").and_then(Value::as_str)
+                    == Some("reasoning.uses_debate")
+            })
+            .expect("debate record should exist");
+        assert_eq!(record.promotion_state, PromotionState::AutoPromoted);
+
+        store
+            .set_user_record_promotion(
+                &record.id,
+                PromotionState::Rejected,
+                Some("too broad".to_string()),
+            )
+            .expect("record should reject");
+        let summary = store.run_twin_inference().expect("inference should rerun");
+        let record = store
+            .get_user_record(&record.id)
+            .expect("record should load");
+
+        assert_eq!(record.promotion_state, PromotionState::Rejected);
+        assert!(summary.skipped_rejected_records >= 1);
+    }
+
+    #[test]
+    fn context_records_include_approved_and_only_relevant_candidates() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::Preference,
+                content: "Prefers evidence-backed implementation detail.".to_string(),
+                origin: RecordOrigin::User,
+                evidence_refs: Vec::new(),
+                confidence: 0.9,
+                promotion_state: Some(PromotionState::Endorsed),
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
+            })
+            .expect("approved record should create");
+        let relevant_candidate = store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::ReasoningPattern,
+                content: "May prefer red-team critique for shipping decisions.".to_string(),
+                origin: RecordOrigin::Inferred,
+                evidence_refs: Vec::new(),
+                confidence: 0.6,
+                promotion_state: Some(PromotionState::Candidate),
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
+            })
+            .expect("candidate should create");
+        store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::ReasoningPattern,
+                content: "May prefer visual design exploration.".to_string(),
+                origin: RecordOrigin::Inferred,
+                evidence_refs: Vec::new(),
+                confidence: 0.6,
+                promotion_state: Some(PromotionState::Candidate),
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
+            })
+            .expect("irrelevant candidate should create");
+
+        let (approved, candidates) = store
+            .select_context_records("Need red-team critique for this shipping decision")
+            .expect("context records should select");
+
+        assert_eq!(approved.len(), 1);
+        assert_eq!(candidates.len(), 1);
+        assert_eq!(candidates[0].id, relevant_candidate.id);
+    }
+
+    #[test]
+    fn context_records_exclude_rejected_private_and_no_train() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        for state in [
+            PromotionState::Rejected,
+            PromotionState::Private,
+            PromotionState::NoTrain,
+        ] {
+            store
+                .create_user_record(UserRecordCreate {
+                    kind: UserRecordKind::Preference,
+                    content: format!("Excluded record for red-team decision: {:?}", state),
+                    origin: RecordOrigin::User,
+                    evidence_refs: Vec::new(),
+                    confidence: 0.9,
+                    promotion_state: Some(state),
+                    valid_from: None,
+                    valid_until: None,
+                    links: Vec::new(),
+                    metadata: HashMap::new(),
+                })
+                .expect("record should create");
+        }
+
+        let (approved, candidates) = store
+            .select_context_records("red-team decision")
+            .expect("context records should select");
+
+        assert!(approved.is_empty());
+        assert!(candidates.is_empty());
+    }
+
+    #[test]
+    fn export_preserves_history_through_links_instead_of_overwriting() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        let old_record = store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::Preference,
+                content: "Preferred shorter answers earlier.".to_string(),
+                origin: RecordOrigin::User,
+                evidence_refs: Vec::new(),
+                confidence: 0.7,
+                promotion_state: Some(PromotionState::Endorsed),
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
+            })
+            .expect("old record should be created");
+
+        let new_record = store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::Preference,
+                content: "Now prefers blunt, longer answers when accuracy matters.".to_string(),
+                origin: RecordOrigin::User,
+                evidence_refs: Vec::new(),
+                confidence: 0.9,
+                promotion_state: Some(PromotionState::Endorsed),
+                valid_from: None,
+                valid_until: None,
+                links: vec![RecordLink {
+                    relation: RecordLinkType::Supersedes,
+                    target_record_id: old_record.id.clone(),
+                }],
+                metadata: HashMap::new(),
+            })
+            .expect("new record should be created");
+
+        let listed = store.list_user_records().expect("records should list");
+        let old = listed
+            .iter()
+            .find(|record| record.id == old_record.id)
+            .expect("old record should remain present");
+        let new = listed
+            .iter()
+            .find(|record| record.id == new_record.id)
+            .expect("new record should remain present");
+
+        assert!(old.links.is_empty());
+        assert_eq!(new.links.len(), 1);
+        assert_eq!(new.links[0].target_record_id, old_record.id);
+    }
+
+    fn endorsed_record(store: &mut TwinStore, content: &str, confidence: f32) -> UserRecord {
+        store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::Preference,
+                content: content.to_string(),
+                origin: RecordOrigin::User,
+                evidence_refs: Vec::new(),
+                confidence,
+                promotion_state: Some(PromotionState::Endorsed),
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
+            })
+            .expect("record should be created")
+    }
+
+    #[test]
+    fn approved_records_are_relevance_gated_with_confidence_fallback() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        endorsed_record(
+            &mut store,
+            "Prefers remote work over relocation for salary",
+            0.6,
+        );
+        endorsed_record(&mut store, "Enjoys woodworking podcasts on weekends", 0.9);
+
+        let (approved, _) = store
+            .select_context_records("Should I accept the relocation offer for more salary?")
+            .expect("selection should succeed");
+        assert_eq!(approved.len(), 1);
+        assert!(approved[0].content.contains("relocation"));
+
+        // No keyword overlap at all: fall back to top-confidence records
+        // instead of an empty behavioral context.
+        let (fallback, _) = store
+            .select_context_records("zzz qqq xyzzy")
+            .expect("fallback selection should succeed");
+        assert!(!fallback.is_empty());
+        assert!(fallback.len() <= MAX_TWIN_APPROVED_FALLBACK_RECORDS);
+        assert!(fallback[0].content.contains("woodworking"));
+    }
+
+}

From 3e747addd56b7fcb15a6ad1afa41108bdaeadcb0 Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 15:57:00 +0800
Subject: [PATCH 12/30] refactor: extract twin::constitution

Moves Constitution items, action gaps, guided setup, and constitution
inference (including interview-note extraction and vault-derived
staleness pruning) into services/twin/constitution.rs. constitution_file_path,
read_constitution_file, action_gap_file_path, read_action_gap_file, and
normalize_key_text are marked pub(super)/kept accessible: decisions.rs's
build_decision_evidence_packet reads constitution/action-gap labels by
id, and digest.rs's memory_digest_cluster_key falls back to
normalize_key_text. Verbatim move; tests move with their code.
---
 .../src/services/twin/constitution.rs         | 1747 +++++++++++++++
 frontend/src-tauri/src/services/twin/mod.rs   | 1924 +----------------
 2 files changed, 1860 insertions(+), 1811 deletions(-)
 create mode 100644 frontend/src-tauri/src/services/twin/constitution.rs

diff --git a/frontend/src-tauri/src/services/twin/constitution.rs b/frontend/src-tauri/src/services/twin/constitution.rs
new file mode 100644
index 0000000..dbb9f95
--- /dev/null
+++ b/frontend/src-tauri/src/services/twin/constitution.rs
@@ -0,0 +1,1747 @@
+use crate::models::note::Note;
+use crate::models::twin::{
+    ActionGap, ActionGapCreate, ConstitutionInferenceSummary, ConstitutionItem,
+    ConstitutionItemCreate, ConstitutionItemUpdate, ConstitutionReviewRequest, ConstitutionSetup,
+    ConstitutionStatus, DecisionEpisode, DecisionEpisodeCreate, DecisionEpisodeWithReflections,
+    DecisionEvidencePacket, DecisionEvidenceSource, DecisionMirrorConfig,
+    DecisionMirrorConfigUpdate, DecisionMirrorWeights, DecisionOutcomeUpdate, EvidenceRef,
+    ExportBundle, ExportFileSummary, MemoryDigestAction, MemoryDigestItem,
+    MemoryDigestReviewRequest, MemoryDigestState, PromotionState, RecordOrigin, ReflectionCard,
+    ReflectionCardCreate, ReflectionScores, ResolvedEvidenceRef, SessionTrace, TraceEvent,
+    TraceEventType, TwinContextRecord, TwinExportRequest, TwinInferenceRunSummary, TwinPrediction,
+    TwinPredictionDraft, TwinReviewRecord, UserRecord, UserRecordCreate, UserRecordKind,
+    UserRecordUpdate,
+};
+#[cfg(test)]
+use crate::models::twin::{DecisionMirrorPreset, PrimitiveDecisionAssessment};
+use crate::services::atomic_io::write_atomic;
+use anyhow::{Context, Result};
+use chrono::Utc;
+use serde::de::DeserializeOwned;
+use serde::Serialize;
+use serde_json::{json, Value};
+use std::collections::hash_map::DefaultHasher;
+use std::collections::HashMap;
+use std::collections::HashSet;
+use std::hash::{Hash, Hasher};
+use std::path::{Path, PathBuf};
+use std::time::{SystemTime, UNIX_EPOCH};
+use walkdir::WalkDir;
+use super::TwinStore;
+use super::shared::{excerpt, lexical_terms, load_or_quarantine, text_contains_any};
+use super::{AUTO_PROMOTE_SUPPORT_COUNT};
+
+fn clean_setup_entries(entries: Vec<String>) -> Vec<String> {
+    let mut seen = HashSet::new();
+    entries
+        .into_iter()
+        .map(|entry| entry.trim().to_string())
+        .filter(|entry| !entry.is_empty())
+        .filter(|entry| seen.insert(entry.to_lowercase()))
+        .collect()
+}
+
+fn clean_optional_setup_entry(entry: Option<String>) -> Option<String> {
+    entry
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+}
+
+fn constitution_key(dimension: &str, claim: &str) -> String {
+    format!(
+        "{}::{}",
+        dimension.trim().to_lowercase(),
+        normalize_key_text(claim)
+    )
+}
+
+fn action_gap_key(stated_value: &str, revealed_behavior: &str) -> String {
+    format!(
+        "{}::{}",
+        normalize_key_text(stated_value),
+        normalize_key_text(revealed_behavior)
+    )
+}
+
+pub(super) fn normalize_key_text(text: &str) -> String {
+    text.split_whitespace()
+        .collect::<Vec<_>>()
+        .join(" ")
+        .to_lowercase()
+}
+
+fn constitution_allows_record(record: &UserRecord) -> bool {
+    !matches!(
+        record.promotion_state,
+        PromotionState::Rejected | PromotionState::Private | PromotionState::NoTrain
+    ) && record.kind != UserRecordKind::Fact
+}
+
+fn behavior_event_for_constitution(event_type: &TraceEventType) -> bool {
+    matches!(
+        event_type,
+        TraceEventType::PromptSubmitted
+            | TraceEventType::FeedbackRecorded
+            | TraceEventType::RankingRecorded
+            | TraceEventType::InsightCaptured
+            | TraceEventType::DebateStarted
+            | TraceEventType::DebateContinued
+            | TraceEventType::NoteExported
+            | TraceEventType::NoteCanonicalPromoted
+            | TraceEventType::DecisionEpisodeCreated
+            | TraceEventType::OutcomeFollowUpRecorded
+    )
+}
+
+fn constitution_status_from_record(record: &UserRecord) -> ConstitutionStatus {
+    let support_count = record.evidence_refs.len();
+    match record.promotion_state {
+        PromotionState::AutoPromoted | PromotionState::Endorsed
+            if support_count >= AUTO_PROMOTE_SUPPORT_COUNT =>
+        {
+            ConstitutionStatus::Active
+        }
+        _ => ConstitutionStatus::Candidate,
+    }
+}
+
+fn constitution_context_allowed(status: &ConstitutionStatus) -> bool {
+    matches!(
+        status,
+        ConstitutionStatus::Active | ConstitutionStatus::Candidate | ConstitutionStatus::Softened
+    )
+}
+
+fn constitution_status_for_action(action: &MemoryDigestAction) -> ConstitutionStatus {
+    match action {
+        MemoryDigestAction::Keep => ConstitutionStatus::Active,
+        MemoryDigestAction::Soften => ConstitutionStatus::Softened,
+        MemoryDigestAction::NotMe => ConstitutionStatus::NotMe,
+        MemoryDigestAction::Private => ConstitutionStatus::Private,
+        MemoryDigestAction::NoTrain => ConstitutionStatus::NoTrain,
+        MemoryDigestAction::Reject => ConstitutionStatus::Rejected,
+    }
+}
+
+fn constitution_status_sort_key(status: &ConstitutionStatus) -> u8 {
+    match status {
+        ConstitutionStatus::Active => 0,
+        ConstitutionStatus::Candidate => 1,
+        ConstitutionStatus::Softened => 2,
+        ConstitutionStatus::NotMe => 3,
+        ConstitutionStatus::Private => 4,
+        ConstitutionStatus::NoTrain => 5,
+        ConstitutionStatus::Rejected => 6,
+    }
+}
+
+fn infer_constitution_dimension(content: &str, kind: &UserRecordKind) -> String {
+    let lower = content.to_lowercase();
+    if text_contains_any(&lower, &["taste", "aesthetic", "style", "design", "feel"]) {
+        "taste".to_string()
+    } else if text_contains_any(
+        &lower,
+        &["constraint", "deadline", "budget", "time", "cost"],
+    ) {
+        "constraints".to_string()
+    } else if text_contains_any(&lower, &["somatic", "gut", "body", "energy", "fatigue"]) {
+        "somatic".to_string()
+    } else if text_contains_any(&lower, &["value", "principle", "mission", "care about"]) {
+        "values".to_string()
+    } else {
+        match kind {
+            UserRecordKind::Preference => "preferences".to_string(),
+            UserRecordKind::ReasoningPattern => "reasoning".to_string(),
+            UserRecordKind::Fact => "facts".to_string(),
+        }
+    }
+}
+
+fn note_is_interview(note: &Note) -> bool {
+    note.properties
+        .get("source_type")
+        .or_else(|| note.properties.get("source"))
+        .and_then(Value::as_str)
+        .is_some_and(|value| value.eq_ignore_ascii_case("interview"))
+        || note
+            .tags
+            .iter()
+            .any(|tag| tag.eq_ignore_ascii_case("interview"))
+}
+
+#[derive(Debug, Clone)]
+struct InterviewTurn {
+    role: String,
+    content: String,
+}
+
+enum InterviewExtraction {
+    Unlabeled,
+    Labeled {
+        interviewer_turns: Vec<InterviewTurn>,
+        interviewee_turns: Vec<InterviewTurn>,
+    },
+}
+
+fn extract_interview_note_evidence(note: &Note) -> InterviewExtraction {
+    let turns = extract_markdown_interview_turns(&note.content)
+        .or_else(|| extract_colon_labeled_interview_turns(&note.content));
+    let Some(turns) = turns else {
+        return InterviewExtraction::Unlabeled;
+    };
+    let interviewer_turns = turns
+        .iter()
+        .filter(|turn| turn.role == "user")
+        .cloned()
+        .collect::<Vec<_>>();
+    let interviewee_turns = turns
+        .into_iter()
+        .filter(|turn| turn.role == "interviewee")
+        .collect::<Vec<_>>();
+    if interviewer_turns.is_empty() || interviewee_turns.is_empty() {
+        return InterviewExtraction::Unlabeled;
+    }
+    InterviewExtraction::Labeled {
+        interviewer_turns,
+        interviewee_turns,
+    }
+}
+
+fn extract_markdown_interview_turns(content: &str) -> Option<Vec<InterviewTurn>> {
+    let mut turns = Vec::new();
+    let mut current_role: Option<String> = None;
+    let mut current_content = String::new();
+    for line in content.lines() {
+        let trimmed = line.trim();
+        if let Some(role) = markdown_message_role(trimmed) {
+            flush_interview_turn(&mut turns, &mut current_role, &mut current_content);
+            current_role = Some(role);
+            continue;
+        }
+        if current_role.is_some() {
+            current_content.push_str(line);
+            current_content.push('\n');
+        }
+    }
+    flush_interview_turn(&mut turns, &mut current_role, &mut current_content);
+    if turns.len() >= 2 {
+        Some(turns)
+    } else {
+        None
+    }
+}
+
+fn markdown_message_role(line: &str) -> Option<String> {
+    let lower = line.to_lowercase();
+    if !(lower.starts_with("### message") || lower.starts_with("## message")) {
+        return None;
+    }
+    if lower.contains("interviewee") || lower.contains("participant") {
+        Some("interviewee".to_string())
+    } else if lower.contains("user")
+        || lower.contains("interviewer")
+        || lower.contains("researcher")
+    {
+        Some("user".to_string())
+    } else {
+        None
+    }
+}
+
+fn extract_colon_labeled_interview_turns(content: &str) -> Option<Vec<InterviewTurn>> {
+    let mut turns = Vec::new();
+    for line in content.lines() {
+        let Some((speaker, body)) = line.split_once(':') else {
+            continue;
+        };
+        let speaker = speaker.trim().to_lowercase();
+        let role = match speaker.as_str() {
+            "interviewer" | "researcher" | "moderator" | "facilitator" | "me" | "user" => "user",
+            "interviewee" | "participant" | "respondent" | "customer" | "student" | "teacher" => {
+                "interviewee"
+            }
+            _ => continue,
+        };
+        let content = body.trim();
+        if !content.is_empty() {
+            turns.push(InterviewTurn {
+                role: role.to_string(),
+                content: content.to_string(),
+            });
+        }
+    }
+    if turns.len() >= 2 {
+        Some(turns)
+    } else {
+        None
+    }
+}
+
+fn flush_interview_turn(
+    turns: &mut Vec<InterviewTurn>,
+    current_role: &mut Option<String>,
+    current_content: &mut String,
+) {
+    let Some(role) = current_role.take() else {
+        return;
+    };
+    let content = current_content.trim().to_string();
+    current_content.clear();
+    if content.is_empty() {
+        return;
+    }
+    turns.push(InterviewTurn { role, content });
+}
+
+fn constitution_claim_from_interviewer_turn(content: &str) -> Option<(String, String)> {
+    let lower = content.to_lowercase();
+    if text_contains_any(
+        &lower,
+        &[
+            "concrete example",
+            "compare",
+            "why",
+            "how do you",
+            "what makes",
+            "walk me through",
+        ],
+    ) {
+        return Some((
+            "reasoning".to_string(),
+            "Uses interview questions to probe for concrete examples and comparisons before treating claims as useful.".to_string(),
+        ));
+    }
+    None
+}
+
+fn looks_like_research_finding(content: &str) -> bool {
+    content.split_whitespace().count() >= 8
+        && text_contains_any(
+            content,
+            &[
+                "need", "want", "trust", "frustrat", "prefer", "hard", "easy", "useful", "demo",
+                "workflow",
+            ],
+        )
+}
+
+fn constitution_claim_from_note(note: &Note) -> Option<(String, String)> {
+    if note.is_topic_hub() {
+        return None;
+    }
+    let content = note.content.trim();
+    if content.len() < 24 {
+        return None;
+    }
+    let lower = content.to_lowercase();
+    if !text_contains_any(
+        &lower,
+        &[
+            "i prefer",
+            "i need",
+            "i value",
+            "my reasoning",
+            "works for me",
+            "not me",
+            "i reject",
+            "i decide",
+        ],
+    ) {
+        return None;
+    }
+    if text_contains_any(&lower, &["prefer"]) {
+        Some((
+            "preferences".to_string(),
+            format!("Note-backed preference: {}", excerpt(content)),
+        ))
+    } else {
+        Some((
+            "reasoning".to_string(),
+            format!("Note-backed reasoning pattern: {}", excerpt(content)),
+        ))
+    }
+}
+
+fn note_evidence_ref(
+    note: &Note,
+    source_type: &str,
+    source_label: &str,
+    speaker_role: Option<&str>,
+    content: &str,
+) -> EvidenceRef {
+    EvidenceRef {
+        trace_id: format!("note-{}", note.id),
+        event_id: note.id.clone(),
+        session_id: "vault-note".to_string(),
+        tile_id: None,
+        model_id: None,
+        note: Some(note.title.clone()),
+        source_type: Some(source_type.to_string()),
+        source_id: Some(note.id.clone()),
+        source_label: Some(source_label.to_string()),
+        excerpt: Some(excerpt(content.trim())),
+        speaker_role: speaker_role.map(ToOwned::to_owned),
+    }
+}
+
+fn distill_constitution_setup_from_notes(notes: &[Note]) -> ConstitutionSetup {
+    let mut setup = ConstitutionSetup::default();
+    let mut saw_interview_question = false;
+    let mut saw_values_question = false;
+    let mut saw_tradeoff_question = false;
+    let mut saw_risk_question = false;
+    let mut saw_concrete_question = false;
+    let mut saw_followup_question = false;
+    let mut saw_user_note_preference = false;
+    let mut interviewer_question_count = 0_usize;
+
+    for note in notes {
+        if note.is_topic_hub() {
+            continue;
+        }
+
+        if note_is_interview(note) {
+            if let InterviewExtraction::Labeled {
+                interviewer_turns, ..
+            } = extract_interview_note_evidence(note)
+            {
+                for turn in interviewer_turns {
+                    let lower = turn.content.to_lowercase();
+                    if turn.content.split_whitespace().count() < 5 {
+                        continue;
+                    }
+                    saw_interview_question = true;
+                    interviewer_question_count += 1;
+                    if text_contains_any(&lower, &["value", "cultural", "drives your decision"]) {
+                        saw_values_question = true;
+                    }
+                    if text_contains_any(&lower, &["trade off", "trade-off", "balance"]) {
+                        saw_tradeoff_question = true;
+                    }
+                    if text_contains_any(&lower, &["risk", "comfortable taking", "actively avoid"])
+                    {
+                        saw_risk_question = true;
+                    }
+                    if text_contains_any(
+                        &lower,
+                        &[
+                            "example",
+                            "walk us through",
+                            "walk through",
+                            "concrete",
+                            "top two",
+                        ],
+                    ) {
+                        saw_concrete_question = true;
+                    }
+                    if text_contains_any(
+                        &lower,
+                        &["following up", "if i understand", "drill", "how would"],
+                    ) {
+                        saw_followup_question = true;
+                    }
+                }
+            }
+            continue;
+        }
+
+        if let Some((dimension, claim)) = constitution_claim_from_note(note) {
+            saw_user_note_preference = true;
+            match dimension.as_str() {
+                "preferences" => push_unique(&mut setup.tastes, claim),
+                "constraints" => push_unique(&mut setup.constraints, claim),
+                "action_tendency" => push_unique(&mut setup.action_tendencies, claim),
+                _ => push_unique(&mut setup.values, claim),
+            }
+        }
+    }
+
+    if saw_interview_question {
+        push_unique(
+            &mut setup.constraints,
+            "Keeps interviewee answers as research evidence rather than treating them as the user's own Constitution.".to_string(),
+        );
+        push_unique(
+            &mut setup.constraints,
+            "Requires speaker-labelled evidence before extracting Constitution or research findings.".to_string(),
+        );
+    }
+    if saw_values_question {
+        push_unique(
+            &mut setup.values,
+            "Probes for the values and cultural assumptions behind decisions, not only the visible decision outcome.".to_string(),
+        );
+    }
+    if saw_tradeoff_question {
+        push_unique(
+            &mut setup.values,
+            "Treats important choices as tradeoffs between innovation, stability, impact, and institutional responsibility.".to_string(),
+        );
+    }
+    if saw_risk_question {
+        push_unique(
+            &mut setup.constraints,
+            "Separates acceptable experiments from risks that harm people, courses, or institutional trust.".to_string(),
+        );
+    }
+    if saw_concrete_question {
+        push_unique(
+            &mut setup.tastes,
+            "Prefers concrete walkthroughs, examples, and decision stories over abstract positioning.".to_string(),
+        );
+    }
+    if saw_followup_question || (interviewer_question_count > 1 && saw_concrete_question) {
+        push_unique(
+            &mut setup.action_tendencies,
+            "Uses follow-up questions to move from broad narrative into specific decisions, assumptions, criteria, and consequences.".to_string(),
+        );
+    }
+    if saw_user_note_preference {
+        push_unique(
+            &mut setup.action_tendencies,
+            "Turns user-authored note evidence into reviewable Constitution candidates instead of accepting it silently.".to_string(),
+        );
+    }
+
+    setup
+}
+
+fn constitution_setup_entry_count(setup: &ConstitutionSetup) -> usize {
+    setup.values.len()
+        + setup.tastes.len()
+        + setup.constraints.len()
+        + setup.somatic_cues.len()
+        + setup.action_tendencies.len()
+}
+
+fn constitution_setup_claims(setup: &ConstitutionSetup) -> HashSet<String> {
+    setup
+        .values
+        .iter()
+        .chain(setup.tastes.iter())
+        .chain(setup.constraints.iter())
+        .chain(setup.somatic_cues.iter())
+        .chain(setup.action_tendencies.iter())
+        .map(|entry| entry.trim().to_string())
+        .filter(|entry| !entry.is_empty())
+        .collect()
+}
+
+fn push_unique(entries: &mut Vec<String>, entry: String) {
+    let normalized = entry.trim();
+    if normalized.is_empty() {
+        return;
+    }
+    if !entries
+        .iter()
+        .any(|existing| existing.eq_ignore_ascii_case(normalized))
+    {
+        entries.push(normalized.to_string());
+    }
+}
+
+fn constitution_item_is_vault_derived(item: &ConstitutionItem) -> bool {
+    matches!(
+        item.source.as_deref(),
+        Some("note_inference")
+            | Some("interview_behavior_inference")
+            | Some("interview_research_inference")
+    ) || item.evidence_refs.iter().any(|evidence| {
+        matches!(
+            evidence.source_type.as_deref(),
+            Some("note") | Some("interview-question") | Some("interview-answer")
+        )
+    })
+}
+
+fn record_is_vault_derived(record: &UserRecord) -> bool {
+    record.metadata.get("source_note_id").is_some()
+        || matches!(
+            record.metadata.get("source_type").and_then(Value::as_str),
+            Some("interview_answer") | Some("note")
+        )
+        || record.evidence_refs.iter().any(|evidence| {
+            matches!(
+                evidence.source_type.as_deref(),
+                Some("note") | Some("interview-question") | Some("interview-answer")
+            )
+        })
+}
+
+fn split_action_gap_claim(content: &str) -> Option<(String, String)> {
+    let lowered = content.to_lowercase();
+    for separator in [" but ", " however ", " yet ", " although "] {
+        if let Some(index) = lowered.find(separator) {
+            let left = content[..index].trim();
+            let right = content[index + separator.len()..].trim();
+            if left.len() >= 8 && right.len() >= 8 {
+                return Some((left.to_string(), right.to_string()));
+            }
+        }
+    }
+    None
+}
+
+fn constitution_item_relevance(item: &ConstitutionItem, query_terms: &HashSet<String>) -> usize {
+    if query_terms.is_empty() {
+        return 0;
+    }
+    let mut haystack = format!("{} {} {}", item.claim, item.dimension, item.scope.join(" "));
+    for tension in &item.tensions {
+        haystack.push(' ');
+        haystack.push_str(tension);
+    }
+    let item_terms = lexical_terms(&haystack);
+    query_terms.intersection(&item_terms).count()
+}
+
+fn action_gap_relevance(gap: &ActionGap, query_terms: &HashSet<String>) -> usize {
+    if query_terms.is_empty() {
+        return 0;
+    }
+    let mut haystack = format!(
+        "{} {} {}",
+        gap.stated_value, gap.revealed_behavior, gap.decision_risk
+    );
+    if let Some(driver) = &gap.driver_hypothesis {
+        haystack.push(' ');
+        haystack.push_str(driver);
+    }
+    if let Some(signal) = &gap.somatic_taste_signal {
+        haystack.push(' ');
+        haystack.push_str(signal);
+    }
+    let gap_terms = lexical_terms(&haystack);
+    query_terms.intersection(&gap_terms).count()
+}
+
+
+impl TwinStore {
+    pub fn list_constitution_items(&self) -> Result<Vec<ConstitutionItem>> {
+        let mut items = Vec::new();
+        if !self.constitution_path.exists() {
+            return Ok(items);
+        }
+
+        for entry in WalkDir::new(&self.constitution_path)
+            .min_depth(1)
+            .max_depth(1)
+            .into_iter()
+            .filter_map(|entry| entry.ok())
+        {
+            let path = entry.path();
+            if path.extension().is_some_and(|ext| ext == "json") {
+                if let Some(item) =
+                    load_or_quarantine::<ConstitutionItem>(path, "constitution item")
+                {
+                    items.push(item);
+                }
+            }
+        }
+
+        items.sort_by(|a, b| {
+            constitution_status_sort_key(&a.status)
+                .cmp(&constitution_status_sort_key(&b.status))
+                .then_with(|| {
+                    b.priority
+                        .partial_cmp(&a.priority)
+                        .unwrap_or(std::cmp::Ordering::Equal)
+                })
+                .then_with(|| b.updated_at.cmp(&a.updated_at))
+        });
+        Ok(items)
+    }
+
+    pub fn create_constitution_item(
+        &self,
+        create: ConstitutionItemCreate,
+    ) -> Result<ConstitutionItem> {
+        let now = Utc::now();
+        let item = ConstitutionItem {
+            id: uuid::Uuid::new_v4().to_string(),
+            claim: create.claim,
+            dimension: create.dimension,
+            scope: create.scope,
+            priority: create.priority.clamp(0.0, 1.0),
+            confidence: create.confidence.clamp(0.0, 1.0),
+            status: create.status,
+            evidence_refs: create.evidence_refs,
+            tensions: create.tensions,
+            linked_record_ids: create.linked_record_ids,
+            source: create.source,
+            created_at: now,
+            updated_at: now,
+        };
+        self.write_constitution_file(&item)?;
+        Ok(item)
+    }
+
+    pub fn update_constitution_item(
+        &self,
+        id: &str,
+        update: ConstitutionItemUpdate,
+    ) -> Result<ConstitutionItem> {
+        Self::validate_file_id(id)?;
+        let path = self.constitution_file_path(id);
+        let mut item = self.read_constitution_file(&path)?;
+        if let Some(claim) = update.claim {
+            item.claim = claim;
+        }
+        if let Some(dimension) = update.dimension {
+            item.dimension = dimension;
+        }
+        if let Some(scope) = update.scope {
+            item.scope = scope;
+        }
+        if let Some(priority) = update.priority {
+            item.priority = priority.clamp(0.0, 1.0);
+        }
+        if let Some(confidence) = update.confidence {
+            item.confidence = confidence.clamp(0.0, 1.0);
+        }
+        if let Some(status) = update.status {
+            item.status = status;
+        }
+        if let Some(tensions) = update.tensions {
+            item.tensions = tensions;
+        }
+        item.updated_at = Utc::now();
+        self.write_constitution_file(&item)?;
+        Ok(item)
+    }
+
+    pub fn review_constitution_item(
+        &mut self,
+        id: &str,
+        request: ConstitutionReviewRequest,
+    ) -> Result<ConstitutionItem> {
+        Self::validate_file_id(id)?;
+        let mut item = self.read_constitution_file(&self.constitution_file_path(id))?;
+        item.status = constitution_status_for_action(&request.action);
+        item.updated_at = Utc::now();
+        self.write_constitution_file(&item)?;
+        self.append_trace_event(
+            "constitution-review",
+            TraceEventType::ConstitutionItemReviewed,
+            json!({
+                "constitution_item_id": item.id,
+                "action": request.action,
+                "rationale": request.rationale,
+            }),
+        )?;
+        Ok(item)
+    }
+
+    pub fn list_action_gaps(&self) -> Result<Vec<ActionGap>> {
+        let mut gaps = Vec::new();
+        if !self.action_gaps_path.exists() {
+            return Ok(gaps);
+        }
+
+        for entry in WalkDir::new(&self.action_gaps_path)
+            .min_depth(1)
+            .max_depth(1)
+            .into_iter()
+            .filter_map(|entry| entry.ok())
+        {
+            let path = entry.path();
+            if path.extension().is_some_and(|ext| ext == "json") {
+                if let Some(gap) = load_or_quarantine::<ActionGap>(path, "action gap") {
+                    gaps.push(gap);
+                }
+            }
+        }
+
+        gaps.sort_by(|a, b| {
+            constitution_status_sort_key(&a.status)
+                .cmp(&constitution_status_sort_key(&b.status))
+                .then_with(|| {
+                    b.confidence
+                        .partial_cmp(&a.confidence)
+                        .unwrap_or(std::cmp::Ordering::Equal)
+                })
+                .then_with(|| b.updated_at.cmp(&a.updated_at))
+        });
+        Ok(gaps)
+    }
+
+    pub fn create_action_gap(&self, create: ActionGapCreate) -> Result<ActionGap> {
+        let now = Utc::now();
+        let gap = ActionGap {
+            id: uuid::Uuid::new_v4().to_string(),
+            stated_value: create.stated_value,
+            revealed_behavior: create.revealed_behavior,
+            driver_hypothesis: create.driver_hypothesis,
+            somatic_taste_signal: create.somatic_taste_signal,
+            decision_risk: create.decision_risk,
+            evidence_refs: create.evidence_refs,
+            linked_record_ids: create.linked_record_ids,
+            confidence: create.confidence.clamp(0.0, 1.0),
+            status: create.status,
+            created_at: now,
+            updated_at: now,
+        };
+        self.write_action_gap_file(&gap)?;
+        Ok(gap)
+    }
+
+    pub fn review_action_gap(
+        &mut self,
+        id: &str,
+        request: ConstitutionReviewRequest,
+    ) -> Result<ActionGap> {
+        Self::validate_file_id(id)?;
+        let mut gap = self.read_action_gap_file(&self.action_gap_file_path(id))?;
+        gap.status = constitution_status_for_action(&request.action);
+        gap.updated_at = Utc::now();
+        self.write_action_gap_file(&gap)?;
+        self.append_trace_event(
+            "constitution-review",
+            TraceEventType::ActionGapReviewed,
+            json!({
+                "action_gap_id": gap.id,
+                "action": request.action,
+                "rationale": request.rationale,
+            }),
+        )?;
+        Ok(gap)
+    }
+
+    pub fn get_constitution_setup(&self) -> Result<ConstitutionSetup> {
+        if !self.setup_path.exists() {
+            return Ok(ConstitutionSetup::default());
+        }
+
+        let content = std::fs::read_to_string(&self.setup_path).with_context(|| {
+            format!(
+                "Failed to read constitution setup file: {}",
+                self.setup_path.display()
+            )
+        })?;
+        serde_json::from_str(&content).with_context(|| {
+            format!(
+                "Failed to parse constitution setup file: {}",
+                self.setup_path.display()
+            )
+        })
+    }
+
+    pub fn save_constitution_setup(
+        &mut self,
+        mut setup: ConstitutionSetup,
+    ) -> Result<ConstitutionSetup> {
+        setup.twin_name = clean_optional_setup_entry(setup.twin_name);
+        setup.twin_role = clean_optional_setup_entry(setup.twin_role);
+        setup.source_boundaries = clean_setup_entries(setup.source_boundaries);
+        setup.values = clean_setup_entries(setup.values);
+        setup.tastes = clean_setup_entries(setup.tastes);
+        setup.constraints = clean_setup_entries(setup.constraints);
+        setup.somatic_cues = clean_setup_entries(setup.somatic_cues);
+        setup.action_tendencies = clean_setup_entries(setup.action_tendencies);
+        setup.updated_at = Some(Utc::now());
+        self.write_pretty_json(&self.setup_path, &setup)?;
+
+        let event = self.append_trace_event(
+            "constitution-setup",
+            TraceEventType::ConstitutionSetupSaved,
+            json!({
+                "twin_name": setup.twin_name,
+                "twin_role": setup.twin_role,
+                "source_boundaries": setup.source_boundaries,
+                "values": setup.values,
+                "tastes": setup.tastes,
+                "constraints": setup.constraints,
+                "somatic_cues": setup.somatic_cues,
+                "action_tendencies": setup.action_tendencies,
+            }),
+        )?;
+        let evidence_ref = EvidenceRef {
+            trace_id: "constitution-setup".to_string(),
+            event_id: event.id,
+            session_id: "constitution-setup".to_string(),
+            tile_id: None,
+            model_id: None,
+            note: Some("Guided Twin setup".to_string()),
+            source_type: Some("setup".to_string()),
+            source_id: Some("constitution-setup".to_string()),
+            source_label: Some("Guided Twin setup".to_string()),
+            excerpt: None,
+            speaker_role: None,
+        };
+
+        self.seed_constitution_setup_items(&setup, evidence_ref)?;
+        Ok(setup)
+    }
+
+    pub fn run_constitution_inference(&mut self) -> Result<ConstitutionInferenceSummary> {
+        self.run_constitution_inference_with_notes(&[])
+    }
+
+    pub fn run_constitution_inference_with_notes(
+        &mut self,
+        notes: &[Note],
+    ) -> Result<ConstitutionInferenceSummary> {
+        self.ensure_record_cache()?;
+        let current_note_ids = notes
+            .iter()
+            .map(|note| note.id.clone())
+            .collect::<HashSet<_>>();
+        let pruned_stale_records = self.prune_stale_note_records(&current_note_ids)?;
+        let distilled_setup = distill_constitution_setup_from_notes(notes);
+        let updated_setup_entries = constitution_setup_entry_count(&distilled_setup);
+        let pruned_stale_constitution_items = self
+            .prune_stale_note_constitution_items(&current_note_ids)?
+            + self.prune_stale_setup_constitution_items(&distilled_setup)?;
+        if updated_setup_entries > 0 || self.setup_path.exists() {
+            self.write_auto_constitution_setup(distilled_setup.clone())?;
+        }
+        self.ensure_record_cache()?;
+        let records = self
+            .record_cache
+            .values()
+            .filter(|record| constitution_allows_record(record))
+            .cloned()
+            .collect::<Vec<_>>();
+        let traces = self.list_session_traces()?;
+        let scanned_behavior_events = traces
+            .iter()
+            .flat_map(|trace| trace.events.iter())
+            .filter(|event| behavior_event_for_constitution(&event.event_type))
+            .count();
+        let decisions = self.list_decision_episodes()?;
+        let existing_items = self.list_constitution_items()?;
+        let existing_gaps = self.list_action_gaps()?;
+        let mut item_keys = existing_items
+            .iter()
+            .map(|item| constitution_key(&item.dimension, &item.claim))
+            .collect::<HashSet<_>>();
+        let mut gap_keys = existing_gaps
+            .iter()
+            .map(|gap| action_gap_key(&gap.stated_value, &gap.revealed_behavior))
+            .collect::<HashSet<_>>();
+
+        let mut created_constitution_items = 0_usize;
+        let mut created_action_gaps = 0_usize;
+        let mut auto_active_items = 0_usize;
+        let mut review_candidate_items = 0_usize;
+        let mut skipped_domain_claims = 0_usize;
+        let mut extracted_research_findings = 0_usize;
+
+        for record in &records {
+            let dimension = infer_constitution_dimension(&record.content, &record.kind);
+            let claim = record.content.trim().to_string();
+            if claim.is_empty() {
+                continue;
+            }
+            let key = constitution_key(&dimension, &claim);
+            if item_keys.insert(key) {
+                let status = constitution_status_from_record(record);
+                if status == ConstitutionStatus::Active {
+                    auto_active_items += 1;
+                } else if status == ConstitutionStatus::Candidate {
+                    review_candidate_items += 1;
+                }
+                let source = if record.origin == RecordOrigin::Inferred {
+                    "behavior_inference"
+                } else {
+                    "constitution_inference"
+                };
+                self.create_constitution_item(ConstitutionItemCreate {
+                    claim,
+                    dimension,
+                    scope: vec!["general".to_string()],
+                    priority: record.confidence,
+                    confidence: record.confidence,
+                    status,
+                    evidence_refs: record.evidence_refs.clone(),
+                    tensions: Vec::new(),
+                    linked_record_ids: vec![record.id.clone()],
+                    source: Some(source.to_string()),
+                })?;
+                created_constitution_items += 1;
+            }
+
+            if let Some((stated_value, revealed_behavior)) = split_action_gap_claim(&record.content)
+            {
+                let key = action_gap_key(&stated_value, &revealed_behavior);
+                if gap_keys.insert(key) {
+                    self.create_action_gap(ActionGapCreate {
+                        stated_value,
+                        revealed_behavior,
+                        driver_hypothesis: Some(
+                            "Inferred from a contradiction-style user record".to_string(),
+                        ),
+                        somatic_taste_signal: None,
+                        decision_risk:
+                            "The user's endorsed intent may diverge from what they repeatedly do."
+                                .to_string(),
+                        evidence_refs: record.evidence_refs.clone(),
+                        linked_record_ids: vec![record.id.clone()],
+                        confidence: record.confidence,
+                        status: ConstitutionStatus::Candidate,
+                    })?;
+                    created_action_gaps += 1;
+                }
+            }
+        }
+
+        for decision in &decisions {
+            let Some(initial_leaning) = decision.initial_leaning.as_ref() else {
+                continue;
+            };
+            let Some(chosen_option) = decision.chosen_option.as_ref() else {
+                continue;
+            };
+            if initial_leaning
+                .trim()
+                .eq_ignore_ascii_case(chosen_option.trim())
+            {
+                continue;
+            }
+            let stated_value = format!("Initial leaning: {}", initial_leaning.trim());
+            let revealed_behavior = format!("Chosen option: {}", chosen_option.trim());
+            let key = action_gap_key(&stated_value, &revealed_behavior);
+            if gap_keys.insert(key) {
+                self.create_action_gap(ActionGapCreate {
+                    stated_value,
+                    revealed_behavior,
+                    driver_hypothesis: Some("Inferred from a decision where final action diverged from initial leaning.".to_string()),
+                    somatic_taste_signal: decision.primitive_assessment.somatic_signal.clone(),
+                    decision_risk: "Grafyn should check whether future similar decisions repeat this gap.".to_string(),
+                    evidence_refs: self.decision_evidence_refs(&decision.id)?,
+                    linked_record_ids: Vec::new(),
+                    confidence: 0.68,
+                    status: ConstitutionStatus::Candidate,
+                })?;
+                created_action_gaps += 1;
+            }
+        }
+
+        for note in notes {
+            if note_is_interview(note) {
+                match extract_interview_note_evidence(note) {
+                    InterviewExtraction::Unlabeled => {
+                        skipped_domain_claims += 1;
+                    }
+                    InterviewExtraction::Labeled {
+                        interviewer_turns,
+                        interviewee_turns,
+                    } => {
+                        for turn in interviewer_turns {
+                            if let Some((dimension, claim)) =
+                                constitution_claim_from_interviewer_turn(&turn.content)
+                            {
+                                let key = constitution_key(&dimension, &claim);
+                                if item_keys.insert(key) {
+                                    self.create_constitution_item(ConstitutionItemCreate {
+                                        claim,
+                                        dimension,
+                                        scope: vec!["interview".to_string()],
+                                        priority: 0.62,
+                                        confidence: 0.62,
+                                        status: ConstitutionStatus::Candidate,
+                                        evidence_refs: vec![note_evidence_ref(
+                                            note,
+                                            "interview-question",
+                                            "Interviewer question",
+                                            Some("user"),
+                                            &turn.content,
+                                        )],
+                                        tensions: Vec::new(),
+                                        linked_record_ids: Vec::new(),
+                                        source: Some("interview_behavior_inference".to_string()),
+                                    })?;
+                                    created_constitution_items += 1;
+                                    review_candidate_items += 1;
+                                }
+                            }
+                        }
+                        for turn in interviewee_turns {
+                            if !looks_like_research_finding(&turn.content) {
+                                skipped_domain_claims += 1;
+                                continue;
+                            }
+                            if self.create_interview_research_record(note, &turn.content)? {
+                                extracted_research_findings += 1;
+                            }
+                        }
+                    }
+                }
+                continue;
+            }
+
+            if let Some((dimension, claim)) = constitution_claim_from_note(note) {
+                let key = constitution_key(&dimension, &claim);
+                if item_keys.insert(key) {
+                    self.create_constitution_item(ConstitutionItemCreate {
+                        claim,
+                        dimension,
+                        scope: vec!["note".to_string()],
+                        priority: 0.58,
+                        confidence: 0.58,
+                        status: ConstitutionStatus::Candidate,
+                        evidence_refs: vec![note_evidence_ref(
+                            note,
+                            "note",
+                            "Vault note",
+                            Some("user"),
+                            &note.content,
+                        )],
+                        tensions: Vec::new(),
+                        linked_record_ids: Vec::new(),
+                        source: Some("note_inference".to_string()),
+                    })?;
+                    created_constitution_items += 1;
+                    review_candidate_items += 1;
+                }
+            } else {
+                skipped_domain_claims += 1;
+            }
+        }
+
+        let summary = ConstitutionInferenceSummary {
+            scanned_records: records.len(),
+            scanned_decisions: decisions.len(),
+            created_constitution_items,
+            created_action_gaps,
+            scanned_behavior_events,
+            scanned_notes: notes.len(),
+            scanned_interviews: notes.iter().filter(|note| note_is_interview(note)).count(),
+            auto_active_items,
+            review_candidate_items,
+            skipped_domain_claims,
+            extracted_research_findings,
+            pruned_stale_constitution_items,
+            pruned_stale_records,
+            updated_setup_entries,
+            generated_at: Utc::now(),
+        };
+        self.append_trace_event(
+            "constitution-inference",
+            TraceEventType::ConstitutionInferenceRun,
+            serde_json::to_value(&summary)?,
+        )?;
+        Ok(summary)
+    }
+
+    fn create_interview_research_record(&mut self, note: &Note, content: &str) -> Result<bool> {
+        self.ensure_record_cache()?;
+        let finding = format!("Interview finding: {}", excerpt(content.trim()));
+        let existing = self.record_cache.values().any(|record| {
+            record.kind == UserRecordKind::Fact
+                && record.content == finding
+                && record.metadata.get("source_type").and_then(Value::as_str)
+                    == Some("interview_answer")
+        });
+        if existing {
+            return Ok(false);
+        }
+
+        self.create_user_record(UserRecordCreate {
+            kind: UserRecordKind::Fact,
+            content: finding,
+            evidence_refs: vec![note_evidence_ref(
+                note,
+                "interview-answer",
+                "Interviewee answer",
+                Some("interviewee"),
+                content,
+            )],
+            confidence: 0.66,
+            origin: RecordOrigin::Inferred,
+            promotion_state: Some(PromotionState::Candidate),
+            valid_from: None,
+            valid_until: None,
+            links: Vec::new(),
+            metadata: HashMap::from([
+                ("source_type".to_string(), json!("interview_answer")),
+                ("source_note_id".to_string(), json!(note.id.clone())),
+            ]),
+        })?;
+        Ok(true)
+    }
+
+    fn write_auto_constitution_setup(&self, mut setup: ConstitutionSetup) -> Result<()> {
+        if let Ok(existing) = self.get_constitution_setup() {
+            setup.twin_name = existing.twin_name;
+            setup.twin_role = existing.twin_role;
+            setup.source_boundaries = existing.source_boundaries;
+        }
+        setup.twin_name = clean_optional_setup_entry(setup.twin_name);
+        setup.twin_role = clean_optional_setup_entry(setup.twin_role);
+        setup.source_boundaries = clean_setup_entries(setup.source_boundaries);
+        setup.values = clean_setup_entries(setup.values);
+        setup.tastes = clean_setup_entries(setup.tastes);
+        setup.constraints = clean_setup_entries(setup.constraints);
+        setup.somatic_cues = clean_setup_entries(setup.somatic_cues);
+        setup.action_tendencies = clean_setup_entries(setup.action_tendencies);
+        setup.updated_at = Some(Utc::now());
+        self.write_pretty_json(&self.setup_path, &setup)
+    }
+
+    fn prune_stale_note_records(&mut self, current_note_ids: &HashSet<String>) -> Result<usize> {
+        self.ensure_record_cache()?;
+        let stale_ids = self
+            .record_cache
+            .values()
+            .filter(|record| record_is_vault_derived(record))
+            .filter(|record| {
+                record
+                    .metadata
+                    .get("source_note_id")
+                    .and_then(Value::as_str)
+                    .is_some_and(|source_note_id| !current_note_ids.contains(source_note_id))
+            })
+            .map(|record| record.id.clone())
+            .collect::<Vec<_>>();
+
+        for id in &stale_ids {
+            self.record_cache.remove(id);
+            let path = self.records_path.join(format!("{}.json", id));
+            if path.exists() {
+                std::fs::remove_file(&path).with_context(|| {
+                    format!("Failed to remove stale Twin record: {}", path.display())
+                })?;
+            }
+        }
+
+        Ok(stale_ids.len())
+    }
+
+    fn prune_stale_note_constitution_items(
+        &self,
+        current_note_ids: &HashSet<String>,
+    ) -> Result<usize> {
+        let stale_items = self
+            .list_constitution_items()?
+            .into_iter()
+            .filter(|item| constitution_item_is_vault_derived(item))
+            .filter(|item| {
+                item.evidence_refs
+                    .iter()
+                    .filter_map(|evidence| evidence.source_id.as_deref())
+                    .any(|source_id| !current_note_ids.contains(source_id))
+            })
+            .collect::<Vec<_>>();
+
+        for item in &stale_items {
+            let path = self.constitution_path.join(format!("{}.json", item.id));
+            if path.exists() {
+                std::fs::remove_file(&path).with_context(|| {
+                    format!(
+                        "Failed to remove stale Constitution item: {}",
+                        path.display()
+                    )
+                })?;
+            }
+        }
+
+        Ok(stale_items.len())
+    }
+
+    fn prune_stale_setup_constitution_items(&self, setup: &ConstitutionSetup) -> Result<usize> {
+        let setup_claims = constitution_setup_claims(setup);
+        let stale_items = self
+            .list_constitution_items()?
+            .into_iter()
+            .filter(|item| item.source.as_deref() == Some("guided_setup"))
+            .filter(|item| !setup_claims.contains(item.claim.trim()))
+            .collect::<Vec<_>>();
+
+        for item in &stale_items {
+            let path = self.constitution_path.join(format!("{}.json", item.id));
+            if path.exists() {
+                std::fs::remove_file(&path).with_context(|| {
+                    format!(
+                        "Failed to remove stale setup Constitution item: {}",
+                        path.display()
+                    )
+                })?;
+            }
+        }
+
+        Ok(stale_items.len())
+    }
+
+    pub fn select_constitution_context(
+        &self,
+        query: &str,
+    ) -> Result<(Vec<ConstitutionItem>, Vec<ActionGap>)> {
+        let query_terms = lexical_terms(query);
+        let mut items = self
+            .list_constitution_items()?
+            .into_iter()
+            .filter(|item| constitution_context_allowed(&item.status))
+            .map(|item| (constitution_item_relevance(&item, &query_terms), item))
+            .filter(|(score, item)| *score > 0 || item.status == ConstitutionStatus::Active)
+            .collect::<Vec<_>>();
+        items.sort_by(|a, b| {
+            b.0.cmp(&a.0)
+                .then_with(|| {
+                    b.1.priority
+                        .partial_cmp(&a.1.priority)
+                        .unwrap_or(std::cmp::Ordering::Equal)
+                })
+                .then_with(|| b.1.updated_at.cmp(&a.1.updated_at))
+        });
+
+        let mut gaps = self
+            .list_action_gaps()?
+            .into_iter()
+            .filter(|gap| constitution_context_allowed(&gap.status))
+            .map(|gap| (action_gap_relevance(&gap, &query_terms), gap))
+            .filter(|(score, gap)| *score > 0 || gap.status == ConstitutionStatus::Active)
+            .collect::<Vec<_>>();
+        gaps.sort_by(|a, b| {
+            b.0.cmp(&a.0)
+                .then_with(|| {
+                    b.1.confidence
+                        .partial_cmp(&a.1.confidence)
+                        .unwrap_or(std::cmp::Ordering::Equal)
+                })
+                .then_with(|| b.1.updated_at.cmp(&a.1.updated_at))
+        });
+
+        Ok((
+            items.into_iter().take(8).map(|(_, item)| item).collect(),
+            gaps.into_iter().take(4).map(|(_, gap)| gap).collect(),
+        ))
+    }
+
+    pub(super) fn constitution_file_path(&self, item_id: &str) -> PathBuf {
+        self.constitution_path.join(format!("{}.json", item_id))
+    }
+
+    pub(super) fn action_gap_file_path(&self, gap_id: &str) -> PathBuf {
+        self.action_gaps_path.join(format!("{}.json", gap_id))
+    }
+
+    pub(super) fn read_constitution_file(&self, path: &Path) -> Result<ConstitutionItem> {
+        let content = std::fs::read_to_string(path)
+            .with_context(|| format!("Failed to read constitution file: {}", path.display()))?;
+        serde_json::from_str(&content)
+            .with_context(|| format!("Failed to parse constitution file: {}", path.display()))
+    }
+
+    pub(super) fn read_action_gap_file(&self, path: &Path) -> Result<ActionGap> {
+        let content = std::fs::read_to_string(path)
+            .with_context(|| format!("Failed to read action gap file: {}", path.display()))?;
+        serde_json::from_str(&content)
+            .with_context(|| format!("Failed to parse action gap file: {}", path.display()))
+    }
+
+    fn write_constitution_file(&self, item: &ConstitutionItem) -> Result<()> {
+        let path = self.constitution_file_path(&item.id);
+        self.write_pretty_json(&path, item)
+    }
+
+    fn write_action_gap_file(&self, gap: &ActionGap) -> Result<()> {
+        let path = self.action_gap_file_path(&gap.id);
+        self.write_pretty_json(&path, gap)
+    }
+
+    fn seed_constitution_setup_items(
+        &self,
+        setup: &ConstitutionSetup,
+        evidence_ref: EvidenceRef,
+    ) -> Result<()> {
+        let existing_keys = self
+            .list_constitution_items()?
+            .into_iter()
+            .map(|item| constitution_key(&item.dimension, &item.claim))
+            .collect::<HashSet<_>>();
+        let mut created_keys = existing_keys;
+
+        let groups: &[(&str, &[String])] = &[
+            ("values", &setup.values),
+            ("taste", &setup.tastes),
+            ("constraints", &setup.constraints),
+            ("somatic", &setup.somatic_cues),
+            ("action_tendency", &setup.action_tendencies),
+        ];
+
+        for (dimension, entries) in groups {
+            for entry in entries.iter().filter(|entry| !entry.trim().is_empty()) {
+                let claim = entry.trim().to_string();
+                let key = constitution_key(dimension, &claim);
+                if !created_keys.insert(key) {
+                    continue;
+                }
+                self.create_constitution_item(ConstitutionItemCreate {
+                    claim,
+                    dimension: (*dimension).to_string(),
+                    scope: vec!["setup".to_string()],
+                    priority: 0.9,
+                    confidence: 0.9,
+                    status: ConstitutionStatus::Active,
+                    evidence_refs: vec![evidence_ref.clone()],
+                    tensions: Vec::new(),
+                    linked_record_ids: Vec::new(),
+                    source: Some("guided_setup".to_string()),
+                })?;
+            }
+        }
+
+        Ok(())
+    }
+
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::models::note::{Note, NoteStatus};
+    use crate::models::twin::{
+        default_record_confidence, PromotionState, RecordLink, RecordLinkType, UserRecordKind,
+    };
+    use tempfile::tempdir;
+
+    use crate::models::twin::ConstitutionStatus;
+    fn test_note(id: &str, title: &str, content: &str, source_type: Option<&str>) -> Note {
+        let now = Utc::now();
+        let mut properties = HashMap::new();
+        if let Some(source_type) = source_type {
+            properties.insert(
+                "source_type".to_string(),
+                Value::String(source_type.to_string()),
+            );
+        }
+        Note {
+            id: id.to_string(),
+            title: title.to_string(),
+            content: content.to_string(),
+            relative_path: format!("{}.md", id),
+            aliases: Vec::new(),
+            status: NoteStatus::Evidence,
+            tags: Vec::new(),
+            created_at: now,
+            updated_at: now,
+            schema_version: crate::models::note::CURRENT_NOTE_SCHEMA_VERSION,
+            migration_source: None,
+            optimizer_managed: false,
+            wikilinks: Vec::new(),
+            parsed_links: Vec::new(),
+            properties,
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn constitution_inference_uses_repeated_behavior_as_primary_evidence() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        for index in 0..3 {
+            store
+                .append_trace_event(
+                    "session-1",
+                    TraceEventType::PromptSubmitted,
+                    serde_json::json!({
+                        "tile_id": format!("tile-{}", index),
+                        "prompt": "Please implement this with exact files, commands, and tests.",
+                        "models": ["openai/gpt-4o"],
+                    }),
+                )
+                .expect("trace event should append");
+        }
+
+        store
+            .run_twin_inference()
+            .expect("record inference should run");
+        let summary = store
+            .run_constitution_inference_with_notes(&[])
+            .expect("constitution inference should run");
+        let items = store
+            .list_constitution_items()
+            .expect("constitution should list");
+        let item = items
+            .iter()
+            .find(|item| item.claim.contains("concrete implementation details"))
+            .expect("behavior-derived constitution item should exist");
+
+        assert_eq!(summary.scanned_behavior_events, 3);
+        assert_eq!(summary.auto_active_items, 1);
+        assert_eq!(item.status, ConstitutionStatus::Active);
+        assert_eq!(item.source.as_deref(), Some("behavior_inference"));
+        assert!(item
+            .evidence_refs
+            .iter()
+            .all(|evidence| evidence.source_type.as_deref() == Some("behavior")));
+    }
+
+    #[test]
+    fn interviewee_answers_become_research_findings_not_personal_constitution() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+        let notes = vec![test_note(
+            "interview-1",
+            "Interview: onboarding",
+            "### Message 1: User\n\nHow do you decide whether an AI workflow is useful?\n\n### Message 2: Interviewee\n\nI need to see a working demo before I trust the system.\n\n### Message 3: User\n\nCan you give a concrete example and compare it with your current workflow?",
+            Some("interview"),
+        )];
+
+        let summary = store
+            .run_constitution_inference_with_notes(&notes)
+            .expect("constitution inference should run");
+        let items = store
+            .list_constitution_items()
+            .expect("constitution should list");
+        let records = store.list_user_records().expect("records should list");
+
+        assert_eq!(summary.scanned_interviews, 1);
+        assert_eq!(summary.extracted_research_findings, 1);
+        assert!(items
+            .iter()
+            .any(|item| item.claim.contains("concrete examples")));
+        assert!(!items
+            .iter()
+            .any(|item| item.claim.contains("working demo before I trust")));
+        assert!(records.iter().any(|record| {
+            record.kind == UserRecordKind::Fact
+                && record.content.contains("working demo before I trust")
+                && record.metadata.get("source_type").and_then(Value::as_str)
+                    == Some("interview_answer")
+        }));
+    }
+
+    #[test]
+    fn unlabeled_interview_notes_import_but_do_not_extract() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+        let notes = vec![test_note(
+            "interview-2",
+            "Unlabeled interview",
+            "How do you decide whether an AI workflow is useful?\nI need a working demo.",
+            Some("interview"),
+        )];
+
+        let summary = store
+            .run_constitution_inference_with_notes(&notes)
+            .expect("constitution inference should run");
+
+        assert_eq!(summary.scanned_interviews, 1);
+        assert_eq!(summary.extracted_research_findings, 0);
+        assert_eq!(summary.skipped_domain_claims, 1);
+        assert!(store
+            .list_constitution_items()
+            .expect("constitution should list")
+            .is_empty());
+    }
+
+    #[test]
+    fn constitution_inference_prunes_stale_vault_derived_items_and_records() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        store
+            .create_constitution_item(ConstitutionItemCreate {
+                claim: "Old note-backed claim".to_string(),
+                dimension: "reasoning".to_string(),
+                scope: vec!["note".to_string()],
+                priority: 0.58,
+                confidence: 0.58,
+                status: ConstitutionStatus::Candidate,
+                evidence_refs: vec![EvidenceRef {
+                    trace_id: "note-old-note".to_string(),
+                    event_id: "old-note".to_string(),
+                    session_id: "vault-note".to_string(),
+                    tile_id: None,
+                    model_id: None,
+                    note: Some("Old note".to_string()),
+                    source_type: Some("note".to_string()),
+                    source_id: Some("old-note".to_string()),
+                    source_label: Some("Vault note".to_string()),
+                    excerpt: Some("old evidence".to_string()),
+                    speaker_role: Some("user".to_string()),
+                }],
+                tensions: Vec::new(),
+                linked_record_ids: Vec::new(),
+                source: Some("note_inference".to_string()),
+            })
+            .expect("old constitution item should be created");
+        store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::Fact,
+                content: "Interview finding: old vault finding".to_string(),
+                origin: RecordOrigin::Inferred,
+                evidence_refs: Vec::new(),
+                confidence: 0.66,
+                promotion_state: Some(PromotionState::Candidate),
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::from([
+                    ("source_type".to_string(), json!("interview_answer")),
+                    ("source_note_id".to_string(), json!("old-note")),
+                ]),
+            })
+            .expect("old record should be created");
+        store
+            .create_constitution_item(ConstitutionItemCreate {
+                claim: "Old guided setup claim".to_string(),
+                dimension: "values".to_string(),
+                scope: vec!["setup".to_string()],
+                priority: 0.9,
+                confidence: 0.9,
+                status: ConstitutionStatus::Active,
+                evidence_refs: Vec::new(),
+                tensions: Vec::new(),
+                linked_record_ids: Vec::new(),
+                source: Some("guided_setup".to_string()),
+            })
+            .expect("old setup constitution item should be created");
+
+        let current_notes = vec![test_note(
+            "current-interview",
+            "Current interview",
+            "### Message 1: User\n\nCan you give a concrete example of how you make tradeoffs?\n\n### Message 2: Interviewee\n\nI compare impact and risk before deciding.",
+            Some("interview"),
+        )];
+        let summary = store
+            .run_constitution_inference_with_notes(&current_notes)
+            .expect("constitution inference should run");
+
+        assert_eq!(summary.pruned_stale_constitution_items, 2);
+        assert_eq!(summary.pruned_stale_records, 1);
+        assert!(store
+            .list_constitution_items()
+            .expect("constitution should list")
+            .iter()
+            .all(|item| !item.claim.contains("Old note-backed claim")
+                && !item.claim.contains("Old guided setup claim")));
+        assert!(store
+            .list_user_records()
+            .expect("records should list")
+            .iter()
+            .all(|record| !record.content.contains("old vault finding")));
+    }
+
+    #[test]
+    fn constitution_inference_rewrites_setup_from_current_interview_questions() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+        let notes = vec![test_note(
+            "interview-setup",
+            "Interview: strategy",
+            "### Message 1: User\n\nWhat are some personal values or cultural values that drive your decisions?\n\n### Message 2: Interviewee\n\nI want work to make something better and different.\n\n### Message 3: User\n\nCan you walk us through a concrete example and how you balance innovation and stability?",
+            Some("interview"),
+        )];
+
+        let summary = store
+            .run_constitution_inference_with_notes(&notes)
+            .expect("constitution inference should run");
+        let setup = store
+            .get_constitution_setup()
+            .expect("setup should load after inference");
+
+        assert!(summary.updated_setup_entries >= 4);
+        assert!(setup
+            .values
+            .iter()
+            .any(|entry| entry.contains("values and cultural assumptions")));
+        assert!(setup
+            .tastes
+            .iter()
+            .any(|entry| entry.contains("concrete walkthroughs")));
+        assert!(setup
+            .constraints
+            .iter()
+            .any(|entry| entry.contains("interviewee answers as research evidence")));
+        assert!(setup
+            .action_tendencies
+            .iter()
+            .any(|entry| entry.contains("follow-up questions")));
+    }
+
+    #[test]
+    fn constitution_setup_accepts_legacy_json_without_identity() {
+        let setup: ConstitutionSetup = serde_json::from_str(
+            r#"{
+                "values": ["evidence-backed work"],
+                "tastes": ["clean UX"],
+                "constraints": [],
+                "somatic_cues": [],
+                "action_tendencies": []
+            }"#,
+        )
+        .expect("legacy setup should parse");
+
+        assert_eq!(setup.twin_name, None);
+        assert_eq!(setup.twin_role, None);
+        assert!(setup.source_boundaries.is_empty());
+        assert_eq!(setup.values, vec!["evidence-backed work"]);
+    }
+
+    #[test]
+    fn save_constitution_setup_trims_identity_fields() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        let saved = store
+            .save_constitution_setup(ConstitutionSetup {
+                twin_name: Some("  Alex Chen  ".to_string()),
+                twin_role: Some("  founder deciding from product evidence  ".to_string()),
+                source_boundaries: vec![
+                    "  Use reviewed notes only.  ".to_string(),
+                    "".to_string(),
+                    " Uploaded interviews define domain context. ".to_string(),
+                ],
+                values: vec![" evidence-backed work ".to_string()],
+                ..ConstitutionSetup::default()
+            })
+            .expect("setup should save");
+
+        assert_eq!(saved.twin_name.as_deref(), Some("Alex Chen"));
+        assert_eq!(
+            saved.twin_role.as_deref(),
+            Some("founder deciding from product evidence")
+        );
+        assert_eq!(
+            saved.source_boundaries,
+            vec![
+                "Use reviewed notes only.".to_string(),
+                "Uploaded interviews define domain context.".to_string()
+            ]
+        );
+        assert_eq!(saved.values, vec!["evidence-backed work"]);
+    }
+
+    #[test]
+    fn constitution_inference_preserves_configured_identity() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+        store
+            .save_constitution_setup(ConstitutionSetup {
+                twin_name: Some("Alex Chen".to_string()),
+                twin_role: Some("founder deciding from product evidence".to_string()),
+                source_boundaries: vec!["Use reviewed notes only.".to_string()],
+                values: vec!["evidence-backed work".to_string()],
+                ..ConstitutionSetup::default()
+            })
+            .expect("identity setup should save");
+
+        let notes = vec![test_note(
+            "interview-setup",
+            "Interview: strategy",
+            "### Message 1: User\n\nCan you walk us through a concrete example and how you balance innovation and stability?",
+            Some("interview"),
+        )];
+        store
+            .run_constitution_inference_with_notes(&notes)
+            .expect("constitution inference should run");
+        let setup = store
+            .get_constitution_setup()
+            .expect("setup should load after inference");
+
+        assert_eq!(setup.twin_name.as_deref(), Some("Alex Chen"));
+        assert_eq!(
+            setup.twin_role.as_deref(),
+            Some("founder deciding from product evidence")
+        );
+        assert_eq!(
+            setup.source_boundaries,
+            vec!["Use reviewed notes only.".to_string()]
+        );
+    }
+
+}
diff --git a/frontend/src-tauri/src/services/twin/mod.rs b/frontend/src-tauri/src/services/twin/mod.rs
index e092891..65e2d7e 100644
--- a/frontend/src-tauri/src/services/twin/mod.rs
+++ b/frontend/src-tauri/src/services/twin/mod.rs
@@ -31,8 +31,10 @@ use walkdir::WalkDir;
 mod shared;
 mod traces;
 mod records;
+mod constitution;
 
 use shared::*;
+use constitution::normalize_key_text;
 
 const AUTO_PROMOTE_CONFIDENCE: f32 = 0.75;
 const AUTO_PROMOTE_SUPPORT_COUNT: usize = 3;
@@ -47,590 +49,6 @@ enum ExportSplit {
     Holdout,
 }
 
-fn clean_setup_entries(entries: Vec<String>) -> Vec<String> {
-    let mut seen = HashSet::new();
-    entries
-        .into_iter()
-        .map(|entry| entry.trim().to_string())
-        .filter(|entry| !entry.is_empty())
-        .filter(|entry| seen.insert(entry.to_lowercase()))
-        .collect()
-}
-
-fn clean_optional_setup_entry(entry: Option<String>) -> Option<String> {
-    entry
-        .map(|value| value.trim().to_string())
-        .filter(|value| !value.is_empty())
-}
-
-fn constitution_key(dimension: &str, claim: &str) -> String {
-    format!(
-        "{}::{}",
-        dimension.trim().to_lowercase(),
-        normalize_key_text(claim)
-    )
-}
-
-fn action_gap_key(stated_value: &str, revealed_behavior: &str) -> String {
-    format!(
-        "{}::{}",
-        normalize_key_text(stated_value),
-        normalize_key_text(revealed_behavior)
-    )
-}
-
-fn normalize_key_text(text: &str) -> String {
-    text.split_whitespace()
-        .collect::<Vec<_>>()
-        .join(" ")
-        .to_lowercase()
-}
-
-fn constitution_allows_record(record: &UserRecord) -> bool {
-    !matches!(
-        record.promotion_state,
-        PromotionState::Rejected | PromotionState::Private | PromotionState::NoTrain
-    ) && record.kind != UserRecordKind::Fact
-}
-
-fn behavior_event_for_constitution(event_type: &TraceEventType) -> bool {
-    matches!(
-        event_type,
-        TraceEventType::PromptSubmitted
-            | TraceEventType::FeedbackRecorded
-            | TraceEventType::RankingRecorded
-            | TraceEventType::InsightCaptured
-            | TraceEventType::DebateStarted
-            | TraceEventType::DebateContinued
-            | TraceEventType::NoteExported
-            | TraceEventType::NoteCanonicalPromoted
-            | TraceEventType::DecisionEpisodeCreated
-            | TraceEventType::OutcomeFollowUpRecorded
-    )
-}
-
-fn constitution_status_from_record(record: &UserRecord) -> ConstitutionStatus {
-    let support_count = record.evidence_refs.len();
-    match record.promotion_state {
-        PromotionState::AutoPromoted | PromotionState::Endorsed
-            if support_count >= AUTO_PROMOTE_SUPPORT_COUNT =>
-        {
-            ConstitutionStatus::Active
-        }
-        _ => ConstitutionStatus::Candidate,
-    }
-}
-
-fn constitution_context_allowed(status: &ConstitutionStatus) -> bool {
-    matches!(
-        status,
-        ConstitutionStatus::Active | ConstitutionStatus::Candidate | ConstitutionStatus::Softened
-    )
-}
-
-fn constitution_status_for_action(action: &MemoryDigestAction) -> ConstitutionStatus {
-    match action {
-        MemoryDigestAction::Keep => ConstitutionStatus::Active,
-        MemoryDigestAction::Soften => ConstitutionStatus::Softened,
-        MemoryDigestAction::NotMe => ConstitutionStatus::NotMe,
-        MemoryDigestAction::Private => ConstitutionStatus::Private,
-        MemoryDigestAction::NoTrain => ConstitutionStatus::NoTrain,
-        MemoryDigestAction::Reject => ConstitutionStatus::Rejected,
-    }
-}
-
-fn constitution_status_sort_key(status: &ConstitutionStatus) -> u8 {
-    match status {
-        ConstitutionStatus::Active => 0,
-        ConstitutionStatus::Candidate => 1,
-        ConstitutionStatus::Softened => 2,
-        ConstitutionStatus::NotMe => 3,
-        ConstitutionStatus::Private => 4,
-        ConstitutionStatus::NoTrain => 5,
-        ConstitutionStatus::Rejected => 6,
-    }
-}
-
-fn infer_constitution_dimension(content: &str, kind: &UserRecordKind) -> String {
-    let lower = content.to_lowercase();
-    if text_contains_any(&lower, &["taste", "aesthetic", "style", "design", "feel"]) {
-        "taste".to_string()
-    } else if text_contains_any(
-        &lower,
-        &["constraint", "deadline", "budget", "time", "cost"],
-    ) {
-        "constraints".to_string()
-    } else if text_contains_any(&lower, &["somatic", "gut", "body", "energy", "fatigue"]) {
-        "somatic".to_string()
-    } else if text_contains_any(&lower, &["value", "principle", "mission", "care about"]) {
-        "values".to_string()
-    } else {
-        match kind {
-            UserRecordKind::Preference => "preferences".to_string(),
-            UserRecordKind::ReasoningPattern => "reasoning".to_string(),
-            UserRecordKind::Fact => "facts".to_string(),
-        }
-    }
-}
-
-fn note_is_interview(note: &Note) -> bool {
-    note.properties
-        .get("source_type")
-        .or_else(|| note.properties.get("source"))
-        .and_then(Value::as_str)
-        .is_some_and(|value| value.eq_ignore_ascii_case("interview"))
-        || note
-            .tags
-            .iter()
-            .any(|tag| tag.eq_ignore_ascii_case("interview"))
-}
-
-#[derive(Debug, Clone)]
-struct InterviewTurn {
-    role: String,
-    content: String,
-}
-
-enum InterviewExtraction {
-    Unlabeled,
-    Labeled {
-        interviewer_turns: Vec<InterviewTurn>,
-        interviewee_turns: Vec<InterviewTurn>,
-    },
-}
-
-fn extract_interview_note_evidence(note: &Note) -> InterviewExtraction {
-    let turns = extract_markdown_interview_turns(&note.content)
-        .or_else(|| extract_colon_labeled_interview_turns(&note.content));
-    let Some(turns) = turns else {
-        return InterviewExtraction::Unlabeled;
-    };
-    let interviewer_turns = turns
-        .iter()
-        .filter(|turn| turn.role == "user")
-        .cloned()
-        .collect::<Vec<_>>();
-    let interviewee_turns = turns
-        .into_iter()
-        .filter(|turn| turn.role == "interviewee")
-        .collect::<Vec<_>>();
-    if interviewer_turns.is_empty() || interviewee_turns.is_empty() {
-        return InterviewExtraction::Unlabeled;
-    }
-    InterviewExtraction::Labeled {
-        interviewer_turns,
-        interviewee_turns,
-    }
-}
-
-fn extract_markdown_interview_turns(content: &str) -> Option<Vec<InterviewTurn>> {
-    let mut turns = Vec::new();
-    let mut current_role: Option<String> = None;
-    let mut current_content = String::new();
-    for line in content.lines() {
-        let trimmed = line.trim();
-        if let Some(role) = markdown_message_role(trimmed) {
-            flush_interview_turn(&mut turns, &mut current_role, &mut current_content);
-            current_role = Some(role);
-            continue;
-        }
-        if current_role.is_some() {
-            current_content.push_str(line);
-            current_content.push('\n');
-        }
-    }
-    flush_interview_turn(&mut turns, &mut current_role, &mut current_content);
-    if turns.len() >= 2 {
-        Some(turns)
-    } else {
-        None
-    }
-}
-
-fn markdown_message_role(line: &str) -> Option<String> {
-    let lower = line.to_lowercase();
-    if !(lower.starts_with("### message") || lower.starts_with("## message")) {
-        return None;
-    }
-    if lower.contains("interviewee") || lower.contains("participant") {
-        Some("interviewee".to_string())
-    } else if lower.contains("user")
-        || lower.contains("interviewer")
-        || lower.contains("researcher")
-    {
-        Some("user".to_string())
-    } else {
-        None
-    }
-}
-
-fn extract_colon_labeled_interview_turns(content: &str) -> Option<Vec<InterviewTurn>> {
-    let mut turns = Vec::new();
-    for line in content.lines() {
-        let Some((speaker, body)) = line.split_once(':') else {
-            continue;
-        };
-        let speaker = speaker.trim().to_lowercase();
-        let role = match speaker.as_str() {
-            "interviewer" | "researcher" | "moderator" | "facilitator" | "me" | "user" => "user",
-            "interviewee" | "participant" | "respondent" | "customer" | "student" | "teacher" => {
-                "interviewee"
-            }
-            _ => continue,
-        };
-        let content = body.trim();
-        if !content.is_empty() {
-            turns.push(InterviewTurn {
-                role: role.to_string(),
-                content: content.to_string(),
-            });
-        }
-    }
-    if turns.len() >= 2 {
-        Some(turns)
-    } else {
-        None
-    }
-}
-
-fn flush_interview_turn(
-    turns: &mut Vec<InterviewTurn>,
-    current_role: &mut Option<String>,
-    current_content: &mut String,
-) {
-    let Some(role) = current_role.take() else {
-        return;
-    };
-    let content = current_content.trim().to_string();
-    current_content.clear();
-    if content.is_empty() {
-        return;
-    }
-    turns.push(InterviewTurn { role, content });
-}
-
-fn constitution_claim_from_interviewer_turn(content: &str) -> Option<(String, String)> {
-    let lower = content.to_lowercase();
-    if text_contains_any(
-        &lower,
-        &[
-            "concrete example",
-            "compare",
-            "why",
-            "how do you",
-            "what makes",
-            "walk me through",
-        ],
-    ) {
-        return Some((
-            "reasoning".to_string(),
-            "Uses interview questions to probe for concrete examples and comparisons before treating claims as useful.".to_string(),
-        ));
-    }
-    None
-}
-
-fn looks_like_research_finding(content: &str) -> bool {
-    content.split_whitespace().count() >= 8
-        && text_contains_any(
-            content,
-            &[
-                "need", "want", "trust", "frustrat", "prefer", "hard", "easy", "useful", "demo",
-                "workflow",
-            ],
-        )
-}
-
-fn constitution_claim_from_note(note: &Note) -> Option<(String, String)> {
-    if note.is_topic_hub() {
-        return None;
-    }
-    let content = note.content.trim();
-    if content.len() < 24 {
-        return None;
-    }
-    let lower = content.to_lowercase();
-    if !text_contains_any(
-        &lower,
-        &[
-            "i prefer",
-            "i need",
-            "i value",
-            "my reasoning",
-            "works for me",
-            "not me",
-            "i reject",
-            "i decide",
-        ],
-    ) {
-        return None;
-    }
-    if text_contains_any(&lower, &["prefer"]) {
-        Some((
-            "preferences".to_string(),
-            format!("Note-backed preference: {}", excerpt(content)),
-        ))
-    } else {
-        Some((
-            "reasoning".to_string(),
-            format!("Note-backed reasoning pattern: {}", excerpt(content)),
-        ))
-    }
-}
-
-fn note_evidence_ref(
-    note: &Note,
-    source_type: &str,
-    source_label: &str,
-    speaker_role: Option<&str>,
-    content: &str,
-) -> EvidenceRef {
-    EvidenceRef {
-        trace_id: format!("note-{}", note.id),
-        event_id: note.id.clone(),
-        session_id: "vault-note".to_string(),
-        tile_id: None,
-        model_id: None,
-        note: Some(note.title.clone()),
-        source_type: Some(source_type.to_string()),
-        source_id: Some(note.id.clone()),
-        source_label: Some(source_label.to_string()),
-        excerpt: Some(excerpt(content.trim())),
-        speaker_role: speaker_role.map(ToOwned::to_owned),
-    }
-}
-
-fn distill_constitution_setup_from_notes(notes: &[Note]) -> ConstitutionSetup {
-    let mut setup = ConstitutionSetup::default();
-    let mut saw_interview_question = false;
-    let mut saw_values_question = false;
-    let mut saw_tradeoff_question = false;
-    let mut saw_risk_question = false;
-    let mut saw_concrete_question = false;
-    let mut saw_followup_question = false;
-    let mut saw_user_note_preference = false;
-    let mut interviewer_question_count = 0_usize;
-
-    for note in notes {
-        if note.is_topic_hub() {
-            continue;
-        }
-
-        if note_is_interview(note) {
-            if let InterviewExtraction::Labeled {
-                interviewer_turns, ..
-            } = extract_interview_note_evidence(note)
-            {
-                for turn in interviewer_turns {
-                    let lower = turn.content.to_lowercase();
-                    if turn.content.split_whitespace().count() < 5 {
-                        continue;
-                    }
-                    saw_interview_question = true;
-                    interviewer_question_count += 1;
-                    if text_contains_any(&lower, &["value", "cultural", "drives your decision"]) {
-                        saw_values_question = true;
-                    }
-                    if text_contains_any(&lower, &["trade off", "trade-off", "balance"]) {
-                        saw_tradeoff_question = true;
-                    }
-                    if text_contains_any(&lower, &["risk", "comfortable taking", "actively avoid"])
-                    {
-                        saw_risk_question = true;
-                    }
-                    if text_contains_any(
-                        &lower,
-                        &[
-                            "example",
-                            "walk us through",
-                            "walk through",
-                            "concrete",
-                            "top two",
-                        ],
-                    ) {
-                        saw_concrete_question = true;
-                    }
-                    if text_contains_any(
-                        &lower,
-                        &["following up", "if i understand", "drill", "how would"],
-                    ) {
-                        saw_followup_question = true;
-                    }
-                }
-            }
-            continue;
-        }
-
-        if let Some((dimension, claim)) = constitution_claim_from_note(note) {
-            saw_user_note_preference = true;
-            match dimension.as_str() {
-                "preferences" => push_unique(&mut setup.tastes, claim),
-                "constraints" => push_unique(&mut setup.constraints, claim),
-                "action_tendency" => push_unique(&mut setup.action_tendencies, claim),
-                _ => push_unique(&mut setup.values, claim),
-            }
-        }
-    }
-
-    if saw_interview_question {
-        push_unique(
-            &mut setup.constraints,
-            "Keeps interviewee answers as research evidence rather than treating them as the user's own Constitution.".to_string(),
-        );
-        push_unique(
-            &mut setup.constraints,
-            "Requires speaker-labelled evidence before extracting Constitution or research findings.".to_string(),
-        );
-    }
-    if saw_values_question {
-        push_unique(
-            &mut setup.values,
-            "Probes for the values and cultural assumptions behind decisions, not only the visible decision outcome.".to_string(),
-        );
-    }
-    if saw_tradeoff_question {
-        push_unique(
-            &mut setup.values,
-            "Treats important choices as tradeoffs between innovation, stability, impact, and institutional responsibility.".to_string(),
-        );
-    }
-    if saw_risk_question {
-        push_unique(
-            &mut setup.constraints,
-            "Separates acceptable experiments from risks that harm people, courses, or institutional trust.".to_string(),
-        );
-    }
-    if saw_concrete_question {
-        push_unique(
-            &mut setup.tastes,
-            "Prefers concrete walkthroughs, examples, and decision stories over abstract positioning.".to_string(),
-        );
-    }
-    if saw_followup_question || (interviewer_question_count > 1 && saw_concrete_question) {
-        push_unique(
-            &mut setup.action_tendencies,
-            "Uses follow-up questions to move from broad narrative into specific decisions, assumptions, criteria, and consequences.".to_string(),
-        );
-    }
-    if saw_user_note_preference {
-        push_unique(
-            &mut setup.action_tendencies,
-            "Turns user-authored note evidence into reviewable Constitution candidates instead of accepting it silently.".to_string(),
-        );
-    }
-
-    setup
-}
-
-fn constitution_setup_entry_count(setup: &ConstitutionSetup) -> usize {
-    setup.values.len()
-        + setup.tastes.len()
-        + setup.constraints.len()
-        + setup.somatic_cues.len()
-        + setup.action_tendencies.len()
-}
-
-fn constitution_setup_claims(setup: &ConstitutionSetup) -> HashSet<String> {
-    setup
-        .values
-        .iter()
-        .chain(setup.tastes.iter())
-        .chain(setup.constraints.iter())
-        .chain(setup.somatic_cues.iter())
-        .chain(setup.action_tendencies.iter())
-        .map(|entry| entry.trim().to_string())
-        .filter(|entry| !entry.is_empty())
-        .collect()
-}
-
-fn push_unique(entries: &mut Vec<String>, entry: String) {
-    let normalized = entry.trim();
-    if normalized.is_empty() {
-        return;
-    }
-    if !entries
-        .iter()
-        .any(|existing| existing.eq_ignore_ascii_case(normalized))
-    {
-        entries.push(normalized.to_string());
-    }
-}
-
-fn constitution_item_is_vault_derived(item: &ConstitutionItem) -> bool {
-    matches!(
-        item.source.as_deref(),
-        Some("note_inference")
-            | Some("interview_behavior_inference")
-            | Some("interview_research_inference")
-    ) || item.evidence_refs.iter().any(|evidence| {
-        matches!(
-            evidence.source_type.as_deref(),
-            Some("note") | Some("interview-question") | Some("interview-answer")
-        )
-    })
-}
-
-fn record_is_vault_derived(record: &UserRecord) -> bool {
-    record.metadata.get("source_note_id").is_some()
-        || matches!(
-            record.metadata.get("source_type").and_then(Value::as_str),
-            Some("interview_answer") | Some("note")
-        )
-        || record.evidence_refs.iter().any(|evidence| {
-            matches!(
-                evidence.source_type.as_deref(),
-                Some("note") | Some("interview-question") | Some("interview-answer")
-            )
-        })
-}
-
-fn split_action_gap_claim(content: &str) -> Option<(String, String)> {
-    let lowered = content.to_lowercase();
-    for separator in [" but ", " however ", " yet ", " although "] {
-        if let Some(index) = lowered.find(separator) {
-            let left = content[..index].trim();
-            let right = content[index + separator.len()..].trim();
-            if left.len() >= 8 && right.len() >= 8 {
-                return Some((left.to_string(), right.to_string()));
-            }
-        }
-    }
-    None
-}
-
-fn constitution_item_relevance(item: &ConstitutionItem, query_terms: &HashSet<String>) -> usize {
-    if query_terms.is_empty() {
-        return 0;
-    }
-    let mut haystack = format!("{} {} {}", item.claim, item.dimension, item.scope.join(" "));
-    for tension in &item.tensions {
-        haystack.push(' ');
-        haystack.push_str(tension);
-    }
-    let item_terms = lexical_terms(&haystack);
-    query_terms.intersection(&item_terms).count()
-}
-
-fn action_gap_relevance(gap: &ActionGap, query_terms: &HashSet<String>) -> usize {
-    if query_terms.is_empty() {
-        return 0;
-    }
-    let mut haystack = format!(
-        "{} {} {}",
-        gap.stated_value, gap.revealed_behavior, gap.decision_risk
-    );
-    if let Some(driver) = &gap.driver_hypothesis {
-        haystack.push(' ');
-        haystack.push_str(driver);
-    }
-    if let Some(signal) = &gap.somatic_taste_signal {
-        haystack.push(' ');
-        haystack.push_str(signal);
-    }
-    let gap_terms = lexical_terms(&haystack);
-    query_terms.intersection(&gap_terms).count()
-}
-
 fn clamp_decision_mirror_weights(mut weights: DecisionMirrorWeights) -> DecisionMirrorWeights {
     weights.notes_weight = clamp_weight(weights.notes_weight);
     weights.approved_records_weight = clamp_weight(weights.approved_records_weight);
@@ -1123,902 +541,134 @@ fn memory_digest_cluster_key(record: &UserRecord) -> String {
         .get("signal_family")
         .and_then(Value::as_str)
         .filter(|value| !value.trim().is_empty())
-    {
-        return format!("{:?}::{}", record.kind, signal_family.trim().to_lowercase());
-    }
-
-    let mut terms = lexical_terms(&record.content)
-        .into_iter()
-        .collect::<Vec<_>>();
-    terms.sort();
-    terms.truncate(6);
-    if terms.is_empty() {
-        format!("{:?}::{}", record.kind, normalize_key_text(&record.content))
-    } else {
-        format!("{:?}::{}", record.kind, terms.join("-"))
-    }
-}
-
-fn stable_digest_id(records: &[UserRecord]) -> String {
-    let mut ids = records
-        .iter()
-        .map(|record| record.id.as_str())
-        .collect::<Vec<_>>();
-    ids.sort_unstable();
-    let mut hasher = DefaultHasher::new();
-    ids.hash(&mut hasher);
-    format!("digest-cluster-{:x}", hasher.finish())
-}
-
-fn stale_for_review(record: &UserRecord) -> bool {
-    Utc::now()
-        .signed_duration_since(record.updated_at)
-        .num_days()
-        >= 90
-}
-
-fn digest_state_sort_key(state: &MemoryDigestState) -> u8 {
-    match state {
-        MemoryDigestState::Pending => 0,
-        MemoryDigestState::Softened => 1,
-        MemoryDigestState::Kept => 2,
-        MemoryDigestState::NotMe => 3,
-        MemoryDigestState::Private => 4,
-        MemoryDigestState::NoTrain => 5,
-        MemoryDigestState::Rejected => 6,
-    }
-}
-
-fn memory_digest_state_for_action(action: &MemoryDigestAction) -> MemoryDigestState {
-    match action {
-        MemoryDigestAction::Keep => MemoryDigestState::Kept,
-        MemoryDigestAction::Soften => MemoryDigestState::Softened,
-        MemoryDigestAction::NotMe => MemoryDigestState::NotMe,
-        MemoryDigestAction::Private => MemoryDigestState::Private,
-        MemoryDigestAction::NoTrain => MemoryDigestState::NoTrain,
-        MemoryDigestAction::Reject => MemoryDigestState::Rejected,
-    }
-}
-
-
-pub struct TwinStore {
-    root_path: PathBuf,
-    traces_path: PathBuf,
-    records_path: PathBuf,
-    decisions_path: PathBuf,
-    reflections_path: PathBuf,
-    constitution_path: PathBuf,
-    action_gaps_path: PathBuf,
-    setup_path: PathBuf,
-    decision_mirror_config_path: PathBuf,
-    digest_path: PathBuf,
-    exports_path: PathBuf,
-    trace_cache: HashMap<String, SessionTrace>,
-    record_cache: HashMap<String, UserRecord>,
-    records_cache_ready: bool,
-}
-
-impl TwinStore {
-    pub fn new(root_path: PathBuf) -> Self {
-        let traces_path = root_path.join("traces");
-        let records_path = root_path.join("records");
-        let decisions_path = root_path.join("decisions");
-        let reflections_path = root_path.join("reflections");
-        let constitution_path = root_path.join("constitution");
-        let action_gaps_path = root_path.join("action_gaps");
-        let setup_path = root_path.join("constitution_setup.json");
-        let decision_mirror_config_path = root_path.join("decision_mirror_config.json");
-        let digest_path = root_path.join("memory_digest.json");
-        let exports_path = root_path.join("exports");
-
-        std::fs::create_dir_all(&traces_path).ok();
-        std::fs::create_dir_all(&records_path).ok();
-        std::fs::create_dir_all(&decisions_path).ok();
-        std::fs::create_dir_all(&reflections_path).ok();
-        std::fs::create_dir_all(&constitution_path).ok();
-        std::fs::create_dir_all(&action_gaps_path).ok();
-        std::fs::create_dir_all(&exports_path).ok();
-
-        Self {
-            root_path,
-            traces_path,
-            records_path,
-            decisions_path,
-            reflections_path,
-            constitution_path,
-            action_gaps_path,
-            setup_path,
-            decision_mirror_config_path,
-            digest_path,
-            exports_path,
-            trace_cache: HashMap::new(),
-            record_cache: HashMap::new(),
-            records_cache_ready: false,
-        }
-    }
-
-    fn write_pretty_json<T: Serialize>(&self, path: &Path, value: &T) -> Result<()> {
-        if let Some(parent) = path.parent() {
-            std::fs::create_dir_all(parent)
-                .with_context(|| format!("Failed to create directory: {}", parent.display()))?;
-        }
-
-        let content = serde_json::to_string_pretty(value)?;
-        write_atomic(path, content.as_bytes())
-            .with_context(|| format!("Failed to write JSON file: {}", path.display()))
-    }
-
-    fn validate_file_id(id: &str) -> Result<()> {
-        if id.is_empty() || id.contains('/') || id.contains('\\') || id.contains("..") {
-            anyhow::bail!("Invalid file id: {}", id);
-        }
-
-        Ok(())
-    }
-
-    pub fn list_constitution_items(&self) -> Result<Vec<ConstitutionItem>> {
-        let mut items = Vec::new();
-        if !self.constitution_path.exists() {
-            return Ok(items);
-        }
-
-        for entry in WalkDir::new(&self.constitution_path)
-            .min_depth(1)
-            .max_depth(1)
-            .into_iter()
-            .filter_map(|entry| entry.ok())
-        {
-            let path = entry.path();
-            if path.extension().is_some_and(|ext| ext == "json") {
-                if let Some(item) =
-                    load_or_quarantine::<ConstitutionItem>(path, "constitution item")
-                {
-                    items.push(item);
-                }
-            }
-        }
-
-        items.sort_by(|a, b| {
-            constitution_status_sort_key(&a.status)
-                .cmp(&constitution_status_sort_key(&b.status))
-                .then_with(|| {
-                    b.priority
-                        .partial_cmp(&a.priority)
-                        .unwrap_or(std::cmp::Ordering::Equal)
-                })
-                .then_with(|| b.updated_at.cmp(&a.updated_at))
-        });
-        Ok(items)
-    }
-
-    pub fn create_constitution_item(
-        &self,
-        create: ConstitutionItemCreate,
-    ) -> Result<ConstitutionItem> {
-        let now = Utc::now();
-        let item = ConstitutionItem {
-            id: uuid::Uuid::new_v4().to_string(),
-            claim: create.claim,
-            dimension: create.dimension,
-            scope: create.scope,
-            priority: create.priority.clamp(0.0, 1.0),
-            confidence: create.confidence.clamp(0.0, 1.0),
-            status: create.status,
-            evidence_refs: create.evidence_refs,
-            tensions: create.tensions,
-            linked_record_ids: create.linked_record_ids,
-            source: create.source,
-            created_at: now,
-            updated_at: now,
-        };
-        self.write_constitution_file(&item)?;
-        Ok(item)
-    }
-
-    pub fn update_constitution_item(
-        &self,
-        id: &str,
-        update: ConstitutionItemUpdate,
-    ) -> Result<ConstitutionItem> {
-        Self::validate_file_id(id)?;
-        let path = self.constitution_file_path(id);
-        let mut item = self.read_constitution_file(&path)?;
-        if let Some(claim) = update.claim {
-            item.claim = claim;
-        }
-        if let Some(dimension) = update.dimension {
-            item.dimension = dimension;
-        }
-        if let Some(scope) = update.scope {
-            item.scope = scope;
-        }
-        if let Some(priority) = update.priority {
-            item.priority = priority.clamp(0.0, 1.0);
-        }
-        if let Some(confidence) = update.confidence {
-            item.confidence = confidence.clamp(0.0, 1.0);
-        }
-        if let Some(status) = update.status {
-            item.status = status;
-        }
-        if let Some(tensions) = update.tensions {
-            item.tensions = tensions;
-        }
-        item.updated_at = Utc::now();
-        self.write_constitution_file(&item)?;
-        Ok(item)
-    }
-
-    pub fn review_constitution_item(
-        &mut self,
-        id: &str,
-        request: ConstitutionReviewRequest,
-    ) -> Result<ConstitutionItem> {
-        Self::validate_file_id(id)?;
-        let mut item = self.read_constitution_file(&self.constitution_file_path(id))?;
-        item.status = constitution_status_for_action(&request.action);
-        item.updated_at = Utc::now();
-        self.write_constitution_file(&item)?;
-        self.append_trace_event(
-            "constitution-review",
-            TraceEventType::ConstitutionItemReviewed,
-            json!({
-                "constitution_item_id": item.id,
-                "action": request.action,
-                "rationale": request.rationale,
-            }),
-        )?;
-        Ok(item)
-    }
-
-    pub fn list_action_gaps(&self) -> Result<Vec<ActionGap>> {
-        let mut gaps = Vec::new();
-        if !self.action_gaps_path.exists() {
-            return Ok(gaps);
-        }
-
-        for entry in WalkDir::new(&self.action_gaps_path)
-            .min_depth(1)
-            .max_depth(1)
-            .into_iter()
-            .filter_map(|entry| entry.ok())
-        {
-            let path = entry.path();
-            if path.extension().is_some_and(|ext| ext == "json") {
-                if let Some(gap) = load_or_quarantine::<ActionGap>(path, "action gap") {
-                    gaps.push(gap);
-                }
-            }
-        }
-
-        gaps.sort_by(|a, b| {
-            constitution_status_sort_key(&a.status)
-                .cmp(&constitution_status_sort_key(&b.status))
-                .then_with(|| {
-                    b.confidence
-                        .partial_cmp(&a.confidence)
-                        .unwrap_or(std::cmp::Ordering::Equal)
-                })
-                .then_with(|| b.updated_at.cmp(&a.updated_at))
-        });
-        Ok(gaps)
-    }
-
-    pub fn create_action_gap(&self, create: ActionGapCreate) -> Result<ActionGap> {
-        let now = Utc::now();
-        let gap = ActionGap {
-            id: uuid::Uuid::new_v4().to_string(),
-            stated_value: create.stated_value,
-            revealed_behavior: create.revealed_behavior,
-            driver_hypothesis: create.driver_hypothesis,
-            somatic_taste_signal: create.somatic_taste_signal,
-            decision_risk: create.decision_risk,
-            evidence_refs: create.evidence_refs,
-            linked_record_ids: create.linked_record_ids,
-            confidence: create.confidence.clamp(0.0, 1.0),
-            status: create.status,
-            created_at: now,
-            updated_at: now,
-        };
-        self.write_action_gap_file(&gap)?;
-        Ok(gap)
-    }
-
-    pub fn review_action_gap(
-        &mut self,
-        id: &str,
-        request: ConstitutionReviewRequest,
-    ) -> Result<ActionGap> {
-        Self::validate_file_id(id)?;
-        let mut gap = self.read_action_gap_file(&self.action_gap_file_path(id))?;
-        gap.status = constitution_status_for_action(&request.action);
-        gap.updated_at = Utc::now();
-        self.write_action_gap_file(&gap)?;
-        self.append_trace_event(
-            "constitution-review",
-            TraceEventType::ActionGapReviewed,
-            json!({
-                "action_gap_id": gap.id,
-                "action": request.action,
-                "rationale": request.rationale,
-            }),
-        )?;
-        Ok(gap)
-    }
-
-    pub fn get_constitution_setup(&self) -> Result<ConstitutionSetup> {
-        if !self.setup_path.exists() {
-            return Ok(ConstitutionSetup::default());
-        }
-
-        let content = std::fs::read_to_string(&self.setup_path).with_context(|| {
-            format!(
-                "Failed to read constitution setup file: {}",
-                self.setup_path.display()
-            )
-        })?;
-        serde_json::from_str(&content).with_context(|| {
-            format!(
-                "Failed to parse constitution setup file: {}",
-                self.setup_path.display()
-            )
-        })
-    }
-
-    pub fn save_constitution_setup(
-        &mut self,
-        mut setup: ConstitutionSetup,
-    ) -> Result<ConstitutionSetup> {
-        setup.twin_name = clean_optional_setup_entry(setup.twin_name);
-        setup.twin_role = clean_optional_setup_entry(setup.twin_role);
-        setup.source_boundaries = clean_setup_entries(setup.source_boundaries);
-        setup.values = clean_setup_entries(setup.values);
-        setup.tastes = clean_setup_entries(setup.tastes);
-        setup.constraints = clean_setup_entries(setup.constraints);
-        setup.somatic_cues = clean_setup_entries(setup.somatic_cues);
-        setup.action_tendencies = clean_setup_entries(setup.action_tendencies);
-        setup.updated_at = Some(Utc::now());
-        self.write_pretty_json(&self.setup_path, &setup)?;
-
-        let event = self.append_trace_event(
-            "constitution-setup",
-            TraceEventType::ConstitutionSetupSaved,
-            json!({
-                "twin_name": setup.twin_name,
-                "twin_role": setup.twin_role,
-                "source_boundaries": setup.source_boundaries,
-                "values": setup.values,
-                "tastes": setup.tastes,
-                "constraints": setup.constraints,
-                "somatic_cues": setup.somatic_cues,
-                "action_tendencies": setup.action_tendencies,
-            }),
-        )?;
-        let evidence_ref = EvidenceRef {
-            trace_id: "constitution-setup".to_string(),
-            event_id: event.id,
-            session_id: "constitution-setup".to_string(),
-            tile_id: None,
-            model_id: None,
-            note: Some("Guided Twin setup".to_string()),
-            source_type: Some("setup".to_string()),
-            source_id: Some("constitution-setup".to_string()),
-            source_label: Some("Guided Twin setup".to_string()),
-            excerpt: None,
-            speaker_role: None,
-        };
-
-        self.seed_constitution_setup_items(&setup, evidence_ref)?;
-        Ok(setup)
-    }
-
-    pub fn run_constitution_inference(&mut self) -> Result<ConstitutionInferenceSummary> {
-        self.run_constitution_inference_with_notes(&[])
-    }
-
-    pub fn run_constitution_inference_with_notes(
-        &mut self,
-        notes: &[Note],
-    ) -> Result<ConstitutionInferenceSummary> {
-        self.ensure_record_cache()?;
-        let current_note_ids = notes
-            .iter()
-            .map(|note| note.id.clone())
-            .collect::<HashSet<_>>();
-        let pruned_stale_records = self.prune_stale_note_records(&current_note_ids)?;
-        let distilled_setup = distill_constitution_setup_from_notes(notes);
-        let updated_setup_entries = constitution_setup_entry_count(&distilled_setup);
-        let pruned_stale_constitution_items = self
-            .prune_stale_note_constitution_items(&current_note_ids)?
-            + self.prune_stale_setup_constitution_items(&distilled_setup)?;
-        if updated_setup_entries > 0 || self.setup_path.exists() {
-            self.write_auto_constitution_setup(distilled_setup.clone())?;
-        }
-        self.ensure_record_cache()?;
-        let records = self
-            .record_cache
-            .values()
-            .filter(|record| constitution_allows_record(record))
-            .cloned()
-            .collect::<Vec<_>>();
-        let traces = self.list_session_traces()?;
-        let scanned_behavior_events = traces
-            .iter()
-            .flat_map(|trace| trace.events.iter())
-            .filter(|event| behavior_event_for_constitution(&event.event_type))
-            .count();
-        let decisions = self.list_decision_episodes()?;
-        let existing_items = self.list_constitution_items()?;
-        let existing_gaps = self.list_action_gaps()?;
-        let mut item_keys = existing_items
-            .iter()
-            .map(|item| constitution_key(&item.dimension, &item.claim))
-            .collect::<HashSet<_>>();
-        let mut gap_keys = existing_gaps
-            .iter()
-            .map(|gap| action_gap_key(&gap.stated_value, &gap.revealed_behavior))
-            .collect::<HashSet<_>>();
-
-        let mut created_constitution_items = 0_usize;
-        let mut created_action_gaps = 0_usize;
-        let mut auto_active_items = 0_usize;
-        let mut review_candidate_items = 0_usize;
-        let mut skipped_domain_claims = 0_usize;
-        let mut extracted_research_findings = 0_usize;
-
-        for record in &records {
-            let dimension = infer_constitution_dimension(&record.content, &record.kind);
-            let claim = record.content.trim().to_string();
-            if claim.is_empty() {
-                continue;
-            }
-            let key = constitution_key(&dimension, &claim);
-            if item_keys.insert(key) {
-                let status = constitution_status_from_record(record);
-                if status == ConstitutionStatus::Active {
-                    auto_active_items += 1;
-                } else if status == ConstitutionStatus::Candidate {
-                    review_candidate_items += 1;
-                }
-                let source = if record.origin == RecordOrigin::Inferred {
-                    "behavior_inference"
-                } else {
-                    "constitution_inference"
-                };
-                self.create_constitution_item(ConstitutionItemCreate {
-                    claim,
-                    dimension,
-                    scope: vec!["general".to_string()],
-                    priority: record.confidence,
-                    confidence: record.confidence,
-                    status,
-                    evidence_refs: record.evidence_refs.clone(),
-                    tensions: Vec::new(),
-                    linked_record_ids: vec![record.id.clone()],
-                    source: Some(source.to_string()),
-                })?;
-                created_constitution_items += 1;
-            }
-
-            if let Some((stated_value, revealed_behavior)) = split_action_gap_claim(&record.content)
-            {
-                let key = action_gap_key(&stated_value, &revealed_behavior);
-                if gap_keys.insert(key) {
-                    self.create_action_gap(ActionGapCreate {
-                        stated_value,
-                        revealed_behavior,
-                        driver_hypothesis: Some(
-                            "Inferred from a contradiction-style user record".to_string(),
-                        ),
-                        somatic_taste_signal: None,
-                        decision_risk:
-                            "The user's endorsed intent may diverge from what they repeatedly do."
-                                .to_string(),
-                        evidence_refs: record.evidence_refs.clone(),
-                        linked_record_ids: vec![record.id.clone()],
-                        confidence: record.confidence,
-                        status: ConstitutionStatus::Candidate,
-                    })?;
-                    created_action_gaps += 1;
-                }
-            }
-        }
-
-        for decision in &decisions {
-            let Some(initial_leaning) = decision.initial_leaning.as_ref() else {
-                continue;
-            };
-            let Some(chosen_option) = decision.chosen_option.as_ref() else {
-                continue;
-            };
-            if initial_leaning
-                .trim()
-                .eq_ignore_ascii_case(chosen_option.trim())
-            {
-                continue;
-            }
-            let stated_value = format!("Initial leaning: {}", initial_leaning.trim());
-            let revealed_behavior = format!("Chosen option: {}", chosen_option.trim());
-            let key = action_gap_key(&stated_value, &revealed_behavior);
-            if gap_keys.insert(key) {
-                self.create_action_gap(ActionGapCreate {
-                    stated_value,
-                    revealed_behavior,
-                    driver_hypothesis: Some("Inferred from a decision where final action diverged from initial leaning.".to_string()),
-                    somatic_taste_signal: decision.primitive_assessment.somatic_signal.clone(),
-                    decision_risk: "Grafyn should check whether future similar decisions repeat this gap.".to_string(),
-                    evidence_refs: self.decision_evidence_refs(&decision.id)?,
-                    linked_record_ids: Vec::new(),
-                    confidence: 0.68,
-                    status: ConstitutionStatus::Candidate,
-                })?;
-                created_action_gaps += 1;
-            }
-        }
-
-        for note in notes {
-            if note_is_interview(note) {
-                match extract_interview_note_evidence(note) {
-                    InterviewExtraction::Unlabeled => {
-                        skipped_domain_claims += 1;
-                    }
-                    InterviewExtraction::Labeled {
-                        interviewer_turns,
-                        interviewee_turns,
-                    } => {
-                        for turn in interviewer_turns {
-                            if let Some((dimension, claim)) =
-                                constitution_claim_from_interviewer_turn(&turn.content)
-                            {
-                                let key = constitution_key(&dimension, &claim);
-                                if item_keys.insert(key) {
-                                    self.create_constitution_item(ConstitutionItemCreate {
-                                        claim,
-                                        dimension,
-                                        scope: vec!["interview".to_string()],
-                                        priority: 0.62,
-                                        confidence: 0.62,
-                                        status: ConstitutionStatus::Candidate,
-                                        evidence_refs: vec![note_evidence_ref(
-                                            note,
-                                            "interview-question",
-                                            "Interviewer question",
-                                            Some("user"),
-                                            &turn.content,
-                                        )],
-                                        tensions: Vec::new(),
-                                        linked_record_ids: Vec::new(),
-                                        source: Some("interview_behavior_inference".to_string()),
-                                    })?;
-                                    created_constitution_items += 1;
-                                    review_candidate_items += 1;
-                                }
-                            }
-                        }
-                        for turn in interviewee_turns {
-                            if !looks_like_research_finding(&turn.content) {
-                                skipped_domain_claims += 1;
-                                continue;
-                            }
-                            if self.create_interview_research_record(note, &turn.content)? {
-                                extracted_research_findings += 1;
-                            }
-                        }
-                    }
-                }
-                continue;
-            }
-
-            if let Some((dimension, claim)) = constitution_claim_from_note(note) {
-                let key = constitution_key(&dimension, &claim);
-                if item_keys.insert(key) {
-                    self.create_constitution_item(ConstitutionItemCreate {
-                        claim,
-                        dimension,
-                        scope: vec!["note".to_string()],
-                        priority: 0.58,
-                        confidence: 0.58,
-                        status: ConstitutionStatus::Candidate,
-                        evidence_refs: vec![note_evidence_ref(
-                            note,
-                            "note",
-                            "Vault note",
-                            Some("user"),
-                            &note.content,
-                        )],
-                        tensions: Vec::new(),
-                        linked_record_ids: Vec::new(),
-                        source: Some("note_inference".to_string()),
-                    })?;
-                    created_constitution_items += 1;
-                    review_candidate_items += 1;
-                }
-            } else {
-                skipped_domain_claims += 1;
-            }
-        }
-
-        let summary = ConstitutionInferenceSummary {
-            scanned_records: records.len(),
-            scanned_decisions: decisions.len(),
-            created_constitution_items,
-            created_action_gaps,
-            scanned_behavior_events,
-            scanned_notes: notes.len(),
-            scanned_interviews: notes.iter().filter(|note| note_is_interview(note)).count(),
-            auto_active_items,
-            review_candidate_items,
-            skipped_domain_claims,
-            extracted_research_findings,
-            pruned_stale_constitution_items,
-            pruned_stale_records,
-            updated_setup_entries,
-            generated_at: Utc::now(),
-        };
-        self.append_trace_event(
-            "constitution-inference",
-            TraceEventType::ConstitutionInferenceRun,
-            serde_json::to_value(&summary)?,
-        )?;
-        Ok(summary)
-    }
-
-    fn create_interview_research_record(&mut self, note: &Note, content: &str) -> Result<bool> {
-        self.ensure_record_cache()?;
-        let finding = format!("Interview finding: {}", excerpt(content.trim()));
-        let existing = self.record_cache.values().any(|record| {
-            record.kind == UserRecordKind::Fact
-                && record.content == finding
-                && record.metadata.get("source_type").and_then(Value::as_str)
-                    == Some("interview_answer")
-        });
-        if existing {
-            return Ok(false);
-        }
-
-        self.create_user_record(UserRecordCreate {
-            kind: UserRecordKind::Fact,
-            content: finding,
-            evidence_refs: vec![note_evidence_ref(
-                note,
-                "interview-answer",
-                "Interviewee answer",
-                Some("interviewee"),
-                content,
-            )],
-            confidence: 0.66,
-            origin: RecordOrigin::Inferred,
-            promotion_state: Some(PromotionState::Candidate),
-            valid_from: None,
-            valid_until: None,
-            links: Vec::new(),
-            metadata: HashMap::from([
-                ("source_type".to_string(), json!("interview_answer")),
-                ("source_note_id".to_string(), json!(note.id.clone())),
-            ]),
-        })?;
-        Ok(true)
-    }
-
-    fn write_auto_constitution_setup(&self, mut setup: ConstitutionSetup) -> Result<()> {
-        if let Ok(existing) = self.get_constitution_setup() {
-            setup.twin_name = existing.twin_name;
-            setup.twin_role = existing.twin_role;
-            setup.source_boundaries = existing.source_boundaries;
-        }
-        setup.twin_name = clean_optional_setup_entry(setup.twin_name);
-        setup.twin_role = clean_optional_setup_entry(setup.twin_role);
-        setup.source_boundaries = clean_setup_entries(setup.source_boundaries);
-        setup.values = clean_setup_entries(setup.values);
-        setup.tastes = clean_setup_entries(setup.tastes);
-        setup.constraints = clean_setup_entries(setup.constraints);
-        setup.somatic_cues = clean_setup_entries(setup.somatic_cues);
-        setup.action_tendencies = clean_setup_entries(setup.action_tendencies);
-        setup.updated_at = Some(Utc::now());
-        self.write_pretty_json(&self.setup_path, &setup)
-    }
-
-    fn prune_stale_note_records(&mut self, current_note_ids: &HashSet<String>) -> Result<usize> {
-        self.ensure_record_cache()?;
-        let stale_ids = self
-            .record_cache
-            .values()
-            .filter(|record| record_is_vault_derived(record))
-            .filter(|record| {
-                record
-                    .metadata
-                    .get("source_note_id")
-                    .and_then(Value::as_str)
-                    .is_some_and(|source_note_id| !current_note_ids.contains(source_note_id))
-            })
-            .map(|record| record.id.clone())
-            .collect::<Vec<_>>();
-
-        for id in &stale_ids {
-            self.record_cache.remove(id);
-            let path = self.records_path.join(format!("{}.json", id));
-            if path.exists() {
-                std::fs::remove_file(&path).with_context(|| {
-                    format!("Failed to remove stale Twin record: {}", path.display())
-                })?;
-            }
-        }
-
-        Ok(stale_ids.len())
-    }
-
-    fn prune_stale_note_constitution_items(
-        &self,
-        current_note_ids: &HashSet<String>,
-    ) -> Result<usize> {
-        let stale_items = self
-            .list_constitution_items()?
-            .into_iter()
-            .filter(|item| constitution_item_is_vault_derived(item))
-            .filter(|item| {
-                item.evidence_refs
-                    .iter()
-                    .filter_map(|evidence| evidence.source_id.as_deref())
-                    .any(|source_id| !current_note_ids.contains(source_id))
-            })
-            .collect::<Vec<_>>();
-
-        for item in &stale_items {
-            let path = self.constitution_path.join(format!("{}.json", item.id));
-            if path.exists() {
-                std::fs::remove_file(&path).with_context(|| {
-                    format!(
-                        "Failed to remove stale Constitution item: {}",
-                        path.display()
-                    )
-                })?;
-            }
-        }
-
-        Ok(stale_items.len())
+    {
+        return format!("{:?}::{}", record.kind, signal_family.trim().to_lowercase());
     }
 
-    fn prune_stale_setup_constitution_items(&self, setup: &ConstitutionSetup) -> Result<usize> {
-        let setup_claims = constitution_setup_claims(setup);
-        let stale_items = self
-            .list_constitution_items()?
-            .into_iter()
-            .filter(|item| item.source.as_deref() == Some("guided_setup"))
-            .filter(|item| !setup_claims.contains(item.claim.trim()))
-            .collect::<Vec<_>>();
-
-        for item in &stale_items {
-            let path = self.constitution_path.join(format!("{}.json", item.id));
-            if path.exists() {
-                std::fs::remove_file(&path).with_context(|| {
-                    format!(
-                        "Failed to remove stale setup Constitution item: {}",
-                        path.display()
-                    )
-                })?;
-            }
-        }
-
-        Ok(stale_items.len())
+    let mut terms = lexical_terms(&record.content)
+        .into_iter()
+        .collect::<Vec<_>>();
+    terms.sort();
+    terms.truncate(6);
+    if terms.is_empty() {
+        format!("{:?}::{}", record.kind, normalize_key_text(&record.content))
+    } else {
+        format!("{:?}::{}", record.kind, terms.join("-"))
     }
+}
 
-    pub fn select_constitution_context(
-        &self,
-        query: &str,
-    ) -> Result<(Vec<ConstitutionItem>, Vec<ActionGap>)> {
-        let query_terms = lexical_terms(query);
-        let mut items = self
-            .list_constitution_items()?
-            .into_iter()
-            .filter(|item| constitution_context_allowed(&item.status))
-            .map(|item| (constitution_item_relevance(&item, &query_terms), item))
-            .filter(|(score, item)| *score > 0 || item.status == ConstitutionStatus::Active)
-            .collect::<Vec<_>>();
-        items.sort_by(|a, b| {
-            b.0.cmp(&a.0)
-                .then_with(|| {
-                    b.1.priority
-                        .partial_cmp(&a.1.priority)
-                        .unwrap_or(std::cmp::Ordering::Equal)
-                })
-                .then_with(|| b.1.updated_at.cmp(&a.1.updated_at))
-        });
+fn stable_digest_id(records: &[UserRecord]) -> String {
+    let mut ids = records
+        .iter()
+        .map(|record| record.id.as_str())
+        .collect::<Vec<_>>();
+    ids.sort_unstable();
+    let mut hasher = DefaultHasher::new();
+    ids.hash(&mut hasher);
+    format!("digest-cluster-{:x}", hasher.finish())
+}
 
-        let mut gaps = self
-            .list_action_gaps()?
-            .into_iter()
-            .filter(|gap| constitution_context_allowed(&gap.status))
-            .map(|gap| (action_gap_relevance(&gap, &query_terms), gap))
-            .filter(|(score, gap)| *score > 0 || gap.status == ConstitutionStatus::Active)
-            .collect::<Vec<_>>();
-        gaps.sort_by(|a, b| {
-            b.0.cmp(&a.0)
-                .then_with(|| {
-                    b.1.confidence
-                        .partial_cmp(&a.1.confidence)
-                        .unwrap_or(std::cmp::Ordering::Equal)
-                })
-                .then_with(|| b.1.updated_at.cmp(&a.1.updated_at))
-        });
+fn stale_for_review(record: &UserRecord) -> bool {
+    Utc::now()
+        .signed_duration_since(record.updated_at)
+        .num_days()
+        >= 90
+}
 
-        Ok((
-            items.into_iter().take(8).map(|(_, item)| item).collect(),
-            gaps.into_iter().take(4).map(|(_, gap)| gap).collect(),
-        ))
+fn digest_state_sort_key(state: &MemoryDigestState) -> u8 {
+    match state {
+        MemoryDigestState::Pending => 0,
+        MemoryDigestState::Softened => 1,
+        MemoryDigestState::Kept => 2,
+        MemoryDigestState::NotMe => 3,
+        MemoryDigestState::Private => 4,
+        MemoryDigestState::NoTrain => 5,
+        MemoryDigestState::Rejected => 6,
     }
+}
 
-    fn constitution_file_path(&self, item_id: &str) -> PathBuf {
-        self.constitution_path.join(format!("{}.json", item_id))
+fn memory_digest_state_for_action(action: &MemoryDigestAction) -> MemoryDigestState {
+    match action {
+        MemoryDigestAction::Keep => MemoryDigestState::Kept,
+        MemoryDigestAction::Soften => MemoryDigestState::Softened,
+        MemoryDigestAction::NotMe => MemoryDigestState::NotMe,
+        MemoryDigestAction::Private => MemoryDigestState::Private,
+        MemoryDigestAction::NoTrain => MemoryDigestState::NoTrain,
+        MemoryDigestAction::Reject => MemoryDigestState::Rejected,
     }
+}
 
-    fn action_gap_file_path(&self, gap_id: &str) -> PathBuf {
-        self.action_gaps_path.join(format!("{}.json", gap_id))
-    }
 
-    fn read_constitution_file(&self, path: &Path) -> Result<ConstitutionItem> {
-        let content = std::fs::read_to_string(path)
-            .with_context(|| format!("Failed to read constitution file: {}", path.display()))?;
-        serde_json::from_str(&content)
-            .with_context(|| format!("Failed to parse constitution file: {}", path.display()))
-    }
+pub struct TwinStore {
+    root_path: PathBuf,
+    traces_path: PathBuf,
+    records_path: PathBuf,
+    decisions_path: PathBuf,
+    reflections_path: PathBuf,
+    constitution_path: PathBuf,
+    action_gaps_path: PathBuf,
+    setup_path: PathBuf,
+    decision_mirror_config_path: PathBuf,
+    digest_path: PathBuf,
+    exports_path: PathBuf,
+    trace_cache: HashMap<String, SessionTrace>,
+    record_cache: HashMap<String, UserRecord>,
+    records_cache_ready: bool,
+}
 
-    fn read_action_gap_file(&self, path: &Path) -> Result<ActionGap> {
-        let content = std::fs::read_to_string(path)
-            .with_context(|| format!("Failed to read action gap file: {}", path.display()))?;
-        serde_json::from_str(&content)
-            .with_context(|| format!("Failed to parse action gap file: {}", path.display()))
-    }
+impl TwinStore {
+    pub fn new(root_path: PathBuf) -> Self {
+        let traces_path = root_path.join("traces");
+        let records_path = root_path.join("records");
+        let decisions_path = root_path.join("decisions");
+        let reflections_path = root_path.join("reflections");
+        let constitution_path = root_path.join("constitution");
+        let action_gaps_path = root_path.join("action_gaps");
+        let setup_path = root_path.join("constitution_setup.json");
+        let decision_mirror_config_path = root_path.join("decision_mirror_config.json");
+        let digest_path = root_path.join("memory_digest.json");
+        let exports_path = root_path.join("exports");
+
+        std::fs::create_dir_all(&traces_path).ok();
+        std::fs::create_dir_all(&records_path).ok();
+        std::fs::create_dir_all(&decisions_path).ok();
+        std::fs::create_dir_all(&reflections_path).ok();
+        std::fs::create_dir_all(&constitution_path).ok();
+        std::fs::create_dir_all(&action_gaps_path).ok();
+        std::fs::create_dir_all(&exports_path).ok();
 
-    fn write_constitution_file(&self, item: &ConstitutionItem) -> Result<()> {
-        let path = self.constitution_file_path(&item.id);
-        self.write_pretty_json(&path, item)
+        Self {
+            root_path,
+            traces_path,
+            records_path,
+            decisions_path,
+            reflections_path,
+            constitution_path,
+            action_gaps_path,
+            setup_path,
+            decision_mirror_config_path,
+            digest_path,
+            exports_path,
+            trace_cache: HashMap::new(),
+            record_cache: HashMap::new(),
+            records_cache_ready: false,
+        }
     }
 
-    fn write_action_gap_file(&self, gap: &ActionGap) -> Result<()> {
-        let path = self.action_gap_file_path(&gap.id);
-        self.write_pretty_json(&path, gap)
+    fn write_pretty_json<T: Serialize>(&self, path: &Path, value: &T) -> Result<()> {
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent)
+                .with_context(|| format!("Failed to create directory: {}", parent.display()))?;
+        }
+
+        let content = serde_json::to_string_pretty(value)?;
+        write_atomic(path, content.as_bytes())
+            .with_context(|| format!("Failed to write JSON file: {}", path.display()))
     }
 
-    fn seed_constitution_setup_items(
-        &self,
-        setup: &ConstitutionSetup,
-        evidence_ref: EvidenceRef,
-    ) -> Result<()> {
-        let existing_keys = self
-            .list_constitution_items()?
-            .into_iter()
-            .map(|item| constitution_key(&item.dimension, &item.claim))
-            .collect::<HashSet<_>>();
-        let mut created_keys = existing_keys;
-
-        let groups: &[(&str, &[String])] = &[
-            ("values", &setup.values),
-            ("taste", &setup.tastes),
-            ("constraints", &setup.constraints),
-            ("somatic", &setup.somatic_cues),
-            ("action_tendency", &setup.action_tendencies),
-        ];
-
-        for (dimension, entries) in groups {
-            for entry in entries.iter().filter(|entry| !entry.trim().is_empty()) {
-                let claim = entry.trim().to_string();
-                let key = constitution_key(dimension, &claim);
-                if !created_keys.insert(key) {
-                    continue;
-                }
-                self.create_constitution_item(ConstitutionItemCreate {
-                    claim,
-                    dimension: (*dimension).to_string(),
-                    scope: vec!["setup".to_string()],
-                    priority: 0.9,
-                    confidence: 0.9,
-                    status: ConstitutionStatus::Active,
-                    evidence_refs: vec![evidence_ref.clone()],
-                    tensions: Vec::new(),
-                    linked_record_ids: Vec::new(),
-                    source: Some("guided_setup".to_string()),
-                })?;
-            }
+    fn validate_file_id(id: &str) -> Result<()> {
+        if id.is_empty() || id.contains('/') || id.contains('\\') || id.contains("..") {
+            anyhow::bail!("Invalid file id: {}", id);
         }
 
         Ok(())
@@ -3301,354 +1951,6 @@ mod tests {
     };
     use tempfile::tempdir;
 
-    use crate::models::twin::ConstitutionStatus;
-    fn test_note(id: &str, title: &str, content: &str, source_type: Option<&str>) -> Note {
-        let now = Utc::now();
-        let mut properties = HashMap::new();
-        if let Some(source_type) = source_type {
-            properties.insert(
-                "source_type".to_string(),
-                Value::String(source_type.to_string()),
-            );
-        }
-        Note {
-            id: id.to_string(),
-            title: title.to_string(),
-            content: content.to_string(),
-            relative_path: format!("{}.md", id),
-            aliases: Vec::new(),
-            status: NoteStatus::Evidence,
-            tags: Vec::new(),
-            created_at: now,
-            updated_at: now,
-            schema_version: crate::models::note::CURRENT_NOTE_SCHEMA_VERSION,
-            migration_source: None,
-            optimizer_managed: false,
-            wikilinks: Vec::new(),
-            parsed_links: Vec::new(),
-            properties,
-            ..Default::default()
-        }
-    }
-
-    #[test]
-    fn constitution_inference_uses_repeated_behavior_as_primary_evidence() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        for index in 0..3 {
-            store
-                .append_trace_event(
-                    "session-1",
-                    TraceEventType::PromptSubmitted,
-                    serde_json::json!({
-                        "tile_id": format!("tile-{}", index),
-                        "prompt": "Please implement this with exact files, commands, and tests.",
-                        "models": ["openai/gpt-4o"],
-                    }),
-                )
-                .expect("trace event should append");
-        }
-
-        store
-            .run_twin_inference()
-            .expect("record inference should run");
-        let summary = store
-            .run_constitution_inference_with_notes(&[])
-            .expect("constitution inference should run");
-        let items = store
-            .list_constitution_items()
-            .expect("constitution should list");
-        let item = items
-            .iter()
-            .find(|item| item.claim.contains("concrete implementation details"))
-            .expect("behavior-derived constitution item should exist");
-
-        assert_eq!(summary.scanned_behavior_events, 3);
-        assert_eq!(summary.auto_active_items, 1);
-        assert_eq!(item.status, ConstitutionStatus::Active);
-        assert_eq!(item.source.as_deref(), Some("behavior_inference"));
-        assert!(item
-            .evidence_refs
-            .iter()
-            .all(|evidence| evidence.source_type.as_deref() == Some("behavior")));
-    }
-
-    #[test]
-    fn interviewee_answers_become_research_findings_not_personal_constitution() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-        let notes = vec![test_note(
-            "interview-1",
-            "Interview: onboarding",
-            "### Message 1: User\n\nHow do you decide whether an AI workflow is useful?\n\n### Message 2: Interviewee\n\nI need to see a working demo before I trust the system.\n\n### Message 3: User\n\nCan you give a concrete example and compare it with your current workflow?",
-            Some("interview"),
-        )];
-
-        let summary = store
-            .run_constitution_inference_with_notes(&notes)
-            .expect("constitution inference should run");
-        let items = store
-            .list_constitution_items()
-            .expect("constitution should list");
-        let records = store.list_user_records().expect("records should list");
-
-        assert_eq!(summary.scanned_interviews, 1);
-        assert_eq!(summary.extracted_research_findings, 1);
-        assert!(items
-            .iter()
-            .any(|item| item.claim.contains("concrete examples")));
-        assert!(!items
-            .iter()
-            .any(|item| item.claim.contains("working demo before I trust")));
-        assert!(records.iter().any(|record| {
-            record.kind == UserRecordKind::Fact
-                && record.content.contains("working demo before I trust")
-                && record.metadata.get("source_type").and_then(Value::as_str)
-                    == Some("interview_answer")
-        }));
-    }
-
-    #[test]
-    fn unlabeled_interview_notes_import_but_do_not_extract() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-        let notes = vec![test_note(
-            "interview-2",
-            "Unlabeled interview",
-            "How do you decide whether an AI workflow is useful?\nI need a working demo.",
-            Some("interview"),
-        )];
-
-        let summary = store
-            .run_constitution_inference_with_notes(&notes)
-            .expect("constitution inference should run");
-
-        assert_eq!(summary.scanned_interviews, 1);
-        assert_eq!(summary.extracted_research_findings, 0);
-        assert_eq!(summary.skipped_domain_claims, 1);
-        assert!(store
-            .list_constitution_items()
-            .expect("constitution should list")
-            .is_empty());
-    }
-
-    #[test]
-    fn constitution_inference_prunes_stale_vault_derived_items_and_records() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        store
-            .create_constitution_item(ConstitutionItemCreate {
-                claim: "Old note-backed claim".to_string(),
-                dimension: "reasoning".to_string(),
-                scope: vec!["note".to_string()],
-                priority: 0.58,
-                confidence: 0.58,
-                status: ConstitutionStatus::Candidate,
-                evidence_refs: vec![EvidenceRef {
-                    trace_id: "note-old-note".to_string(),
-                    event_id: "old-note".to_string(),
-                    session_id: "vault-note".to_string(),
-                    tile_id: None,
-                    model_id: None,
-                    note: Some("Old note".to_string()),
-                    source_type: Some("note".to_string()),
-                    source_id: Some("old-note".to_string()),
-                    source_label: Some("Vault note".to_string()),
-                    excerpt: Some("old evidence".to_string()),
-                    speaker_role: Some("user".to_string()),
-                }],
-                tensions: Vec::new(),
-                linked_record_ids: Vec::new(),
-                source: Some("note_inference".to_string()),
-            })
-            .expect("old constitution item should be created");
-        store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::Fact,
-                content: "Interview finding: old vault finding".to_string(),
-                origin: RecordOrigin::Inferred,
-                evidence_refs: Vec::new(),
-                confidence: 0.66,
-                promotion_state: Some(PromotionState::Candidate),
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::from([
-                    ("source_type".to_string(), json!("interview_answer")),
-                    ("source_note_id".to_string(), json!("old-note")),
-                ]),
-            })
-            .expect("old record should be created");
-        store
-            .create_constitution_item(ConstitutionItemCreate {
-                claim: "Old guided setup claim".to_string(),
-                dimension: "values".to_string(),
-                scope: vec!["setup".to_string()],
-                priority: 0.9,
-                confidence: 0.9,
-                status: ConstitutionStatus::Active,
-                evidence_refs: Vec::new(),
-                tensions: Vec::new(),
-                linked_record_ids: Vec::new(),
-                source: Some("guided_setup".to_string()),
-            })
-            .expect("old setup constitution item should be created");
-
-        let current_notes = vec![test_note(
-            "current-interview",
-            "Current interview",
-            "### Message 1: User\n\nCan you give a concrete example of how you make tradeoffs?\n\n### Message 2: Interviewee\n\nI compare impact and risk before deciding.",
-            Some("interview"),
-        )];
-        let summary = store
-            .run_constitution_inference_with_notes(&current_notes)
-            .expect("constitution inference should run");
-
-        assert_eq!(summary.pruned_stale_constitution_items, 2);
-        assert_eq!(summary.pruned_stale_records, 1);
-        assert!(store
-            .list_constitution_items()
-            .expect("constitution should list")
-            .iter()
-            .all(|item| !item.claim.contains("Old note-backed claim")
-                && !item.claim.contains("Old guided setup claim")));
-        assert!(store
-            .list_user_records()
-            .expect("records should list")
-            .iter()
-            .all(|record| !record.content.contains("old vault finding")));
-    }
-
-    #[test]
-    fn constitution_inference_rewrites_setup_from_current_interview_questions() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-        let notes = vec![test_note(
-            "interview-setup",
-            "Interview: strategy",
-            "### Message 1: User\n\nWhat are some personal values or cultural values that drive your decisions?\n\n### Message 2: Interviewee\n\nI want work to make something better and different.\n\n### Message 3: User\n\nCan you walk us through a concrete example and how you balance innovation and stability?",
-            Some("interview"),
-        )];
-
-        let summary = store
-            .run_constitution_inference_with_notes(&notes)
-            .expect("constitution inference should run");
-        let setup = store
-            .get_constitution_setup()
-            .expect("setup should load after inference");
-
-        assert!(summary.updated_setup_entries >= 4);
-        assert!(setup
-            .values
-            .iter()
-            .any(|entry| entry.contains("values and cultural assumptions")));
-        assert!(setup
-            .tastes
-            .iter()
-            .any(|entry| entry.contains("concrete walkthroughs")));
-        assert!(setup
-            .constraints
-            .iter()
-            .any(|entry| entry.contains("interviewee answers as research evidence")));
-        assert!(setup
-            .action_tendencies
-            .iter()
-            .any(|entry| entry.contains("follow-up questions")));
-    }
-
-    #[test]
-    fn constitution_setup_accepts_legacy_json_without_identity() {
-        let setup: ConstitutionSetup = serde_json::from_str(
-            r#"{
-                "values": ["evidence-backed work"],
-                "tastes": ["clean UX"],
-                "constraints": [],
-                "somatic_cues": [],
-                "action_tendencies": []
-            }"#,
-        )
-        .expect("legacy setup should parse");
-
-        assert_eq!(setup.twin_name, None);
-        assert_eq!(setup.twin_role, None);
-        assert!(setup.source_boundaries.is_empty());
-        assert_eq!(setup.values, vec!["evidence-backed work"]);
-    }
-
-    #[test]
-    fn save_constitution_setup_trims_identity_fields() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        let saved = store
-            .save_constitution_setup(ConstitutionSetup {
-                twin_name: Some("  Alex Chen  ".to_string()),
-                twin_role: Some("  founder deciding from product evidence  ".to_string()),
-                source_boundaries: vec![
-                    "  Use reviewed notes only.  ".to_string(),
-                    "".to_string(),
-                    " Uploaded interviews define domain context. ".to_string(),
-                ],
-                values: vec![" evidence-backed work ".to_string()],
-                ..ConstitutionSetup::default()
-            })
-            .expect("setup should save");
-
-        assert_eq!(saved.twin_name.as_deref(), Some("Alex Chen"));
-        assert_eq!(
-            saved.twin_role.as_deref(),
-            Some("founder deciding from product evidence")
-        );
-        assert_eq!(
-            saved.source_boundaries,
-            vec![
-                "Use reviewed notes only.".to_string(),
-                "Uploaded interviews define domain context.".to_string()
-            ]
-        );
-        assert_eq!(saved.values, vec!["evidence-backed work"]);
-    }
-
-    #[test]
-    fn constitution_inference_preserves_configured_identity() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-        store
-            .save_constitution_setup(ConstitutionSetup {
-                twin_name: Some("Alex Chen".to_string()),
-                twin_role: Some("founder deciding from product evidence".to_string()),
-                source_boundaries: vec!["Use reviewed notes only.".to_string()],
-                values: vec!["evidence-backed work".to_string()],
-                ..ConstitutionSetup::default()
-            })
-            .expect("identity setup should save");
-
-        let notes = vec![test_note(
-            "interview-setup",
-            "Interview: strategy",
-            "### Message 1: User\n\nCan you walk us through a concrete example and how you balance innovation and stability?",
-            Some("interview"),
-        )];
-        store
-            .run_constitution_inference_with_notes(&notes)
-            .expect("constitution inference should run");
-        let setup = store
-            .get_constitution_setup()
-            .expect("setup should load after inference");
-
-        assert_eq!(setup.twin_name.as_deref(), Some("Alex Chen"));
-        assert_eq!(
-            setup.twin_role.as_deref(),
-            Some("founder deciding from product evidence")
-        );
-        assert_eq!(
-            setup.source_boundaries,
-            vec!["Use reviewed notes only.".to_string()]
-        );
-    }
-
     #[test]
     fn decision_episode_and_reflection_card_persist_with_scores() {
         let temp_dir = tempdir().expect("temp dir should be created");

From 55280166f713384de0a26116d4f8147704bffa18 Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 15:58:17 +0800
Subject: [PATCH 13/30] refactor: extract twin::decisions

Moves decision episodes (record/list/update_decision_outcome), sealed
twin predictions (attach_twin_prediction, mark_twin_prediction_failed,
parse_twin_prediction and its parsing helpers), reflection cards
(record_reflection_card, scoring), and the decision-mirror config into
services/twin/decisions.rs. The seal-integrity logic and its comment
block move verbatim -- attach_twin_prediction still refuses to overwrite
a sealed prediction or seal one after the outcome is recorded, and
list_decision_episodes_with_reflections still redacts an unrevealed
sealed prediction before it crosses IPC. `parse_twin_prediction` is
re-exported via `pub use decisions::parse_twin_prediction;` in mod.rs
so commands/canvas/context.rs's import path is unchanged. Verbatim
move; tests move with their code.
---
 .../src-tauri/src/services/twin/decisions.rs  | 1877 +++++++++++++++++
 frontend/src-tauri/src/services/twin/mod.rs   | 1840 +---------------
 2 files changed, 1886 insertions(+), 1831 deletions(-)
 create mode 100644 frontend/src-tauri/src/services/twin/decisions.rs

diff --git a/frontend/src-tauri/src/services/twin/decisions.rs b/frontend/src-tauri/src/services/twin/decisions.rs
new file mode 100644
index 0000000..d5b0437
--- /dev/null
+++ b/frontend/src-tauri/src/services/twin/decisions.rs
@@ -0,0 +1,1877 @@
+use crate::models::note::Note;
+use crate::models::twin::{
+    ActionGap, ActionGapCreate, ConstitutionInferenceSummary, ConstitutionItem,
+    ConstitutionItemCreate, ConstitutionItemUpdate, ConstitutionReviewRequest, ConstitutionSetup,
+    ConstitutionStatus, DecisionEpisode, DecisionEpisodeCreate, DecisionEpisodeWithReflections,
+    DecisionEvidencePacket, DecisionEvidenceSource, DecisionMirrorConfig,
+    DecisionMirrorConfigUpdate, DecisionMirrorWeights, DecisionOutcomeUpdate, EvidenceRef,
+    ExportBundle, ExportFileSummary, MemoryDigestAction, MemoryDigestItem,
+    MemoryDigestReviewRequest, MemoryDigestState, PromotionState, RecordOrigin, ReflectionCard,
+    ReflectionCardCreate, ReflectionScores, ResolvedEvidenceRef, SessionTrace, TraceEvent,
+    TraceEventType, TwinContextRecord, TwinExportRequest, TwinInferenceRunSummary, TwinPrediction,
+    TwinPredictionDraft, TwinReviewRecord, UserRecord, UserRecordCreate, UserRecordKind,
+    UserRecordUpdate,
+};
+#[cfg(test)]
+use crate::models::twin::{DecisionMirrorPreset, PrimitiveDecisionAssessment};
+use crate::services::atomic_io::write_atomic;
+use anyhow::{Context, Result};
+use chrono::Utc;
+use serde::de::DeserializeOwned;
+use serde::Serialize;
+use serde_json::{json, Value};
+use std::collections::hash_map::DefaultHasher;
+use std::collections::HashMap;
+use std::collections::HashSet;
+use std::hash::{Hash, Hasher};
+use std::path::{Path, PathBuf};
+use std::time::{SystemTime, UNIX_EPOCH};
+use walkdir::WalkDir;
+use super::TwinStore;
+use super::shared::{excerpt, extract_event_model_id, extract_event_tile_id, lexical_terms, load_or_quarantine, payload_string};
+
+fn clamp_decision_mirror_weights(mut weights: DecisionMirrorWeights) -> DecisionMirrorWeights {
+    weights.notes_weight = clamp_weight(weights.notes_weight);
+    weights.approved_records_weight = clamp_weight(weights.approved_records_weight);
+    weights.candidate_records_weight = clamp_weight(weights.candidate_records_weight);
+    weights.constitution_weight = clamp_weight(weights.constitution_weight);
+    weights.action_gaps_weight = clamp_weight(weights.action_gaps_weight);
+    weights.recency_weight = clamp_weight(weights.recency_weight);
+    weights.evidence_count_weight = clamp_weight(weights.evidence_count_weight);
+    weights.outcome_history_weight = clamp_weight(weights.outcome_history_weight);
+    weights.contradiction_weight = clamp_weight(weights.contradiction_weight);
+    weights.breadth_weight = clamp_weight(weights.breadth_weight);
+    weights.depth_weight = clamp_weight(weights.depth_weight);
+    weights.evidence_grounding_weight = clamp_weight(weights.evidence_grounding_weight);
+    weights.blind_spot_weight = clamp_weight(weights.blind_spot_weight);
+    weights.counter_position_weight = clamp_weight(weights.counter_position_weight);
+    weights.actionability_weight = clamp_weight(weights.actionability_weight);
+    weights.uncertainty_weight = clamp_weight(weights.uncertainty_weight);
+    weights.privacy_weight = clamp_weight(weights.privacy_weight);
+    weights.unsupported_penalty_weight = clamp_weight(weights.unsupported_penalty_weight);
+    weights
+}
+
+fn clamp_weight(weight: f32) -> f32 {
+    if weight.is_finite() {
+        weight.clamp(0.0, 3.0)
+    } else {
+        1.0
+    }
+}
+
+fn promotion_state_label(state: &PromotionState) -> &'static str {
+    match state {
+        PromotionState::Candidate => "Candidate",
+        PromotionState::AutoPromoted => "Auto-promoted",
+        PromotionState::Endorsed => "Endorsed",
+        PromotionState::Rejected => "Rejected",
+        PromotionState::Private => "Private",
+        PromotionState::NoTrain => "No-train",
+    }
+}
+
+fn score_reflection_card(
+    content: &str,
+    cited_note_ids: &[String],
+    cited_user_record_ids: &[String],
+    cited_constitution_item_ids: &[String],
+    cited_action_gap_ids: &[String],
+    config: &DecisionMirrorConfig,
+) -> ReflectionScores {
+    let lower = content.to_lowercase();
+    let section_checks: &[&[&str]] = &[
+        &["decision frame", "actual decision"],
+        &["reasoning pattern", "likely reasoning", "default pattern"],
+        &["evidence", "vault", "record"],
+        &["blind spot", "missing", "underweighting"],
+        &["counter-position", "counter position", "counterargument"],
+        &["recommendation", "would do next"],
+        &["confidence", "uncertain", "would change my mind"],
+        &["next action", "smallest", "follow-up"],
+    ];
+    let present_sections = section_checks
+        .iter()
+        .filter(|aliases| aliases.iter().any(|alias| lower.contains(alias)))
+        .count();
+    let breadth_score = present_sections as f32 / section_checks.len() as f32;
+
+    let word_count = content.split_whitespace().count() as f32;
+    let depth_score = ((word_count / 450.0).min(1.0) * 0.5)
+        + (phrase_score(
+            &lower,
+            &[
+                "because",
+                "tradeoff",
+                "evidence",
+                "alternative",
+                "would change",
+                "unsupported",
+            ],
+        ) * 0.5);
+
+    let evidence_grounding_score = if !cited_note_ids.is_empty()
+        || !cited_user_record_ids.is_empty()
+        || !cited_constitution_item_ids.is_empty()
+        || !cited_action_gap_ids.is_empty()
+    {
+        1.0
+    } else if lower.contains("evidence")
+        || lower.contains("note")
+        || lower.contains("record")
+        || lower.contains("based on")
+    {
+        0.5
+    } else {
+        0.0
+    };
+
+    let blind_spot_score = phrase_score(
+        &lower,
+        &[
+            "blind spot",
+            "missing",
+            "underweight",
+            "bias",
+            "avoid",
+            "overfit",
+        ],
+    );
+    let actionability_score = phrase_score(
+        &lower,
+        &["next action", "smallest", "experiment", "step", "by "],
+    );
+    let counterargument_score = phrase_score(
+        &lower,
+        &[
+            "counter",
+            "strongest argument",
+            "against",
+            "alternative frame",
+        ],
+    );
+    let uncertainty_score = phrase_score(
+        &lower,
+        &[
+            "hypothesis",
+            "may",
+            "seem",
+            "confidence",
+            "uncertain",
+            "would change",
+        ],
+    );
+    let privacy_score = 1.0;
+    let unsupported_claim_count = unsupported_self_claim_count(
+        &lower,
+        evidence_grounding_score,
+        cited_note_ids,
+        cited_user_record_ids,
+        cited_constitution_item_ids,
+        cited_action_gap_ids,
+    );
+    let (overall_score, weighted_breakdown) = weighted_reflection_score(
+        config,
+        &[
+            ("breadth", breadth_score),
+            ("depth", depth_score.min(1.0)),
+            ("evidence_grounding", evidence_grounding_score),
+            ("blind_spot", blind_spot_score),
+            ("counter_position", counterargument_score),
+            ("actionability", actionability_score),
+            ("uncertainty", uncertainty_score),
+            ("privacy", privacy_score),
+        ],
+        unsupported_claim_count,
+    );
+
+    ReflectionScores {
+        breadth_score,
+        depth_score: depth_score.min(1.0),
+        evidence_grounding_score,
+        blind_spot_score,
+        actionability_score,
+        counterargument_score,
+        uncertainty_score,
+        privacy_score,
+        unsupported_claim_count,
+        overall_score,
+        weighted_breakdown,
+    }
+}
+
+fn weighted_reflection_score(
+    config: &DecisionMirrorConfig,
+    scores: &[(&str, f32)],
+    unsupported_claim_count: u32,
+) -> (f32, HashMap<String, f32>) {
+    let weights = &config.weights;
+    let weight_for = |key: &str| match key {
+        "breadth" => weights.breadth_weight,
+        "depth" => weights.depth_weight,
+        "evidence_grounding" => weights.evidence_grounding_weight,
+        "blind_spot" => weights.blind_spot_weight,
+        "counter_position" => weights.counter_position_weight,
+        "actionability" => weights.actionability_weight,
+        "uncertainty" => weights.uncertainty_weight,
+        "privacy" => weights.privacy_weight,
+        _ => 1.0,
+    };
+
+    let mut weighted_breakdown = HashMap::new();
+    let mut weighted_sum = 0.0_f32;
+    let mut weight_sum = 0.0_f32;
+    for (key, score) in scores {
+        let weight = clamp_weight(weight_for(key));
+        let contribution = score.clamp(0.0, 1.0) * weight;
+        weighted_breakdown.insert((*key).to_string(), contribution);
+        weighted_sum += contribution;
+        weight_sum += weight;
+    }
+
+    let unsupported_penalty =
+        (unsupported_claim_count.min(5) as f32 / 5.0) * weights.unsupported_penalty_weight;
+    weighted_breakdown.insert("unsupported_penalty".to_string(), -unsupported_penalty);
+
+    if weight_sum <= 0.0 {
+        return (0.0, weighted_breakdown);
+    }
+
+    let overall = ((weighted_sum - unsupported_penalty) / weight_sum).clamp(0.0, 1.0);
+    (overall, weighted_breakdown)
+}
+
+fn phrase_score(content: &str, phrases: &[&str]) -> f32 {
+    let hits = phrases
+        .iter()
+        .filter(|phrase| content.contains(**phrase))
+        .count();
+    (hits as f32 / phrases.len().max(1) as f32).min(1.0)
+}
+
+fn unsupported_self_claim_count(
+    lower: &str,
+    evidence_grounding_score: f32,
+    cited_note_ids: &[String],
+    cited_user_record_ids: &[String],
+    cited_constitution_item_ids: &[String],
+    cited_action_gap_ids: &[String],
+) -> u32 {
+    let has_structural_evidence = !cited_note_ids.is_empty()
+        || !cited_user_record_ids.is_empty()
+        || !cited_constitution_item_ids.is_empty()
+        || !cited_action_gap_ids.is_empty()
+        || evidence_grounding_score >= 0.5;
+    if has_structural_evidence {
+        return 0;
+    }
+
+    [
+        "you seem",
+        "you may",
+        "you often",
+        "you tend",
+        "your likely",
+        "based on your",
+        "you prefer",
+        "you avoid",
+    ]
+    .iter()
+    .map(|needle| lower.matches(needle).count() as u32)
+    .sum()
+}
+
+const PREDICTION_OPTION_MAX_CHARS: usize = 500;
+
+const PREDICTION_RATIONALE_MAX_CHARS: usize = 2000;
+
+/// Normalize an option string for comparison: trim, strip wrapping quotes,
+/// lowercase, collapse whitespace. Label forms ("Option 2", "B") are handled
+/// separately by `match_option_index` so meaningful digits survive.
+pub fn normalize_option(text: &str) -> String {
+    text.trim()
+        .trim_matches(|c: char| c == '"' || c == '\'' || c == '`')
+        .to_lowercase()
+        .split_whitespace()
+        .collect::<Vec<_>>()
+        .join(" ")
+}
+
+fn truncate_chars(text: &str, max_chars: usize) -> String {
+    if text.chars().count() <= max_chars {
+        text.to_string()
+    } else {
+        text.chars().take(max_chars).collect()
+    }
+}
+
+fn match_option_index(text: &str, options: &[String]) -> Option<usize> {
+    let normalized = normalize_option(text);
+    if normalized.is_empty() {
+        return None;
+    }
+
+    // Label forms: "option 2" / "choice b" / bare "2" / bare "b".
+    let label = ["option", "choice"]
+        .iter()
+        .find_map(|prefix| normalized.strip_prefix(prefix))
+        .map(str::trim)
+        .unwrap_or(&normalized)
+        .trim_matches(|c: char| c == '.' || c == ')' || c == ':' || c.is_whitespace());
+    if label.len() == 1 {
+        if let Some(letter) = label.chars().next() {
+            if letter.is_ascii_lowercase() {
+                let index = (letter as usize) - ('a' as usize);
+                if index < options.len() {
+                    return Some(index);
+                }
+            }
+        }
+    }
+    // Bare number labels: humans count from 1.
+    if let Ok(number) = label.parse::<usize>() {
+        if (1..=options.len()).contains(&number) {
+            return Some(number - 1);
+        }
+    }
+
+    options
+        .iter()
+        .position(|option| normalize_option(option) == normalized)
+}
+
+fn sanitize_confidence(raw: Option<f64>) -> Option<f32> {
+    let value = raw?;
+    if !value.is_finite() {
+        return None;
+    }
+    let value = if value > 2.0 && value <= 100.0 {
+        // Percent-style answer ("73" meaning 73%).
+        value / 100.0
+    } else {
+        // Near-misses like 1.2 are over-confident, not percentages.
+        value
+    };
+    Some(value.clamp(0.0, 1.0) as f32)
+}
+
+/// Extract the first balanced `{...}` span from `raw`, for best-effort JSON parsing of
+/// model output. Returns `None` if there's no opening brace, no closing brace, or the
+/// closing brace appears before the opening one (e.g. truncated/malformed model output
+/// like `"Option A} — but {incomplete"`) — guarding this instead of blindly slicing
+/// `&raw[start..=end]` is what prevents a panic on malformed input.
+fn extract_json_slice(raw: &str) -> Option<&str> {
+    let start = raw.find('{')?;
+    let end = raw.rfind('}')?;
+    if start > end {
+        return None;
+    }
+    Some(&raw[start..=end])
+}
+
+/// Parse the raw model output of a sealed-prediction call into a draft.
+/// Fallback chain: fenced/embedded strict JSON -> normalized string match
+/// against `options` -> raw text (manual adjudication later).
+pub fn parse_twin_prediction(raw: &str, options: &[String]) -> TwinPredictionDraft {
+    #[derive(serde::Deserialize)]
+    struct ParsedPrediction {
+        predicted_option: Option<String>,
+        option_index: Option<Value>,
+        confidence: Option<f64>,
+        rationale: Option<String>,
+    }
+
+    let json_slice = extract_json_slice(raw);
+
+    if let Some(slice) = json_slice {
+        if let Ok(parsed) = serde_json::from_str::<ParsedPrediction>(slice) {
+            let text = parsed.predicted_option.unwrap_or_default();
+            let text_index = match_option_index(&text, options);
+            let field_index = parsed.option_index.as_ref().and_then(|value| match value {
+                Value::Number(number) => number.as_u64().map(|n| n as usize),
+                Value::String(text) => text.trim().parse::<usize>().ok(),
+                _ => None,
+            });
+            // The prompt displays a 1-based option list, so prefer the
+            // 1-based reading; tolerate 0-based answers, and let the option
+            // text disambiguate when both readings are valid.
+            let field_index = field_index.and_then(|index| {
+                let one_based = index.checked_sub(1).filter(|i| *i < options.len());
+                let zero_based = Some(index).filter(|i| *i < options.len());
+                match (one_based, zero_based) {
+                    (Some(ob), Some(zb)) => match text_index {
+                        Some(text_idx) if text_idx == zb => Some(zb),
+                        _ => Some(ob),
+                    },
+                    (Some(ob), None) => Some(ob),
+                    (None, Some(zb)) => Some(zb),
+                    (None, None) => None,
+                }
+            });
+            // The option text is what the model actually said; a conflicting
+            // numeric index loses.
+            let matched_option_index = match (text_index, field_index) {
+                (Some(text_idx), _) => Some(text_idx),
+                (None, Some(field_idx)) if text.is_empty() => Some(field_idx),
+                _ => None,
+            };
+            let predicted_option = if text.is_empty() {
+                matched_option_index
+                    .map(|index| options[index].clone())
+                    .unwrap_or_else(|| truncate_chars(raw.trim(), PREDICTION_OPTION_MAX_CHARS))
+            } else {
+                truncate_chars(&text, PREDICTION_OPTION_MAX_CHARS)
+            };
+            return TwinPredictionDraft {
+                predicted_option,
+                matched_option_index,
+                confidence: sanitize_confidence(parsed.confidence),
+                rationale: parsed
+                    .rationale
+                    .map(|text| truncate_chars(&text, PREDICTION_RATIONALE_MAX_CHARS)),
+                parse_mode: "json".to_string(),
+            };
+        }
+    }
+
+    if let Some(index) = match_option_index(raw, options) {
+        return TwinPredictionDraft {
+            predicted_option: options[index].clone(),
+            matched_option_index: Some(index),
+            confidence: None,
+            rationale: None,
+            parse_mode: "string_match".to_string(),
+        };
+    }
+
+    TwinPredictionDraft {
+        predicted_option: truncate_chars(raw.trim(), PREDICTION_OPTION_MAX_CHARS),
+        matched_option_index: None,
+        confidence: None,
+        rationale: None,
+        parse_mode: "raw".to_string(),
+    }
+}
+
+fn compute_agreement(prediction: &TwinPrediction, chosen: &str, options: &[String]) -> bool {
+    let chosen_index = match_option_index(chosen, options);
+    match (prediction.matched_option_index, chosen_index) {
+        (Some(predicted), Some(chosen)) => predicted == chosen,
+        _ => normalize_option(&prediction.predicted_option) == normalize_option(chosen),
+    }
+}
+
+fn decision_case_relevance(episode: &DecisionEpisode, query_terms: &HashSet<String>) -> usize {
+    if query_terms.is_empty() {
+        return 0;
+    }
+
+    let mut haystack = episode.decision.clone();
+    haystack.push(' ');
+    haystack.push_str(&episode.options.join(" "));
+    for text in [
+        episode.chosen_option.as_deref(),
+        episode.initial_leaning.as_deref(),
+        episode.lesson.as_deref(),
+        episode.outcome.as_deref(),
+        episode.correction_note.as_deref(),
+    ]
+    .into_iter()
+    .flatten()
+    {
+        haystack.push(' ');
+        haystack.push_str(text);
+    }
+
+    let episode_terms = lexical_terms(&haystack);
+    query_terms.intersection(&episode_terms).count()
+}
+
+
+impl TwinStore {
+    pub fn get_decision_mirror_config(&self) -> Result<DecisionMirrorConfig> {
+        if !self.decision_mirror_config_path.exists() {
+            return Ok(DecisionMirrorConfig::default());
+        }
+
+        let content =
+            std::fs::read_to_string(&self.decision_mirror_config_path).with_context(|| {
+                format!(
+                    "Failed to read decision mirror config {}",
+                    self.decision_mirror_config_path.display()
+                )
+            })?;
+        let mut config: DecisionMirrorConfig =
+            serde_json::from_str(&content).context("Failed to parse decision mirror config")?;
+        config.weights = clamp_decision_mirror_weights(config.weights);
+        Ok(config)
+    }
+
+    pub fn update_decision_mirror_config(
+        &self,
+        update: DecisionMirrorConfigUpdate,
+    ) -> Result<DecisionMirrorConfig> {
+        let mut config = self.get_decision_mirror_config()?;
+        if let Some(preset) = update.preset {
+            config.weights = DecisionMirrorWeights::for_preset(&preset);
+            config.preset = preset;
+        }
+        if let Some(weights) = update.weights {
+            config.weights = clamp_decision_mirror_weights(weights);
+        }
+        if let Some(advanced_enabled) = update.advanced_enabled {
+            config.advanced_enabled = advanced_enabled;
+        }
+
+        self.write_decision_mirror_config_file(&config)?;
+        Ok(config)
+    }
+
+    pub fn reset_decision_mirror_config(&self) -> Result<DecisionMirrorConfig> {
+        let config = DecisionMirrorConfig::default();
+        self.write_decision_mirror_config_file(&config)?;
+        Ok(config)
+    }
+
+    pub fn record_decision_episode(
+        &mut self,
+        create: DecisionEpisodeCreate,
+    ) -> Result<DecisionEpisode> {
+        Self::validate_file_id(&create.id)?;
+        Self::validate_file_id(&create.session_id)?;
+        Self::validate_file_id(&create.tile_id)?;
+
+        let now = Utc::now();
+        // A prediction is only attempted when there are at least two options
+        // to choose between; record why one will not arrive otherwise.
+        let prediction_status = if create.options.len() >= 2 {
+            Some("requested".to_string())
+        } else {
+            None
+        };
+        let episode = DecisionEpisode {
+            id: create.id,
+            session_id: create.session_id,
+            tile_id: create.tile_id,
+            decision: create.decision,
+            options: create.options,
+            stakes: create.stakes,
+            initial_leaning: create.initial_leaning,
+            selected_response: None,
+            chosen_option: None,
+            confidence: None,
+            review_date: create.review_date,
+            outcome: None,
+            regret_score: None,
+            lesson: None,
+            missed_something: None,
+            primitive_assessment: create.primitive_assessment,
+            twin_prediction: None,
+            prediction_status,
+            agreement: None,
+            correction_note: None,
+            context_version: create.context_version,
+            outcome_recorded_at: None,
+            created_at: now,
+            updated_at: now,
+        };
+
+        self.write_decision_file(&episode)?;
+        self.append_trace_event(
+            &episode.session_id,
+            TraceEventType::DecisionEpisodeCreated,
+            json!({
+                "decision_episode_id": episode.id,
+                "tile_id": episode.tile_id,
+                "decision": episode.decision,
+                "options": episode.options,
+                "stakes": episode.stakes,
+                "initial_leaning": episode.initial_leaning,
+                "review_date": episode.review_date,
+                "primitive_assessment": episode.primitive_assessment,
+            }),
+        )?;
+
+        Ok(episode)
+    }
+
+    pub fn list_decision_episodes(&self) -> Result<Vec<DecisionEpisode>> {
+        let mut episodes = Vec::new();
+        if !self.decisions_path.exists() {
+            return Ok(episodes);
+        }
+
+        for entry in WalkDir::new(&self.decisions_path)
+            .min_depth(1)
+            .max_depth(1)
+            .into_iter()
+            .filter_map(|entry| entry.ok())
+        {
+            let path = entry.path();
+            if path.extension().is_some_and(|ext| ext == "json") {
+                if let Some(episode) =
+                    load_or_quarantine::<DecisionEpisode>(path, "decision episode")
+                {
+                    episodes.push(episode);
+                }
+            }
+        }
+
+        episodes.sort_by(|a, b| b.updated_at.cmp(&a.updated_at));
+        Ok(episodes)
+    }
+
+    /// Select past decided episodes as verbatim behavioral cases for twin
+    /// context. Correction notes (recorded when a sealed prediction missed)
+    /// break ties between equally relevant cases but never outrank a more
+    /// relevant case.
+    pub fn select_decision_cases(
+        &self,
+        query: &str,
+        exclude_episode_id: Option<&str>,
+        max: usize,
+    ) -> Result<Vec<DecisionEpisode>> {
+        if max == 0 {
+            return Ok(Vec::new());
+        }
+
+        let query_terms = lexical_terms(query);
+        let mut scored = Vec::new();
+        let mut fallback = Vec::new();
+
+        for episode in self.list_decision_episodes()? {
+            if episode.chosen_option.is_none() {
+                continue;
+            }
+            if exclude_episode_id.is_some_and(|id| id == episode.id) {
+                continue;
+            }
+            let score = decision_case_relevance(&episode, &query_terms);
+            if score > 0 {
+                scored.push((score, episode));
+            } else {
+                fallback.push(episode);
+            }
+        }
+
+        if scored.is_empty() {
+            // No keyword overlap at all: include the most recent decided
+            // cases rather than an empty behavioral context.
+            fallback.sort_by(|a, b| b.updated_at.cmp(&a.updated_at));
+            fallback.truncate(max.min(2));
+            return Ok(fallback);
+        }
+
+        scored.sort_by(|a, b| {
+            b.0.cmp(&a.0)
+                .then_with(|| {
+                    b.1.correction_note
+                        .is_some()
+                        .cmp(&a.1.correction_note.is_some())
+                })
+                .then_with(|| b.1.updated_at.cmp(&a.1.updated_at))
+        });
+
+        Ok(scored
+            .into_iter()
+            .take(max)
+            .map(|(_, episode)| episode)
+            .collect())
+    }
+
+    pub fn update_decision_outcome(
+        &mut self,
+        id: &str,
+        update: DecisionOutcomeUpdate,
+    ) -> Result<DecisionEpisode> {
+        Self::validate_file_id(id)?;
+        let path = self.decision_file_path(id);
+        let mut episode = self.read_decision_file(&path)?;
+
+        if let Some(selected_response) = update.selected_response {
+            episode.selected_response = Some(selected_response);
+        }
+        if let Some(chosen_option) = update.chosen_option {
+            // Canonicalize label/case variants ("b", "Option 2", extra
+            // whitespace) against the recorded options; unmatched free text
+            // is kept as-is (legacy and "other" outcomes stay recordable).
+            let canonical = match_option_index(&chosen_option, &episode.options)
+                .map(|index| episode.options[index].clone())
+                .unwrap_or(chosen_option);
+            episode.chosen_option = Some(canonical);
+        }
+        if let Some(confidence) = update.confidence {
+            episode.confidence = Some(confidence.clamp(0.0, 1.0));
+        }
+        if let Some(review_date) = update.review_date {
+            episode.review_date = Some(review_date);
+        }
+        if let Some(outcome) = update.outcome {
+            episode.outcome = Some(outcome);
+        }
+        if let Some(regret_score) = update.regret_score {
+            episode.regret_score = Some(regret_score.min(10));
+        }
+        if let Some(lesson) = update.lesson {
+            episode.lesson = Some(lesson);
+        }
+        if let Some(missed_something) = update.missed_something {
+            episode.missed_something = Some(missed_something);
+        }
+        if let Some(primitive_assessment) = update.primitive_assessment {
+            episode.primitive_assessment = primitive_assessment;
+        }
+        if let Some(correction_note) = update.correction_note {
+            episode.correction_note = Some(correction_note);
+        }
+
+        if episode.outcome_recorded_at.is_none()
+            && (episode.chosen_option.is_some() || episode.outcome.is_some())
+        {
+            episode.outcome_recorded_at = Some(Utc::now());
+        }
+
+        // Agreement is recomputed whenever both sides exist, so a corrected
+        // chosen_option keeps the stored agreement current. Only predictions
+        // sealed before the outcome was first recorded count.
+        if let (Some(chosen), Some(prediction)) = (&episode.chosen_option, &episode.twin_prediction)
+        {
+            let recorded_at = episode.outcome_recorded_at.unwrap_or_else(Utc::now);
+            if prediction.sealed_at <= recorded_at {
+                episode.agreement = Some(compute_agreement(prediction, chosen, &episode.options));
+            }
+        }
+
+        episode.updated_at = Utc::now();
+        self.write_decision_file(&episode)?;
+        self.append_trace_event(
+            &episode.session_id,
+            TraceEventType::OutcomeFollowUpRecorded,
+            json!({
+                "decision_episode_id": episode.id,
+                "tile_id": episode.tile_id,
+                "selected_response": episode.selected_response,
+                "chosen_option": episode.chosen_option,
+                "confidence": episode.confidence,
+                "review_date": episode.review_date,
+                "outcome": episode.outcome,
+                "regret_score": episode.regret_score,
+                "lesson": episode.lesson,
+                "missed_something": episode.missed_something,
+                "primitive_assessment": episode.primitive_assessment,
+                "agreement": episode.agreement,
+                "correction_note": episode.correction_note,
+                "prediction_context_version": episode
+                    .twin_prediction
+                    .as_ref()
+                    .map(|prediction| prediction.context_version.clone()),
+            }),
+        )?;
+
+        Ok(episode)
+    }
+
+    /// Seal a twin prediction onto an episode. Refuses (as a logged no-op
+    /// returning the unchanged episode) when the outcome is already recorded
+    /// or a prediction already exists, so `sealed_at` always precedes the
+    /// outcome structurally. The trace payload never contains the predicted
+    /// option — the trace viewer must not leak a sealed prediction.
+    pub fn attach_twin_prediction(
+        &mut self,
+        episode_id: &str,
+        draft: TwinPredictionDraft,
+        model_id: &str,
+        context_version: &str,
+    ) -> Result<DecisionEpisode> {
+        Self::validate_file_id(episode_id)?;
+        let path = self.decision_file_path(episode_id);
+        let mut episode = self.read_decision_file(&path)?;
+
+        if episode.chosen_option.is_some() {
+            log::warn!(
+                "Twin prediction for episode {} arrived after the outcome was recorded; discarding",
+                episode_id
+            );
+            episode.prediction_status = Some("outcome_recorded_first".to_string());
+            episode.updated_at = Utc::now();
+            self.write_decision_file(&episode)?;
+            return Ok(episode);
+        }
+        if episode.twin_prediction.is_some() {
+            log::warn!(
+                "Episode {} already has a sealed twin prediction; ignoring duplicate",
+                episode_id
+            );
+            return Ok(episode);
+        }
+
+        let prediction = TwinPrediction {
+            predicted_option: draft.predicted_option,
+            matched_option_index: draft.matched_option_index,
+            confidence: draft.confidence,
+            rationale: draft.rationale,
+            parse_mode: draft.parse_mode.clone(),
+            model_id: model_id.to_string(),
+            context_version: context_version.to_string(),
+            sealed_at: Utc::now(),
+        };
+        let sealed_at = prediction.sealed_at;
+        episode.twin_prediction = Some(prediction);
+        episode.prediction_status = Some("sealed".to_string());
+        episode.updated_at = Utc::now();
+        self.write_decision_file(&episode)?;
+
+        self.append_trace_event(
+            &episode.session_id,
+            TraceEventType::TwinPredictionSealed,
+            json!({
+                "decision_episode_id": episode.id,
+                "tile_id": episode.tile_id,
+                "model_id": model_id,
+                "context_version": context_version,
+                "parse_mode": draft.parse_mode,
+                "sealed_at": sealed_at,
+            }),
+        )?;
+
+        Ok(episode)
+    }
+
+    /// Record that the hidden prediction call failed, so exported episodes
+    /// distinguish "no prediction because the call failed" from "agreed to
+    /// not predict" — silent gaps would inflate measured accuracy.
+    pub fn mark_twin_prediction_failed(&mut self, episode_id: &str) -> Result<()> {
+        Self::validate_file_id(episode_id)?;
+        let path = self.decision_file_path(episode_id);
+        let mut episode = self.read_decision_file(&path)?;
+        if episode.twin_prediction.is_some() || episode.chosen_option.is_some() {
+            return Ok(());
+        }
+        episode.prediction_status = Some("failed".to_string());
+        episode.updated_at = Utc::now();
+        self.write_decision_file(&episode)
+    }
+
+    pub fn record_reflection_card(
+        &mut self,
+        create: ReflectionCardCreate,
+    ) -> Result<ReflectionCard> {
+        Self::validate_file_id(&create.decision_episode_id)?;
+        Self::validate_file_id(&create.session_id)?;
+        Self::validate_file_id(&create.tile_id)?;
+
+        let config = self.get_decision_mirror_config()?;
+        let mut evidence_packet = match create.evidence_packet.clone() {
+            Some(packet) => packet,
+            None => self.build_decision_evidence_packet(
+                &create.cited_note_ids,
+                &create.cited_user_record_ids,
+                &create.cited_constitution_item_ids,
+                &create.cited_action_gap_ids,
+                &config,
+            )?,
+        };
+        if evidence_packet.config_snapshot.is_none() {
+            evidence_packet.config_snapshot = Some(config.clone());
+        }
+        let scores = score_reflection_card(
+            &create.content,
+            &create.cited_note_ids,
+            &create.cited_user_record_ids,
+            &create.cited_constitution_item_ids,
+            &create.cited_action_gap_ids,
+            &config,
+        );
+        let card = ReflectionCard {
+            id: uuid::Uuid::new_v4().to_string(),
+            decision_episode_id: create.decision_episode_id,
+            session_id: create.session_id,
+            tile_id: create.tile_id,
+            model_id: create.model_id,
+            content: create.content,
+            cited_note_ids: create.cited_note_ids,
+            cited_user_record_ids: create.cited_user_record_ids,
+            cited_constitution_item_ids: create.cited_constitution_item_ids,
+            cited_action_gap_ids: create.cited_action_gap_ids,
+            scores,
+            evidence_packet,
+            created_at: Utc::now(),
+        };
+
+        self.write_reflection_file(&card)?;
+        self.append_trace_event(
+            &card.session_id,
+            TraceEventType::ReflectionCardRecorded,
+            json!({
+                "reflection_card_id": card.id,
+                "decision_episode_id": card.decision_episode_id,
+                "tile_id": card.tile_id,
+                "model_id": card.model_id,
+                "cited_note_ids": card.cited_note_ids,
+                "cited_user_record_ids": card.cited_user_record_ids,
+                "cited_constitution_item_ids": card.cited_constitution_item_ids,
+                "cited_action_gap_ids": card.cited_action_gap_ids,
+                "scores": card.scores,
+                "evidence_packet": card.evidence_packet,
+            }),
+        )?;
+
+        Ok(card)
+    }
+
+    fn build_decision_evidence_packet(
+        &mut self,
+        cited_note_ids: &[String],
+        cited_user_record_ids: &[String],
+        cited_constitution_item_ids: &[String],
+        cited_action_gap_ids: &[String],
+        config: &DecisionMirrorConfig,
+    ) -> Result<DecisionEvidencePacket> {
+        self.ensure_record_cache()?;
+        let weights = &config.weights;
+        let mut selected_sources = Vec::new();
+
+        for id in cited_note_ids {
+            selected_sources.push(DecisionEvidenceSource {
+                source_type: "note".to_string(),
+                id: id.clone(),
+                label: format!("Note {}", id),
+                weight: weights.notes_weight,
+                reason: "Selected by vault retrieval for this decision".to_string(),
+            });
+        }
+
+        for id in cited_user_record_ids {
+            if let Ok(record) = self.get_user_record(id) {
+                let (source_type, weight) = match &record.promotion_state {
+                    PromotionState::Endorsed | PromotionState::AutoPromoted => {
+                        ("approved_record", weights.approved_records_weight)
+                    }
+                    PromotionState::Candidate => {
+                        ("candidate_record", weights.candidate_records_weight)
+                    }
+                    PromotionState::Rejected
+                    | PromotionState::Private
+                    | PromotionState::NoTrain => {
+                        continue;
+                    }
+                };
+                selected_sources.push(DecisionEvidenceSource {
+                    source_type: source_type.to_string(),
+                    id: record.id,
+                    label: excerpt(&record.content),
+                    weight,
+                    reason: format!(
+                        "{} user record selected for live twin context",
+                        promotion_state_label(&record.promotion_state)
+                    ),
+                });
+            }
+        }
+
+        for id in cited_constitution_item_ids {
+            let label = self
+                .read_constitution_file(&self.constitution_file_path(id))
+                .ok()
+                .map(|item| excerpt(&item.claim))
+                .unwrap_or_else(|| format!("Constitution {}", id));
+            selected_sources.push(DecisionEvidenceSource {
+                source_type: "constitution_item".to_string(),
+                id: id.clone(),
+                label,
+                weight: weights.constitution_weight,
+                reason: "Higher-order constitution item selected for decision framing".to_string(),
+            });
+        }
+
+        for id in cited_action_gap_ids {
+            let label = self
+                .read_action_gap_file(&self.action_gap_file_path(id))
+                .ok()
+                .map(|gap| excerpt(&gap.decision_risk))
+                .unwrap_or_else(|| format!("Action Gap {}", id));
+            selected_sources.push(DecisionEvidenceSource {
+                source_type: "action_gap".to_string(),
+                id: id.clone(),
+                label,
+                weight: weights.action_gaps_weight,
+                reason: "Action gap selected as decision risk context".to_string(),
+            });
+        }
+
+        let mut excluded_private_count = self
+            .record_cache
+            .values()
+            .filter(|record| record.promotion_state == PromotionState::Private)
+            .count();
+        let mut excluded_rejected_count = self
+            .record_cache
+            .values()
+            .filter(|record| record.promotion_state == PromotionState::Rejected)
+            .count();
+        let mut excluded_no_train_count = self
+            .record_cache
+            .values()
+            .filter(|record| record.promotion_state == PromotionState::NoTrain)
+            .count();
+
+        for item in self.list_constitution_items()? {
+            match item.status {
+                ConstitutionStatus::Private => excluded_private_count += 1,
+                ConstitutionStatus::Rejected | ConstitutionStatus::NotMe => {
+                    excluded_rejected_count += 1
+                }
+                ConstitutionStatus::NoTrain => excluded_no_train_count += 1,
+                ConstitutionStatus::Candidate
+                | ConstitutionStatus::Active
+                | ConstitutionStatus::Softened => {}
+            }
+        }
+        for gap in self.list_action_gaps()? {
+            match gap.status {
+                ConstitutionStatus::Private => excluded_private_count += 1,
+                ConstitutionStatus::Rejected | ConstitutionStatus::NotMe => {
+                    excluded_rejected_count += 1
+                }
+                ConstitutionStatus::NoTrain => excluded_no_train_count += 1,
+                ConstitutionStatus::Candidate
+                | ConstitutionStatus::Active
+                | ConstitutionStatus::Softened => {}
+            }
+        }
+
+        Ok(DecisionEvidencePacket {
+            selected_sources,
+            excluded_private_count,
+            excluded_rejected_count,
+            excluded_no_train_count,
+            created_at: Some(Utc::now()),
+            config_snapshot: Some(config.clone()),
+        })
+    }
+
+    pub fn list_decision_episodes_with_reflections(
+        &self,
+    ) -> Result<Vec<DecisionEpisodeWithReflections>> {
+        let cards = self.list_reflection_cards()?;
+        let mut cards_by_episode: HashMap<String, Vec<ReflectionCard>> = HashMap::new();
+        for card in cards {
+            cards_by_episode
+                .entry(card.decision_episode_id.clone())
+                .or_default()
+                .push(card);
+        }
+
+        let mut episodes = self
+            .list_decision_episodes()?
+            .into_iter()
+            .map(|mut episode| {
+                let mut reflection_cards = cards_by_episode.remove(&episode.id).unwrap_or_default();
+                reflection_cards.sort_by(|a, b| b.created_at.cmp(&a.created_at));
+                let feedback_events = self.decision_feedback_events(&episode).unwrap_or_default();
+                // A sealed prediction must never cross IPC before the outcome
+                // is recorded; the UI only learns that one exists.
+                let prediction_sealed =
+                    episode.twin_prediction.is_some() && episode.chosen_option.is_none();
+                if prediction_sealed {
+                    episode.twin_prediction = None;
+                }
+                DecisionEpisodeWithReflections {
+                    episode,
+                    reflection_cards,
+                    feedback_events,
+                    prediction_sealed,
+                }
+            })
+            .collect::<Vec<_>>();
+        episodes.sort_by(|a, b| b.episode.updated_at.cmp(&a.episode.updated_at));
+        Ok(episodes)
+    }
+
+    fn decision_file_path(&self, decision_id: &str) -> PathBuf {
+        self.decisions_path.join(format!("{}.json", decision_id))
+    }
+
+    fn reflection_file_path(&self, reflection_id: &str) -> PathBuf {
+        self.reflections_path
+            .join(format!("{}.json", reflection_id))
+    }
+
+    fn read_decision_file(&self, path: &Path) -> Result<DecisionEpisode> {
+        let content = std::fs::read_to_string(path)
+            .with_context(|| format!("Failed to read decision file: {}", path.display()))?;
+        serde_json::from_str(&content)
+            .with_context(|| format!("Failed to parse decision file: {}", path.display()))
+    }
+
+    fn write_decision_mirror_config_file(&self, config: &DecisionMirrorConfig) -> Result<()> {
+        self.write_pretty_json(&self.decision_mirror_config_path, config)
+    }
+
+    fn write_decision_file(&self, episode: &DecisionEpisode) -> Result<()> {
+        let path = self.decision_file_path(&episode.id);
+        self.write_pretty_json(&path, episode)
+    }
+
+    fn write_reflection_file(&self, card: &ReflectionCard) -> Result<()> {
+        let path = self.reflection_file_path(&card.id);
+        self.write_pretty_json(&path, card)
+    }
+
+    pub(super) fn list_reflection_cards(&self) -> Result<Vec<ReflectionCard>> {
+        let mut cards = Vec::new();
+        if !self.reflections_path.exists() {
+            return Ok(cards);
+        }
+
+        for entry in WalkDir::new(&self.reflections_path)
+            .min_depth(1)
+            .max_depth(1)
+            .into_iter()
+            .filter_map(|entry| entry.ok())
+        {
+            let path = entry.path();
+            if path.extension().is_some_and(|ext| ext == "json") {
+                if let Some(card) = load_or_quarantine::<ReflectionCard>(path, "reflection card") {
+                    cards.push(card);
+                }
+            }
+        }
+
+        cards.sort_by(|a, b| b.created_at.cmp(&a.created_at));
+        Ok(cards)
+    }
+
+    pub(super) fn decision_evidence_refs(&self, decision_id: &str) -> Result<Vec<EvidenceRef>> {
+        Self::validate_file_id(decision_id)?;
+        let mut refs = Vec::new();
+        for entry in WalkDir::new(&self.traces_path)
+            .min_depth(1)
+            .max_depth(1)
+            .into_iter()
+            .filter_map(|entry| entry.ok())
+        {
+            let path = entry.path();
+            if !path.extension().is_some_and(|ext| ext == "json") {
+                continue;
+            }
+            let Some(trace) = load_or_quarantine::<SessionTrace>(path, "trace") else {
+                // A corrupt trace only omits its own evidence refs; the
+                // decision's evidence from healthy traces is still collected.
+                continue;
+            };
+            for event in trace.events {
+                let event_decision_id =
+                    payload_string(&event.payload, &["decision_episode_id"]).unwrap_or_default();
+                if event_decision_id != decision_id {
+                    continue;
+                }
+                refs.push(EvidenceRef {
+                    trace_id: trace.id.clone(),
+                    event_id: event.id.clone(),
+                    session_id: trace.session_id.clone(),
+                    tile_id: extract_event_tile_id(&event.payload),
+                    model_id: extract_event_model_id(&event.payload),
+                    note: Some("Decision episode evidence".to_string()),
+                    source_type: Some("decision".to_string()),
+                    source_id: Some(decision_id.to_string()),
+                    source_label: Some("Decision episode evidence".to_string()),
+                    excerpt: None,
+                    speaker_role: None,
+                });
+            }
+        }
+        refs.sort_by(|a, b| a.event_id.cmp(&b.event_id));
+        Ok(refs)
+    }
+
+    fn decision_feedback_events(&self, episode: &DecisionEpisode) -> Result<Vec<TraceEvent>> {
+        Self::validate_file_id(&episode.session_id)?;
+        let path = self.trace_file_path(&episode.session_id);
+        if !path.exists() {
+            return Ok(Vec::new());
+        }
+
+        let trace = self.read_trace_file(&path)?;
+        let mut events = trace
+            .events
+            .into_iter()
+            .filter(|event| {
+                matches!(
+                    event.event_type,
+                    TraceEventType::FeedbackRecorded
+                        | TraceEventType::RankingRecorded
+                        | TraceEventType::InsightCaptured
+                )
+            })
+            .filter(|event| {
+                payload_string(&event.payload, &["decision_episode_id"])
+                    .is_some_and(|id| id == episode.id)
+                    || extract_event_tile_id(&event.payload)
+                        .is_some_and(|tile_id| tile_id == episode.tile_id)
+            })
+            .collect::<Vec<_>>();
+        events.sort_by(|a, b| b.created_at.cmp(&a.created_at));
+        Ok(events)
+    }
+
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::models::note::{Note, NoteStatus};
+    use crate::models::twin::{
+        default_record_confidence, PromotionState, RecordLink, RecordLinkType, UserRecordKind,
+    };
+    use tempfile::tempdir;
+
+    #[test]
+    fn decision_episode_and_reflection_card_persist_with_scores() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        let episode = store
+            .record_decision_episode(DecisionEpisodeCreate {
+                id: "decision-1".to_string(),
+                session_id: "session-1".to_string(),
+                tile_id: "tile-1".to_string(),
+                decision: "Should Grafyn build Decision Mirror first?".to_string(),
+                options: vec!["Decision Mirror".to_string(), "Topology".to_string()],
+                stakes: Some("Product direction".to_string()),
+                initial_leaning: Some("Decision Mirror".to_string()),
+                review_date: Some("2026-05-15".to_string()),
+                primitive_assessment: PrimitiveDecisionAssessment {
+                    stakes: Some("high".to_string()),
+                    reversibility: Some("medium".to_string()),
+                    time_horizon: Some("weeks".to_string()),
+                    uncertainty: Some("medium".to_string()),
+                    agency: Some("high".to_string()),
+                    value_tension: Some("ambition vs proof".to_string()),
+                    constraint_pressure: None,
+                    taste_aesthetic_pull: None,
+                    somatic_signal: None,
+                    action_gap_risk: None,
+                    outcome_feedback: None,
+                },
+                context_version: None,
+            })
+            .expect("decision episode should persist");
+
+        let card = store
+            .record_reflection_card(ReflectionCardCreate {
+                decision_episode_id: episode.id.clone(),
+                session_id: episode.session_id.clone(),
+                tile_id: episode.tile_id.clone(),
+                model_id: "openai/gpt-4".to_string(),
+                content: [
+                    "## Decision Frame",
+                    "You seem pulled toward ambitious topology.",
+                    "## Likely Reasoning Pattern",
+                    "You tend to prefer large architecture.",
+                    "## Recommendation",
+                    "Build the smaller proof first.",
+                ]
+                .join("\n"),
+                cited_note_ids: Vec::new(),
+                cited_user_record_ids: Vec::new(),
+                cited_constitution_item_ids: Vec::new(),
+                cited_action_gap_ids: Vec::new(),
+                evidence_packet: None,
+            })
+            .expect("reflection card should persist");
+
+        assert_eq!(card.decision_episode_id, "decision-1");
+        assert!(card.scores.unsupported_claim_count > 0);
+        assert!(card.scores.overall_score <= 1.0);
+        assert_eq!(card.evidence_packet.selected_sources.len(), 0);
+        assert_eq!(
+            card.evidence_packet
+                .config_snapshot
+                .as_ref()
+                .expect("config snapshot should persist")
+                .preset,
+            DecisionMirrorPreset::Balanced
+        );
+        store
+            .append_trace_event(
+                &episode.session_id,
+                TraceEventType::FeedbackRecorded,
+                json!({
+                    "feedback_type": "reject",
+                    "response": {
+                        "tile_id": episode.tile_id.clone(),
+                        "model_id": "openai/gpt-4",
+                    },
+                    "rationale": "Decision Mirror reflection marked Not Me",
+                }),
+            )
+            .expect("feedback event should persist");
+
+        let decision_rows = store
+            .list_decision_episodes_with_reflections()
+            .expect("decision rows should list with traces");
+        assert_eq!(decision_rows[0].reflection_cards.len(), 1);
+        assert_eq!(decision_rows[0].feedback_events.len(), 1);
+        assert_eq!(
+            decision_rows[0].feedback_events[0]
+                .payload
+                .get("feedback_type")
+                .and_then(|value| value.as_str()),
+            Some("reject")
+        );
+        let episodes = store
+            .list_decision_episodes()
+            .expect("episodes should list");
+        assert_eq!(episodes.len(), 1);
+
+        let legacy_card: ReflectionCard = serde_json::from_str(
+            r#"{
+                "id": "legacy-card",
+                "decision_episode_id": "decision-1",
+                "session_id": "session-1",
+                "tile_id": "tile-1",
+                "model_id": "openai/gpt-4",
+                "content": "legacy reflection",
+                "scores": { "overall_score": 0.5 },
+                "created_at": "2026-05-08T00:00:00Z"
+            }"#,
+        )
+        .expect("legacy reflection cards should deserialize");
+        assert!(legacy_card.evidence_packet.config_snapshot.is_none());
+    }
+
+    #[test]
+    fn decision_mirror_config_presets_persist() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        let default_config = store
+            .get_decision_mirror_config()
+            .expect("default config should load");
+        assert_eq!(default_config.preset, DecisionMirrorPreset::Balanced);
+
+        let updated = store
+            .update_decision_mirror_config(DecisionMirrorConfigUpdate {
+                preset: Some(DecisionMirrorPreset::EvidenceStrict),
+                weights: None,
+                advanced_enabled: Some(true),
+            })
+            .expect("config should update");
+        assert_eq!(updated.preset, DecisionMirrorPreset::EvidenceStrict);
+        assert!(
+            updated.weights.evidence_grounding_weight
+                > default_config.weights.evidence_grounding_weight
+        );
+
+        let persisted = store
+            .get_decision_mirror_config()
+            .expect("persisted config should load");
+        assert_eq!(persisted.preset, DecisionMirrorPreset::EvidenceStrict);
+
+        let reset = store
+            .reset_decision_mirror_config()
+            .expect("config should reset");
+        assert_eq!(reset.preset, DecisionMirrorPreset::Balanced);
+    }
+
+    #[test]
+    fn decision_episode_old_json_loads_with_default_prediction_fields() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        let old_json = r#"{
+            "id": "legacy-episode",
+            "session_id": "session-1",
+            "tile_id": "tile-1",
+            "decision": "Ship now or wait?",
+            "options": ["Ship now", "Wait"],
+            "chosen_option": "Ship now",
+            "created_at": "2026-01-01T00:00:00Z",
+            "updated_at": "2026-01-01T00:00:00Z"
+        }"#;
+        std::fs::create_dir_all(&store.decisions_path).expect("decisions dir");
+        std::fs::write(store.decisions_path.join("legacy-episode.json"), old_json)
+            .expect("legacy episode should write");
+
+        let episodes = store
+            .list_decision_episodes()
+            .expect("legacy episode should deserialize");
+        assert_eq!(episodes.len(), 1);
+        let episode = &episodes[0];
+        assert!(episode.twin_prediction.is_none());
+        assert!(episode.prediction_status.is_none());
+        assert!(episode.agreement.is_none());
+        assert!(episode.correction_note.is_none());
+        assert!(episode.context_version.is_none());
+        assert!(episode.outcome_recorded_at.is_none());
+    }
+
+    #[test]
+    fn sealed_prediction_redacted_from_reflections_until_outcome() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        let episode = store
+            .record_decision_episode(DecisionEpisodeCreate {
+                id: "decision-sealed".to_string(),
+                session_id: "session-1".to_string(),
+                tile_id: "tile-1".to_string(),
+                decision: "Take the Denver job?".to_string(),
+                options: vec!["Take it".to_string(), "Stay".to_string()],
+                stakes: None,
+                initial_leaning: None,
+                review_date: None,
+                primitive_assessment: PrimitiveDecisionAssessment::default(),
+                context_version: Some("ctx-test".to_string()),
+            })
+            .expect("decision episode should persist");
+        assert_eq!(episode.prediction_status.as_deref(), Some("requested"));
+
+        let mut sealed = episode.clone();
+        sealed.twin_prediction = Some(TwinPrediction {
+            predicted_option: "Stay".to_string(),
+            matched_option_index: Some(1),
+            confidence: Some(0.7),
+            rationale: Some("Family proximity outweighs salary here.".to_string()),
+            parse_mode: "json".to_string(),
+            model_id: "test/model".to_string(),
+            context_version: "ctx-test".to_string(),
+            sealed_at: Utc::now(),
+        });
+        sealed.prediction_status = Some("sealed".to_string());
+        store
+            .write_decision_file(&sealed)
+            .expect("sealed episode should write");
+
+        let listed = store
+            .list_decision_episodes_with_reflections()
+            .expect("episodes should list");
+        let item = listed
+            .iter()
+            .find(|item| item.episode.id == "decision-sealed")
+            .expect("episode should be listed");
+        assert!(item.prediction_sealed);
+        assert!(item.episode.twin_prediction.is_none());
+
+        store
+            .update_decision_outcome(
+                "decision-sealed",
+                DecisionOutcomeUpdate {
+                    chosen_option: Some("Stay".to_string()),
+                    ..DecisionOutcomeUpdate::default()
+                },
+            )
+            .expect("outcome should record");
+
+        let listed = store
+            .list_decision_episodes_with_reflections()
+            .expect("episodes should list after outcome");
+        let item = listed
+            .iter()
+            .find(|item| item.episode.id == "decision-sealed")
+            .expect("episode should be listed after outcome");
+        assert!(!item.prediction_sealed);
+        let prediction = item
+            .episode
+            .twin_prediction
+            .as_ref()
+            .expect("prediction should be revealed after outcome");
+        assert_eq!(prediction.predicted_option, "Stay");
+    }
+
+    fn decided_episode(
+        store: &mut TwinStore,
+        id: &str,
+        decision: &str,
+        chosen: &str,
+        correction_note: Option<&str>,
+    ) -> DecisionEpisode {
+        let episode = store
+            .record_decision_episode(DecisionEpisodeCreate {
+                id: id.to_string(),
+                session_id: "session-1".to_string(),
+                tile_id: format!("tile-{id}"),
+                decision: decision.to_string(),
+                options: vec!["Option A".to_string(), "Option B".to_string()],
+                stakes: None,
+                initial_leaning: None,
+                review_date: None,
+                primitive_assessment: PrimitiveDecisionAssessment::default(),
+                context_version: None,
+            })
+            .expect("episode should persist");
+        let mut decided = episode.clone();
+        decided.chosen_option = Some(chosen.to_string());
+        decided.correction_note = correction_note.map(|note| note.to_string());
+        store
+            .write_decision_file(&decided)
+            .expect("decided episode should write");
+        decided
+    }
+
+    #[test]
+    fn decision_cases_rank_relevance_above_correction_notes() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        decided_episode(
+            &mut store,
+            "case-relevant",
+            "Accept the Denver relocation offer with higher salary?",
+            "Option B",
+            None,
+        );
+        decided_episode(
+            &mut store,
+            "case-correction",
+            "Buy the relocation boxes early?",
+            "Option A",
+            Some("Twin guessed wrong here"),
+        );
+        // Undecided episode must never appear as a case.
+        store
+            .record_decision_episode(DecisionEpisodeCreate {
+                id: "case-undecided".to_string(),
+                session_id: "session-1".to_string(),
+                tile_id: "tile-undecided".to_string(),
+                decision: "Relocation salary salary salary?".to_string(),
+                options: vec!["A".to_string(), "B".to_string()],
+                stakes: None,
+                initial_leaning: None,
+                review_date: None,
+                primitive_assessment: PrimitiveDecisionAssessment::default(),
+                context_version: None,
+            })
+            .expect("undecided episode should persist");
+
+        let cases = store
+            .select_decision_cases("Denver relocation salary decision", None, 5)
+            .expect("cases should select");
+        assert_eq!(cases.len(), 2);
+        // The strongly relevant case outranks the weakly relevant one even
+        // though the weak one carries a correction note.
+        assert_eq!(cases[0].id, "case-relevant");
+        assert_eq!(cases[1].id, "case-correction");
+        assert!(cases.iter().all(|case| case.id != "case-undecided"));
+
+        let excluded = store
+            .select_decision_cases(
+                "Denver relocation salary decision",
+                Some("case-relevant"),
+                5,
+            )
+            .expect("exclusion should apply");
+        assert!(excluded.iter().all(|case| case.id != "case-relevant"));
+
+        // Zero overlap: most recent decided cases, capped at two.
+        let recent = store
+            .select_decision_cases("zzz qqq xyzzy", None, 5)
+            .expect("fallback should select");
+        assert!(!recent.is_empty());
+        assert!(recent.len() <= 2);
+        assert!(recent.iter().all(|case| case.chosen_option.is_some()));
+    }
+
+    fn prediction_options() -> Vec<String> {
+        vec![
+            "Take the Denver job".to_string(),
+            "Stay in Austin".to_string(),
+        ]
+    }
+
+    #[test]
+    fn parse_twin_prediction_strict_json() {
+        let raw = r#"{"predicted_option": "Stay in Austin", "option_index": 2, "confidence": 0.8, "rationale": "Family proximity wins."}"#;
+        let draft = parse_twin_prediction(raw, &prediction_options());
+        assert_eq!(draft.parse_mode, "json");
+        assert_eq!(draft.matched_option_index, Some(1));
+        assert_eq!(draft.predicted_option, "Stay in Austin");
+        assert_eq!(draft.confidence, Some(0.8));
+        assert_eq!(draft.rationale.as_deref(), Some("Family proximity wins."));
+    }
+
+    #[test]
+    fn parse_twin_prediction_fenced_json_with_language_tag() {
+        let raw = "```json\n{\"predicted_option\": \"Take the Denver job\", \"option_index\": 1, \"confidence\": 0.6, \"rationale\": \"Growth.\"}\n```";
+        let draft = parse_twin_prediction(raw, &prediction_options());
+        assert_eq!(draft.parse_mode, "json");
+        assert_eq!(draft.matched_option_index, Some(0));
+    }
+
+    #[test]
+    fn parse_twin_prediction_index_as_string_and_one_based() {
+        let raw = r#"{"option_index": "1", "confidence": 0.5}"#;
+        let draft = parse_twin_prediction(raw, &prediction_options());
+        // 1-based reading preferred: "1" means the first listed option.
+        assert_eq!(draft.matched_option_index, Some(0));
+        assert_eq!(draft.predicted_option, "Take the Denver job");
+    }
+
+    #[test]
+    fn parse_twin_prediction_text_beats_conflicting_index() {
+        let raw = r#"{"predicted_option": "Stay in Austin", "option_index": 1, "confidence": 0.9}"#;
+        let draft = parse_twin_prediction(raw, &prediction_options());
+        // The option text is what the model said; the conflicting index loses.
+        assert_eq!(draft.matched_option_index, Some(1));
+    }
+
+    #[test]
+    fn parse_twin_prediction_out_of_range_index_with_valid_text() {
+        let raw = r#"{"predicted_option": "Stay in Austin", "option_index": 9}"#;
+        let draft = parse_twin_prediction(raw, &prediction_options());
+        assert_eq!(draft.matched_option_index, Some(1));
+    }
+
+    #[test]
+    fn parse_twin_prediction_bare_text_and_labels() {
+        let options = prediction_options();
+        let bare = parse_twin_prediction("  Stay in Austin\n", &options);
+        assert_eq!(bare.parse_mode, "string_match");
+        assert_eq!(bare.matched_option_index, Some(1));
+
+        let letter = parse_twin_prediction("B", &options);
+        assert_eq!(letter.matched_option_index, Some(1));
+
+        let labeled = parse_twin_prediction("Option 2", &options);
+        assert_eq!(labeled.matched_option_index, Some(1));
+    }
+
+    #[test]
+    fn parse_twin_prediction_garbage_falls_to_raw() {
+        let long_garbage = "I think there are many considerations here ".repeat(40);
+        let draft = parse_twin_prediction(&long_garbage, &prediction_options());
+        assert_eq!(draft.parse_mode, "raw");
+        assert!(draft.matched_option_index.is_none());
+        assert!(draft.predicted_option.chars().count() <= 500);
+    }
+
+    #[test]
+    fn parse_twin_prediction_reversed_braces_does_not_panic() {
+        // The closing brace appears BEFORE the opening one, so `raw.find('{')` finds a
+        // start index greater than `raw.rfind('}')`'s end index. Slicing `&raw[start..=end]`
+        // without checking `start <= end` panics — which previously crashed the spawned
+        // sealed-prediction task, silently skipping both `attach_twin_prediction` and
+        // `mark_twin_prediction_failed`.
+        let raw = "Option A} — but {incomplete";
+        let draft = parse_twin_prediction(raw, &prediction_options());
+        // No panic reaching here is the primary assertion. The malformed brace pair is
+        // simply not treated as JSON, so it falls through the same fallback chain as any
+        // other non-JSON text.
+        assert_ne!(draft.parse_mode, "json");
+    }
+
+    #[test]
+    fn extract_json_slice_rejects_reversed_braces() {
+        assert_eq!(extract_json_slice("Option A} — but {incomplete"), None);
+        assert_eq!(extract_json_slice("no braces here"), None);
+        assert_eq!(extract_json_slice("only open {"), None);
+        assert_eq!(extract_json_slice("only close }"), None);
+        assert_eq!(
+            extract_json_slice(r#"prefix {"a": 1} suffix"#),
+            Some(r#"{"a": 1}"#)
+        );
+    }
+
+    #[test]
+    fn parse_twin_prediction_sanitizes_confidence() {
+        let options = prediction_options();
+        let percent = parse_twin_prediction(
+            r#"{"predicted_option": "Stay in Austin", "confidence": 73}"#,
+            &options,
+        );
+        assert_eq!(percent.confidence, Some(0.73));
+
+        let overshoot = parse_twin_prediction(
+            r#"{"predicted_option": "Stay in Austin", "confidence": 1.2}"#,
+            &options,
+        );
+        assert_eq!(overshoot.confidence, Some(1.0));
+
+        let negative = parse_twin_prediction(
+            r#"{"predicted_option": "Stay in Austin", "confidence": -0.1}"#,
+            &options,
+        );
+        assert_eq!(negative.confidence, Some(0.0));
+
+        let null = parse_twin_prediction(
+            r#"{"predicted_option": "Stay in Austin", "confidence": null}"#,
+            &options,
+        );
+        assert!(null.confidence.is_none());
+    }
+
+    #[test]
+    fn attach_twin_prediction_refuses_after_outcome_and_duplicates() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        let episode = store
+            .record_decision_episode(DecisionEpisodeCreate {
+                id: "decision-attach".to_string(),
+                session_id: "session-1".to_string(),
+                tile_id: "tile-1".to_string(),
+                decision: "Take the Denver job?".to_string(),
+                options: prediction_options(),
+                stakes: None,
+                initial_leaning: None,
+                review_date: None,
+                primitive_assessment: PrimitiveDecisionAssessment::default(),
+                context_version: Some("ctx-test".to_string()),
+            })
+            .expect("episode should persist");
+
+        let draft = parse_twin_prediction("Stay in Austin", &prediction_options());
+        let sealed = store
+            .attach_twin_prediction(&episode.id, draft.clone(), "test/model", "ctx-test")
+            .expect("first attach should seal");
+        assert_eq!(sealed.prediction_status.as_deref(), Some("sealed"));
+        let first_sealed_at = sealed.twin_prediction.as_ref().unwrap().sealed_at;
+
+        // Duplicate attach is a no-op.
+        let duplicate = store
+            .attach_twin_prediction(&episode.id, draft.clone(), "other/model", "ctx-test")
+            .expect("duplicate attach should not error");
+        assert_eq!(
+            duplicate.twin_prediction.as_ref().unwrap().sealed_at,
+            first_sealed_at
+        );
+        assert_eq!(
+            duplicate.twin_prediction.as_ref().unwrap().model_id,
+            "test/model"
+        );
+
+        // Outcome-first race: attach after the choice is recorded.
+        let late_episode = store
+            .record_decision_episode(DecisionEpisodeCreate {
+                id: "decision-late".to_string(),
+                session_id: "session-1".to_string(),
+                tile_id: "tile-2".to_string(),
+                decision: "Take the Denver job?".to_string(),
+                options: prediction_options(),
+                stakes: None,
+                initial_leaning: None,
+                review_date: None,
+                primitive_assessment: PrimitiveDecisionAssessment::default(),
+                context_version: None,
+            })
+            .expect("episode should persist");
+        store
+            .update_decision_outcome(
+                &late_episode.id,
+                DecisionOutcomeUpdate {
+                    chosen_option: Some("Stay in Austin".to_string()),
+                    ..DecisionOutcomeUpdate::default()
+                },
+            )
+            .expect("outcome should record");
+        let refused = store
+            .attach_twin_prediction(&late_episode.id, draft, "test/model", "ctx-test")
+            .expect("late attach should not error");
+        assert!(refused.twin_prediction.is_none());
+        assert_eq!(
+            refused.prediction_status.as_deref(),
+            Some("outcome_recorded_first")
+        );
+    }
+
+    #[test]
+    fn outcome_computes_agreement_and_canonicalizes_choice() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        let episode = store
+            .record_decision_episode(DecisionEpisodeCreate {
+                id: "decision-agree".to_string(),
+                session_id: "session-1".to_string(),
+                tile_id: "tile-1".to_string(),
+                decision: "Take the Denver job?".to_string(),
+                options: prediction_options(),
+                stakes: None,
+                initial_leaning: None,
+                review_date: None,
+                primitive_assessment: PrimitiveDecisionAssessment::default(),
+                context_version: Some("ctx-test".to_string()),
+            })
+            .expect("episode should persist");
+        let draft = parse_twin_prediction("Stay in Austin", &prediction_options());
+        store
+            .attach_twin_prediction(&episode.id, draft, "test/model", "ctx-test")
+            .expect("prediction should seal");
+
+        // Label + case variant resolves to the canonical option text and
+        // agreement computes via index comparison.
+        let updated = store
+            .update_decision_outcome(
+                &episode.id,
+                DecisionOutcomeUpdate {
+                    chosen_option: Some("option 2".to_string()),
+                    correction_note: None,
+                    ..DecisionOutcomeUpdate::default()
+                },
+            )
+            .expect("outcome should record");
+        assert_eq!(updated.chosen_option.as_deref(), Some("Stay in Austin"));
+        assert_eq!(updated.agreement, Some(true));
+        assert!(updated.outcome_recorded_at.is_some());
+
+        // Editing the choice recomputes agreement and accepts a correction
+        // note; outcome_recorded_at is not reset.
+        let first_recorded_at = updated.outcome_recorded_at;
+        let edited = store
+            .update_decision_outcome(
+                &episode.id,
+                DecisionOutcomeUpdate {
+                    chosen_option: Some("  TAKE the denver JOB ".to_string()),
+                    correction_note: Some("Twin overweighted family proximity.".to_string()),
+                    ..DecisionOutcomeUpdate::default()
+                },
+            )
+            .expect("edited outcome should record");
+        assert_eq!(edited.chosen_option.as_deref(), Some("Take the Denver job"));
+        assert_eq!(edited.agreement, Some(false));
+        assert_eq!(
+            edited.correction_note.as_deref(),
+            Some("Twin overweighted family proximity.")
+        );
+        assert_eq!(edited.outcome_recorded_at, first_recorded_at);
+    }
+
+    #[test]
+    fn outcome_without_prediction_records_no_agreement_and_keeps_free_text() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        let episode = store
+            .record_decision_episode(DecisionEpisodeCreate {
+                id: "decision-free".to_string(),
+                session_id: "session-1".to_string(),
+                tile_id: "tile-1".to_string(),
+                decision: "Take the Denver job?".to_string(),
+                options: prediction_options(),
+                stakes: None,
+                initial_leaning: None,
+                review_date: None,
+                primitive_assessment: PrimitiveDecisionAssessment::default(),
+                context_version: None,
+            })
+            .expect("episode should persist");
+
+        let updated = store
+            .update_decision_outcome(
+                &episode.id,
+                DecisionOutcomeUpdate {
+                    chosen_option: Some("Negotiated a remote arrangement instead".to_string()),
+                    ..DecisionOutcomeUpdate::default()
+                },
+            )
+            .expect("outcome should record");
+        // Free text that matches no option is preserved verbatim.
+        assert_eq!(
+            updated.chosen_option.as_deref(),
+            Some("Negotiated a remote arrangement instead")
+        );
+        assert!(updated.agreement.is_none());
+    }
+
+}
diff --git a/frontend/src-tauri/src/services/twin/mod.rs b/frontend/src-tauri/src/services/twin/mod.rs
index 65e2d7e..504c4ba 100644
--- a/frontend/src-tauri/src/services/twin/mod.rs
+++ b/frontend/src-tauri/src/services/twin/mod.rs
@@ -32,8 +32,10 @@ mod shared;
 mod traces;
 mod records;
 mod constitution;
+mod decisions;
 
 use shared::*;
+pub use decisions::parse_twin_prediction;
 use constitution::normalize_key_text;
 
 const AUTO_PROMOTE_CONFIDENCE: f32 = 0.75;
@@ -49,463 +51,6 @@ enum ExportSplit {
     Holdout,
 }
 
-fn clamp_decision_mirror_weights(mut weights: DecisionMirrorWeights) -> DecisionMirrorWeights {
-    weights.notes_weight = clamp_weight(weights.notes_weight);
-    weights.approved_records_weight = clamp_weight(weights.approved_records_weight);
-    weights.candidate_records_weight = clamp_weight(weights.candidate_records_weight);
-    weights.constitution_weight = clamp_weight(weights.constitution_weight);
-    weights.action_gaps_weight = clamp_weight(weights.action_gaps_weight);
-    weights.recency_weight = clamp_weight(weights.recency_weight);
-    weights.evidence_count_weight = clamp_weight(weights.evidence_count_weight);
-    weights.outcome_history_weight = clamp_weight(weights.outcome_history_weight);
-    weights.contradiction_weight = clamp_weight(weights.contradiction_weight);
-    weights.breadth_weight = clamp_weight(weights.breadth_weight);
-    weights.depth_weight = clamp_weight(weights.depth_weight);
-    weights.evidence_grounding_weight = clamp_weight(weights.evidence_grounding_weight);
-    weights.blind_spot_weight = clamp_weight(weights.blind_spot_weight);
-    weights.counter_position_weight = clamp_weight(weights.counter_position_weight);
-    weights.actionability_weight = clamp_weight(weights.actionability_weight);
-    weights.uncertainty_weight = clamp_weight(weights.uncertainty_weight);
-    weights.privacy_weight = clamp_weight(weights.privacy_weight);
-    weights.unsupported_penalty_weight = clamp_weight(weights.unsupported_penalty_weight);
-    weights
-}
-
-fn clamp_weight(weight: f32) -> f32 {
-    if weight.is_finite() {
-        weight.clamp(0.0, 3.0)
-    } else {
-        1.0
-    }
-}
-
-fn promotion_state_label(state: &PromotionState) -> &'static str {
-    match state {
-        PromotionState::Candidate => "Candidate",
-        PromotionState::AutoPromoted => "Auto-promoted",
-        PromotionState::Endorsed => "Endorsed",
-        PromotionState::Rejected => "Rejected",
-        PromotionState::Private => "Private",
-        PromotionState::NoTrain => "No-train",
-    }
-}
-
-fn score_reflection_card(
-    content: &str,
-    cited_note_ids: &[String],
-    cited_user_record_ids: &[String],
-    cited_constitution_item_ids: &[String],
-    cited_action_gap_ids: &[String],
-    config: &DecisionMirrorConfig,
-) -> ReflectionScores {
-    let lower = content.to_lowercase();
-    let section_checks: &[&[&str]] = &[
-        &["decision frame", "actual decision"],
-        &["reasoning pattern", "likely reasoning", "default pattern"],
-        &["evidence", "vault", "record"],
-        &["blind spot", "missing", "underweighting"],
-        &["counter-position", "counter position", "counterargument"],
-        &["recommendation", "would do next"],
-        &["confidence", "uncertain", "would change my mind"],
-        &["next action", "smallest", "follow-up"],
-    ];
-    let present_sections = section_checks
-        .iter()
-        .filter(|aliases| aliases.iter().any(|alias| lower.contains(alias)))
-        .count();
-    let breadth_score = present_sections as f32 / section_checks.len() as f32;
-
-    let word_count = content.split_whitespace().count() as f32;
-    let depth_score = ((word_count / 450.0).min(1.0) * 0.5)
-        + (phrase_score(
-            &lower,
-            &[
-                "because",
-                "tradeoff",
-                "evidence",
-                "alternative",
-                "would change",
-                "unsupported",
-            ],
-        ) * 0.5);
-
-    let evidence_grounding_score = if !cited_note_ids.is_empty()
-        || !cited_user_record_ids.is_empty()
-        || !cited_constitution_item_ids.is_empty()
-        || !cited_action_gap_ids.is_empty()
-    {
-        1.0
-    } else if lower.contains("evidence")
-        || lower.contains("note")
-        || lower.contains("record")
-        || lower.contains("based on")
-    {
-        0.5
-    } else {
-        0.0
-    };
-
-    let blind_spot_score = phrase_score(
-        &lower,
-        &[
-            "blind spot",
-            "missing",
-            "underweight",
-            "bias",
-            "avoid",
-            "overfit",
-        ],
-    );
-    let actionability_score = phrase_score(
-        &lower,
-        &["next action", "smallest", "experiment", "step", "by "],
-    );
-    let counterargument_score = phrase_score(
-        &lower,
-        &[
-            "counter",
-            "strongest argument",
-            "against",
-            "alternative frame",
-        ],
-    );
-    let uncertainty_score = phrase_score(
-        &lower,
-        &[
-            "hypothesis",
-            "may",
-            "seem",
-            "confidence",
-            "uncertain",
-            "would change",
-        ],
-    );
-    let privacy_score = 1.0;
-    let unsupported_claim_count = unsupported_self_claim_count(
-        &lower,
-        evidence_grounding_score,
-        cited_note_ids,
-        cited_user_record_ids,
-        cited_constitution_item_ids,
-        cited_action_gap_ids,
-    );
-    let (overall_score, weighted_breakdown) = weighted_reflection_score(
-        config,
-        &[
-            ("breadth", breadth_score),
-            ("depth", depth_score.min(1.0)),
-            ("evidence_grounding", evidence_grounding_score),
-            ("blind_spot", blind_spot_score),
-            ("counter_position", counterargument_score),
-            ("actionability", actionability_score),
-            ("uncertainty", uncertainty_score),
-            ("privacy", privacy_score),
-        ],
-        unsupported_claim_count,
-    );
-
-    ReflectionScores {
-        breadth_score,
-        depth_score: depth_score.min(1.0),
-        evidence_grounding_score,
-        blind_spot_score,
-        actionability_score,
-        counterargument_score,
-        uncertainty_score,
-        privacy_score,
-        unsupported_claim_count,
-        overall_score,
-        weighted_breakdown,
-    }
-}
-
-fn weighted_reflection_score(
-    config: &DecisionMirrorConfig,
-    scores: &[(&str, f32)],
-    unsupported_claim_count: u32,
-) -> (f32, HashMap<String, f32>) {
-    let weights = &config.weights;
-    let weight_for = |key: &str| match key {
-        "breadth" => weights.breadth_weight,
-        "depth" => weights.depth_weight,
-        "evidence_grounding" => weights.evidence_grounding_weight,
-        "blind_spot" => weights.blind_spot_weight,
-        "counter_position" => weights.counter_position_weight,
-        "actionability" => weights.actionability_weight,
-        "uncertainty" => weights.uncertainty_weight,
-        "privacy" => weights.privacy_weight,
-        _ => 1.0,
-    };
-
-    let mut weighted_breakdown = HashMap::new();
-    let mut weighted_sum = 0.0_f32;
-    let mut weight_sum = 0.0_f32;
-    for (key, score) in scores {
-        let weight = clamp_weight(weight_for(key));
-        let contribution = score.clamp(0.0, 1.0) * weight;
-        weighted_breakdown.insert((*key).to_string(), contribution);
-        weighted_sum += contribution;
-        weight_sum += weight;
-    }
-
-    let unsupported_penalty =
-        (unsupported_claim_count.min(5) as f32 / 5.0) * weights.unsupported_penalty_weight;
-    weighted_breakdown.insert("unsupported_penalty".to_string(), -unsupported_penalty);
-
-    if weight_sum <= 0.0 {
-        return (0.0, weighted_breakdown);
-    }
-
-    let overall = ((weighted_sum - unsupported_penalty) / weight_sum).clamp(0.0, 1.0);
-    (overall, weighted_breakdown)
-}
-
-fn phrase_score(content: &str, phrases: &[&str]) -> f32 {
-    let hits = phrases
-        .iter()
-        .filter(|phrase| content.contains(**phrase))
-        .count();
-    (hits as f32 / phrases.len().max(1) as f32).min(1.0)
-}
-
-fn unsupported_self_claim_count(
-    lower: &str,
-    evidence_grounding_score: f32,
-    cited_note_ids: &[String],
-    cited_user_record_ids: &[String],
-    cited_constitution_item_ids: &[String],
-    cited_action_gap_ids: &[String],
-) -> u32 {
-    let has_structural_evidence = !cited_note_ids.is_empty()
-        || !cited_user_record_ids.is_empty()
-        || !cited_constitution_item_ids.is_empty()
-        || !cited_action_gap_ids.is_empty()
-        || evidence_grounding_score >= 0.5;
-    if has_structural_evidence {
-        return 0;
-    }
-
-    [
-        "you seem",
-        "you may",
-        "you often",
-        "you tend",
-        "your likely",
-        "based on your",
-        "you prefer",
-        "you avoid",
-    ]
-    .iter()
-    .map(|needle| lower.matches(needle).count() as u32)
-    .sum()
-}
-
-const PREDICTION_OPTION_MAX_CHARS: usize = 500;
-
-const PREDICTION_RATIONALE_MAX_CHARS: usize = 2000;
-
-/// Normalize an option string for comparison: trim, strip wrapping quotes,
-/// lowercase, collapse whitespace. Label forms ("Option 2", "B") are handled
-/// separately by `match_option_index` so meaningful digits survive.
-pub fn normalize_option(text: &str) -> String {
-    text.trim()
-        .trim_matches(|c: char| c == '"' || c == '\'' || c == '`')
-        .to_lowercase()
-        .split_whitespace()
-        .collect::<Vec<_>>()
-        .join(" ")
-}
-
-fn truncate_chars(text: &str, max_chars: usize) -> String {
-    if text.chars().count() <= max_chars {
-        text.to_string()
-    } else {
-        text.chars().take(max_chars).collect()
-    }
-}
-
-fn match_option_index(text: &str, options: &[String]) -> Option<usize> {
-    let normalized = normalize_option(text);
-    if normalized.is_empty() {
-        return None;
-    }
-
-    // Label forms: "option 2" / "choice b" / bare "2" / bare "b".
-    let label = ["option", "choice"]
-        .iter()
-        .find_map(|prefix| normalized.strip_prefix(prefix))
-        .map(str::trim)
-        .unwrap_or(&normalized)
-        .trim_matches(|c: char| c == '.' || c == ')' || c == ':' || c.is_whitespace());
-    if label.len() == 1 {
-        if let Some(letter) = label.chars().next() {
-            if letter.is_ascii_lowercase() {
-                let index = (letter as usize) - ('a' as usize);
-                if index < options.len() {
-                    return Some(index);
-                }
-            }
-        }
-    }
-    // Bare number labels: humans count from 1.
-    if let Ok(number) = label.parse::<usize>() {
-        if (1..=options.len()).contains(&number) {
-            return Some(number - 1);
-        }
-    }
-
-    options
-        .iter()
-        .position(|option| normalize_option(option) == normalized)
-}
-
-fn sanitize_confidence(raw: Option<f64>) -> Option<f32> {
-    let value = raw?;
-    if !value.is_finite() {
-        return None;
-    }
-    let value = if value > 2.0 && value <= 100.0 {
-        // Percent-style answer ("73" meaning 73%).
-        value / 100.0
-    } else {
-        // Near-misses like 1.2 are over-confident, not percentages.
-        value
-    };
-    Some(value.clamp(0.0, 1.0) as f32)
-}
-
-/// Extract the first balanced `{...}` span from `raw`, for best-effort JSON parsing of
-/// model output. Returns `None` if there's no opening brace, no closing brace, or the
-/// closing brace appears before the opening one (e.g. truncated/malformed model output
-/// like `"Option A} — but {incomplete"`) — guarding this instead of blindly slicing
-/// `&raw[start..=end]` is what prevents a panic on malformed input.
-fn extract_json_slice(raw: &str) -> Option<&str> {
-    let start = raw.find('{')?;
-    let end = raw.rfind('}')?;
-    if start > end {
-        return None;
-    }
-    Some(&raw[start..=end])
-}
-
-/// Parse the raw model output of a sealed-prediction call into a draft.
-/// Fallback chain: fenced/embedded strict JSON -> normalized string match
-/// against `options` -> raw text (manual adjudication later).
-pub fn parse_twin_prediction(raw: &str, options: &[String]) -> TwinPredictionDraft {
-    #[derive(serde::Deserialize)]
-    struct ParsedPrediction {
-        predicted_option: Option<String>,
-        option_index: Option<Value>,
-        confidence: Option<f64>,
-        rationale: Option<String>,
-    }
-
-    let json_slice = extract_json_slice(raw);
-
-    if let Some(slice) = json_slice {
-        if let Ok(parsed) = serde_json::from_str::<ParsedPrediction>(slice) {
-            let text = parsed.predicted_option.unwrap_or_default();
-            let text_index = match_option_index(&text, options);
-            let field_index = parsed.option_index.as_ref().and_then(|value| match value {
-                Value::Number(number) => number.as_u64().map(|n| n as usize),
-                Value::String(text) => text.trim().parse::<usize>().ok(),
-                _ => None,
-            });
-            // The prompt displays a 1-based option list, so prefer the
-            // 1-based reading; tolerate 0-based answers, and let the option
-            // text disambiguate when both readings are valid.
-            let field_index = field_index.and_then(|index| {
-                let one_based = index.checked_sub(1).filter(|i| *i < options.len());
-                let zero_based = Some(index).filter(|i| *i < options.len());
-                match (one_based, zero_based) {
-                    (Some(ob), Some(zb)) => match text_index {
-                        Some(text_idx) if text_idx == zb => Some(zb),
-                        _ => Some(ob),
-                    },
-                    (Some(ob), None) => Some(ob),
-                    (None, Some(zb)) => Some(zb),
-                    (None, None) => None,
-                }
-            });
-            // The option text is what the model actually said; a conflicting
-            // numeric index loses.
-            let matched_option_index = match (text_index, field_index) {
-                (Some(text_idx), _) => Some(text_idx),
-                (None, Some(field_idx)) if text.is_empty() => Some(field_idx),
-                _ => None,
-            };
-            let predicted_option = if text.is_empty() {
-                matched_option_index
-                    .map(|index| options[index].clone())
-                    .unwrap_or_else(|| truncate_chars(raw.trim(), PREDICTION_OPTION_MAX_CHARS))
-            } else {
-                truncate_chars(&text, PREDICTION_OPTION_MAX_CHARS)
-            };
-            return TwinPredictionDraft {
-                predicted_option,
-                matched_option_index,
-                confidence: sanitize_confidence(parsed.confidence),
-                rationale: parsed
-                    .rationale
-                    .map(|text| truncate_chars(&text, PREDICTION_RATIONALE_MAX_CHARS)),
-                parse_mode: "json".to_string(),
-            };
-        }
-    }
-
-    if let Some(index) = match_option_index(raw, options) {
-        return TwinPredictionDraft {
-            predicted_option: options[index].clone(),
-            matched_option_index: Some(index),
-            confidence: None,
-            rationale: None,
-            parse_mode: "string_match".to_string(),
-        };
-    }
-
-    TwinPredictionDraft {
-        predicted_option: truncate_chars(raw.trim(), PREDICTION_OPTION_MAX_CHARS),
-        matched_option_index: None,
-        confidence: None,
-        rationale: None,
-        parse_mode: "raw".to_string(),
-    }
-}
-
-fn compute_agreement(prediction: &TwinPrediction, chosen: &str, options: &[String]) -> bool {
-    let chosen_index = match_option_index(chosen, options);
-    match (prediction.matched_option_index, chosen_index) {
-        (Some(predicted), Some(chosen)) => predicted == chosen,
-        _ => normalize_option(&prediction.predicted_option) == normalize_option(chosen),
-    }
-}
-
-fn decision_case_relevance(episode: &DecisionEpisode, query_terms: &HashSet<String>) -> usize {
-    if query_terms.is_empty() {
-        return 0;
-    }
-
-    let mut haystack = episode.decision.clone();
-    haystack.push(' ');
-    haystack.push_str(&episode.options.join(" "));
-    for text in [
-        episode.chosen_option.as_deref(),
-        episode.initial_leaning.as_deref(),
-        episode.lesson.as_deref(),
-        episode.outcome.as_deref(),
-        episode.correction_note.as_deref(),
-    ]
-    .into_iter()
-    .flatten()
-    {
-        haystack.push(' ');
-        haystack.push_str(text);
-    }
-
-    let episode_terms = lexical_terms(&haystack);
-    query_terms.intersection(&episode_terms).count()
-}
-
 fn memory_digest_trigger(record: &UserRecord) -> Option<&'static str> {
     if record.kind == UserRecordKind::Fact {
         return None;
@@ -674,732 +219,6 @@ impl TwinStore {
         Ok(())
     }
 
-    pub fn get_decision_mirror_config(&self) -> Result<DecisionMirrorConfig> {
-        if !self.decision_mirror_config_path.exists() {
-            return Ok(DecisionMirrorConfig::default());
-        }
-
-        let content =
-            std::fs::read_to_string(&self.decision_mirror_config_path).with_context(|| {
-                format!(
-                    "Failed to read decision mirror config {}",
-                    self.decision_mirror_config_path.display()
-                )
-            })?;
-        let mut config: DecisionMirrorConfig =
-            serde_json::from_str(&content).context("Failed to parse decision mirror config")?;
-        config.weights = clamp_decision_mirror_weights(config.weights);
-        Ok(config)
-    }
-
-    pub fn update_decision_mirror_config(
-        &self,
-        update: DecisionMirrorConfigUpdate,
-    ) -> Result<DecisionMirrorConfig> {
-        let mut config = self.get_decision_mirror_config()?;
-        if let Some(preset) = update.preset {
-            config.weights = DecisionMirrorWeights::for_preset(&preset);
-            config.preset = preset;
-        }
-        if let Some(weights) = update.weights {
-            config.weights = clamp_decision_mirror_weights(weights);
-        }
-        if let Some(advanced_enabled) = update.advanced_enabled {
-            config.advanced_enabled = advanced_enabled;
-        }
-
-        self.write_decision_mirror_config_file(&config)?;
-        Ok(config)
-    }
-
-    pub fn reset_decision_mirror_config(&self) -> Result<DecisionMirrorConfig> {
-        let config = DecisionMirrorConfig::default();
-        self.write_decision_mirror_config_file(&config)?;
-        Ok(config)
-    }
-
-    pub fn record_decision_episode(
-        &mut self,
-        create: DecisionEpisodeCreate,
-    ) -> Result<DecisionEpisode> {
-        Self::validate_file_id(&create.id)?;
-        Self::validate_file_id(&create.session_id)?;
-        Self::validate_file_id(&create.tile_id)?;
-
-        let now = Utc::now();
-        // A prediction is only attempted when there are at least two options
-        // to choose between; record why one will not arrive otherwise.
-        let prediction_status = if create.options.len() >= 2 {
-            Some("requested".to_string())
-        } else {
-            None
-        };
-        let episode = DecisionEpisode {
-            id: create.id,
-            session_id: create.session_id,
-            tile_id: create.tile_id,
-            decision: create.decision,
-            options: create.options,
-            stakes: create.stakes,
-            initial_leaning: create.initial_leaning,
-            selected_response: None,
-            chosen_option: None,
-            confidence: None,
-            review_date: create.review_date,
-            outcome: None,
-            regret_score: None,
-            lesson: None,
-            missed_something: None,
-            primitive_assessment: create.primitive_assessment,
-            twin_prediction: None,
-            prediction_status,
-            agreement: None,
-            correction_note: None,
-            context_version: create.context_version,
-            outcome_recorded_at: None,
-            created_at: now,
-            updated_at: now,
-        };
-
-        self.write_decision_file(&episode)?;
-        self.append_trace_event(
-            &episode.session_id,
-            TraceEventType::DecisionEpisodeCreated,
-            json!({
-                "decision_episode_id": episode.id,
-                "tile_id": episode.tile_id,
-                "decision": episode.decision,
-                "options": episode.options,
-                "stakes": episode.stakes,
-                "initial_leaning": episode.initial_leaning,
-                "review_date": episode.review_date,
-                "primitive_assessment": episode.primitive_assessment,
-            }),
-        )?;
-
-        Ok(episode)
-    }
-
-    pub fn list_decision_episodes(&self) -> Result<Vec<DecisionEpisode>> {
-        let mut episodes = Vec::new();
-        if !self.decisions_path.exists() {
-            return Ok(episodes);
-        }
-
-        for entry in WalkDir::new(&self.decisions_path)
-            .min_depth(1)
-            .max_depth(1)
-            .into_iter()
-            .filter_map(|entry| entry.ok())
-        {
-            let path = entry.path();
-            if path.extension().is_some_and(|ext| ext == "json") {
-                if let Some(episode) =
-                    load_or_quarantine::<DecisionEpisode>(path, "decision episode")
-                {
-                    episodes.push(episode);
-                }
-            }
-        }
-
-        episodes.sort_by(|a, b| b.updated_at.cmp(&a.updated_at));
-        Ok(episodes)
-    }
-
-    /// Select past decided episodes as verbatim behavioral cases for twin
-    /// context. Correction notes (recorded when a sealed prediction missed)
-    /// break ties between equally relevant cases but never outrank a more
-    /// relevant case.
-    pub fn select_decision_cases(
-        &self,
-        query: &str,
-        exclude_episode_id: Option<&str>,
-        max: usize,
-    ) -> Result<Vec<DecisionEpisode>> {
-        if max == 0 {
-            return Ok(Vec::new());
-        }
-
-        let query_terms = lexical_terms(query);
-        let mut scored = Vec::new();
-        let mut fallback = Vec::new();
-
-        for episode in self.list_decision_episodes()? {
-            if episode.chosen_option.is_none() {
-                continue;
-            }
-            if exclude_episode_id.is_some_and(|id| id == episode.id) {
-                continue;
-            }
-            let score = decision_case_relevance(&episode, &query_terms);
-            if score > 0 {
-                scored.push((score, episode));
-            } else {
-                fallback.push(episode);
-            }
-        }
-
-        if scored.is_empty() {
-            // No keyword overlap at all: include the most recent decided
-            // cases rather than an empty behavioral context.
-            fallback.sort_by(|a, b| b.updated_at.cmp(&a.updated_at));
-            fallback.truncate(max.min(2));
-            return Ok(fallback);
-        }
-
-        scored.sort_by(|a, b| {
-            b.0.cmp(&a.0)
-                .then_with(|| {
-                    b.1.correction_note
-                        .is_some()
-                        .cmp(&a.1.correction_note.is_some())
-                })
-                .then_with(|| b.1.updated_at.cmp(&a.1.updated_at))
-        });
-
-        Ok(scored
-            .into_iter()
-            .take(max)
-            .map(|(_, episode)| episode)
-            .collect())
-    }
-
-    pub fn update_decision_outcome(
-        &mut self,
-        id: &str,
-        update: DecisionOutcomeUpdate,
-    ) -> Result<DecisionEpisode> {
-        Self::validate_file_id(id)?;
-        let path = self.decision_file_path(id);
-        let mut episode = self.read_decision_file(&path)?;
-
-        if let Some(selected_response) = update.selected_response {
-            episode.selected_response = Some(selected_response);
-        }
-        if let Some(chosen_option) = update.chosen_option {
-            // Canonicalize label/case variants ("b", "Option 2", extra
-            // whitespace) against the recorded options; unmatched free text
-            // is kept as-is (legacy and "other" outcomes stay recordable).
-            let canonical = match_option_index(&chosen_option, &episode.options)
-                .map(|index| episode.options[index].clone())
-                .unwrap_or(chosen_option);
-            episode.chosen_option = Some(canonical);
-        }
-        if let Some(confidence) = update.confidence {
-            episode.confidence = Some(confidence.clamp(0.0, 1.0));
-        }
-        if let Some(review_date) = update.review_date {
-            episode.review_date = Some(review_date);
-        }
-        if let Some(outcome) = update.outcome {
-            episode.outcome = Some(outcome);
-        }
-        if let Some(regret_score) = update.regret_score {
-            episode.regret_score = Some(regret_score.min(10));
-        }
-        if let Some(lesson) = update.lesson {
-            episode.lesson = Some(lesson);
-        }
-        if let Some(missed_something) = update.missed_something {
-            episode.missed_something = Some(missed_something);
-        }
-        if let Some(primitive_assessment) = update.primitive_assessment {
-            episode.primitive_assessment = primitive_assessment;
-        }
-        if let Some(correction_note) = update.correction_note {
-            episode.correction_note = Some(correction_note);
-        }
-
-        if episode.outcome_recorded_at.is_none()
-            && (episode.chosen_option.is_some() || episode.outcome.is_some())
-        {
-            episode.outcome_recorded_at = Some(Utc::now());
-        }
-
-        // Agreement is recomputed whenever both sides exist, so a corrected
-        // chosen_option keeps the stored agreement current. Only predictions
-        // sealed before the outcome was first recorded count.
-        if let (Some(chosen), Some(prediction)) = (&episode.chosen_option, &episode.twin_prediction)
-        {
-            let recorded_at = episode.outcome_recorded_at.unwrap_or_else(Utc::now);
-            if prediction.sealed_at <= recorded_at {
-                episode.agreement = Some(compute_agreement(prediction, chosen, &episode.options));
-            }
-        }
-
-        episode.updated_at = Utc::now();
-        self.write_decision_file(&episode)?;
-        self.append_trace_event(
-            &episode.session_id,
-            TraceEventType::OutcomeFollowUpRecorded,
-            json!({
-                "decision_episode_id": episode.id,
-                "tile_id": episode.tile_id,
-                "selected_response": episode.selected_response,
-                "chosen_option": episode.chosen_option,
-                "confidence": episode.confidence,
-                "review_date": episode.review_date,
-                "outcome": episode.outcome,
-                "regret_score": episode.regret_score,
-                "lesson": episode.lesson,
-                "missed_something": episode.missed_something,
-                "primitive_assessment": episode.primitive_assessment,
-                "agreement": episode.agreement,
-                "correction_note": episode.correction_note,
-                "prediction_context_version": episode
-                    .twin_prediction
-                    .as_ref()
-                    .map(|prediction| prediction.context_version.clone()),
-            }),
-        )?;
-
-        Ok(episode)
-    }
-
-    /// Seal a twin prediction onto an episode. Refuses (as a logged no-op
-    /// returning the unchanged episode) when the outcome is already recorded
-    /// or a prediction already exists, so `sealed_at` always precedes the
-    /// outcome structurally. The trace payload never contains the predicted
-    /// option — the trace viewer must not leak a sealed prediction.
-    pub fn attach_twin_prediction(
-        &mut self,
-        episode_id: &str,
-        draft: TwinPredictionDraft,
-        model_id: &str,
-        context_version: &str,
-    ) -> Result<DecisionEpisode> {
-        Self::validate_file_id(episode_id)?;
-        let path = self.decision_file_path(episode_id);
-        let mut episode = self.read_decision_file(&path)?;
-
-        if episode.chosen_option.is_some() {
-            log::warn!(
-                "Twin prediction for episode {} arrived after the outcome was recorded; discarding",
-                episode_id
-            );
-            episode.prediction_status = Some("outcome_recorded_first".to_string());
-            episode.updated_at = Utc::now();
-            self.write_decision_file(&episode)?;
-            return Ok(episode);
-        }
-        if episode.twin_prediction.is_some() {
-            log::warn!(
-                "Episode {} already has a sealed twin prediction; ignoring duplicate",
-                episode_id
-            );
-            return Ok(episode);
-        }
-
-        let prediction = TwinPrediction {
-            predicted_option: draft.predicted_option,
-            matched_option_index: draft.matched_option_index,
-            confidence: draft.confidence,
-            rationale: draft.rationale,
-            parse_mode: draft.parse_mode.clone(),
-            model_id: model_id.to_string(),
-            context_version: context_version.to_string(),
-            sealed_at: Utc::now(),
-        };
-        let sealed_at = prediction.sealed_at;
-        episode.twin_prediction = Some(prediction);
-        episode.prediction_status = Some("sealed".to_string());
-        episode.updated_at = Utc::now();
-        self.write_decision_file(&episode)?;
-
-        self.append_trace_event(
-            &episode.session_id,
-            TraceEventType::TwinPredictionSealed,
-            json!({
-                "decision_episode_id": episode.id,
-                "tile_id": episode.tile_id,
-                "model_id": model_id,
-                "context_version": context_version,
-                "parse_mode": draft.parse_mode,
-                "sealed_at": sealed_at,
-            }),
-        )?;
-
-        Ok(episode)
-    }
-
-    /// Record that the hidden prediction call failed, so exported episodes
-    /// distinguish "no prediction because the call failed" from "agreed to
-    /// not predict" — silent gaps would inflate measured accuracy.
-    pub fn mark_twin_prediction_failed(&mut self, episode_id: &str) -> Result<()> {
-        Self::validate_file_id(episode_id)?;
-        let path = self.decision_file_path(episode_id);
-        let mut episode = self.read_decision_file(&path)?;
-        if episode.twin_prediction.is_some() || episode.chosen_option.is_some() {
-            return Ok(());
-        }
-        episode.prediction_status = Some("failed".to_string());
-        episode.updated_at = Utc::now();
-        self.write_decision_file(&episode)
-    }
-
-    pub fn record_reflection_card(
-        &mut self,
-        create: ReflectionCardCreate,
-    ) -> Result<ReflectionCard> {
-        Self::validate_file_id(&create.decision_episode_id)?;
-        Self::validate_file_id(&create.session_id)?;
-        Self::validate_file_id(&create.tile_id)?;
-
-        let config = self.get_decision_mirror_config()?;
-        let mut evidence_packet = match create.evidence_packet.clone() {
-            Some(packet) => packet,
-            None => self.build_decision_evidence_packet(
-                &create.cited_note_ids,
-                &create.cited_user_record_ids,
-                &create.cited_constitution_item_ids,
-                &create.cited_action_gap_ids,
-                &config,
-            )?,
-        };
-        if evidence_packet.config_snapshot.is_none() {
-            evidence_packet.config_snapshot = Some(config.clone());
-        }
-        let scores = score_reflection_card(
-            &create.content,
-            &create.cited_note_ids,
-            &create.cited_user_record_ids,
-            &create.cited_constitution_item_ids,
-            &create.cited_action_gap_ids,
-            &config,
-        );
-        let card = ReflectionCard {
-            id: uuid::Uuid::new_v4().to_string(),
-            decision_episode_id: create.decision_episode_id,
-            session_id: create.session_id,
-            tile_id: create.tile_id,
-            model_id: create.model_id,
-            content: create.content,
-            cited_note_ids: create.cited_note_ids,
-            cited_user_record_ids: create.cited_user_record_ids,
-            cited_constitution_item_ids: create.cited_constitution_item_ids,
-            cited_action_gap_ids: create.cited_action_gap_ids,
-            scores,
-            evidence_packet,
-            created_at: Utc::now(),
-        };
-
-        self.write_reflection_file(&card)?;
-        self.append_trace_event(
-            &card.session_id,
-            TraceEventType::ReflectionCardRecorded,
-            json!({
-                "reflection_card_id": card.id,
-                "decision_episode_id": card.decision_episode_id,
-                "tile_id": card.tile_id,
-                "model_id": card.model_id,
-                "cited_note_ids": card.cited_note_ids,
-                "cited_user_record_ids": card.cited_user_record_ids,
-                "cited_constitution_item_ids": card.cited_constitution_item_ids,
-                "cited_action_gap_ids": card.cited_action_gap_ids,
-                "scores": card.scores,
-                "evidence_packet": card.evidence_packet,
-            }),
-        )?;
-
-        Ok(card)
-    }
-
-    fn build_decision_evidence_packet(
-        &mut self,
-        cited_note_ids: &[String],
-        cited_user_record_ids: &[String],
-        cited_constitution_item_ids: &[String],
-        cited_action_gap_ids: &[String],
-        config: &DecisionMirrorConfig,
-    ) -> Result<DecisionEvidencePacket> {
-        self.ensure_record_cache()?;
-        let weights = &config.weights;
-        let mut selected_sources = Vec::new();
-
-        for id in cited_note_ids {
-            selected_sources.push(DecisionEvidenceSource {
-                source_type: "note".to_string(),
-                id: id.clone(),
-                label: format!("Note {}", id),
-                weight: weights.notes_weight,
-                reason: "Selected by vault retrieval for this decision".to_string(),
-            });
-        }
-
-        for id in cited_user_record_ids {
-            if let Ok(record) = self.get_user_record(id) {
-                let (source_type, weight) = match &record.promotion_state {
-                    PromotionState::Endorsed | PromotionState::AutoPromoted => {
-                        ("approved_record", weights.approved_records_weight)
-                    }
-                    PromotionState::Candidate => {
-                        ("candidate_record", weights.candidate_records_weight)
-                    }
-                    PromotionState::Rejected
-                    | PromotionState::Private
-                    | PromotionState::NoTrain => {
-                        continue;
-                    }
-                };
-                selected_sources.push(DecisionEvidenceSource {
-                    source_type: source_type.to_string(),
-                    id: record.id,
-                    label: excerpt(&record.content),
-                    weight,
-                    reason: format!(
-                        "{} user record selected for live twin context",
-                        promotion_state_label(&record.promotion_state)
-                    ),
-                });
-            }
-        }
-
-        for id in cited_constitution_item_ids {
-            let label = self
-                .read_constitution_file(&self.constitution_file_path(id))
-                .ok()
-                .map(|item| excerpt(&item.claim))
-                .unwrap_or_else(|| format!("Constitution {}", id));
-            selected_sources.push(DecisionEvidenceSource {
-                source_type: "constitution_item".to_string(),
-                id: id.clone(),
-                label,
-                weight: weights.constitution_weight,
-                reason: "Higher-order constitution item selected for decision framing".to_string(),
-            });
-        }
-
-        for id in cited_action_gap_ids {
-            let label = self
-                .read_action_gap_file(&self.action_gap_file_path(id))
-                .ok()
-                .map(|gap| excerpt(&gap.decision_risk))
-                .unwrap_or_else(|| format!("Action Gap {}", id));
-            selected_sources.push(DecisionEvidenceSource {
-                source_type: "action_gap".to_string(),
-                id: id.clone(),
-                label,
-                weight: weights.action_gaps_weight,
-                reason: "Action gap selected as decision risk context".to_string(),
-            });
-        }
-
-        let mut excluded_private_count = self
-            .record_cache
-            .values()
-            .filter(|record| record.promotion_state == PromotionState::Private)
-            .count();
-        let mut excluded_rejected_count = self
-            .record_cache
-            .values()
-            .filter(|record| record.promotion_state == PromotionState::Rejected)
-            .count();
-        let mut excluded_no_train_count = self
-            .record_cache
-            .values()
-            .filter(|record| record.promotion_state == PromotionState::NoTrain)
-            .count();
-
-        for item in self.list_constitution_items()? {
-            match item.status {
-                ConstitutionStatus::Private => excluded_private_count += 1,
-                ConstitutionStatus::Rejected | ConstitutionStatus::NotMe => {
-                    excluded_rejected_count += 1
-                }
-                ConstitutionStatus::NoTrain => excluded_no_train_count += 1,
-                ConstitutionStatus::Candidate
-                | ConstitutionStatus::Active
-                | ConstitutionStatus::Softened => {}
-            }
-        }
-        for gap in self.list_action_gaps()? {
-            match gap.status {
-                ConstitutionStatus::Private => excluded_private_count += 1,
-                ConstitutionStatus::Rejected | ConstitutionStatus::NotMe => {
-                    excluded_rejected_count += 1
-                }
-                ConstitutionStatus::NoTrain => excluded_no_train_count += 1,
-                ConstitutionStatus::Candidate
-                | ConstitutionStatus::Active
-                | ConstitutionStatus::Softened => {}
-            }
-        }
-
-        Ok(DecisionEvidencePacket {
-            selected_sources,
-            excluded_private_count,
-            excluded_rejected_count,
-            excluded_no_train_count,
-            created_at: Some(Utc::now()),
-            config_snapshot: Some(config.clone()),
-        })
-    }
-
-    pub fn list_decision_episodes_with_reflections(
-        &self,
-    ) -> Result<Vec<DecisionEpisodeWithReflections>> {
-        let cards = self.list_reflection_cards()?;
-        let mut cards_by_episode: HashMap<String, Vec<ReflectionCard>> = HashMap::new();
-        for card in cards {
-            cards_by_episode
-                .entry(card.decision_episode_id.clone())
-                .or_default()
-                .push(card);
-        }
-
-        let mut episodes = self
-            .list_decision_episodes()?
-            .into_iter()
-            .map(|mut episode| {
-                let mut reflection_cards = cards_by_episode.remove(&episode.id).unwrap_or_default();
-                reflection_cards.sort_by(|a, b| b.created_at.cmp(&a.created_at));
-                let feedback_events = self.decision_feedback_events(&episode).unwrap_or_default();
-                // A sealed prediction must never cross IPC before the outcome
-                // is recorded; the UI only learns that one exists.
-                let prediction_sealed =
-                    episode.twin_prediction.is_some() && episode.chosen_option.is_none();
-                if prediction_sealed {
-                    episode.twin_prediction = None;
-                }
-                DecisionEpisodeWithReflections {
-                    episode,
-                    reflection_cards,
-                    feedback_events,
-                    prediction_sealed,
-                }
-            })
-            .collect::<Vec<_>>();
-        episodes.sort_by(|a, b| b.episode.updated_at.cmp(&a.episode.updated_at));
-        Ok(episodes)
-    }
-
-    fn decision_file_path(&self, decision_id: &str) -> PathBuf {
-        self.decisions_path.join(format!("{}.json", decision_id))
-    }
-
-    fn reflection_file_path(&self, reflection_id: &str) -> PathBuf {
-        self.reflections_path
-            .join(format!("{}.json", reflection_id))
-    }
-
-    fn read_decision_file(&self, path: &Path) -> Result<DecisionEpisode> {
-        let content = std::fs::read_to_string(path)
-            .with_context(|| format!("Failed to read decision file: {}", path.display()))?;
-        serde_json::from_str(&content)
-            .with_context(|| format!("Failed to parse decision file: {}", path.display()))
-    }
-
-    fn write_decision_mirror_config_file(&self, config: &DecisionMirrorConfig) -> Result<()> {
-        self.write_pretty_json(&self.decision_mirror_config_path, config)
-    }
-
-    fn write_decision_file(&self, episode: &DecisionEpisode) -> Result<()> {
-        let path = self.decision_file_path(&episode.id);
-        self.write_pretty_json(&path, episode)
-    }
-
-    fn write_reflection_file(&self, card: &ReflectionCard) -> Result<()> {
-        let path = self.reflection_file_path(&card.id);
-        self.write_pretty_json(&path, card)
-    }
-
-    pub(super) fn list_reflection_cards(&self) -> Result<Vec<ReflectionCard>> {
-        let mut cards = Vec::new();
-        if !self.reflections_path.exists() {
-            return Ok(cards);
-        }
-
-        for entry in WalkDir::new(&self.reflections_path)
-            .min_depth(1)
-            .max_depth(1)
-            .into_iter()
-            .filter_map(|entry| entry.ok())
-        {
-            let path = entry.path();
-            if path.extension().is_some_and(|ext| ext == "json") {
-                if let Some(card) = load_or_quarantine::<ReflectionCard>(path, "reflection card") {
-                    cards.push(card);
-                }
-            }
-        }
-
-        cards.sort_by(|a, b| b.created_at.cmp(&a.created_at));
-        Ok(cards)
-    }
-
-    pub(super) fn decision_evidence_refs(&self, decision_id: &str) -> Result<Vec<EvidenceRef>> {
-        Self::validate_file_id(decision_id)?;
-        let mut refs = Vec::new();
-        for entry in WalkDir::new(&self.traces_path)
-            .min_depth(1)
-            .max_depth(1)
-            .into_iter()
-            .filter_map(|entry| entry.ok())
-        {
-            let path = entry.path();
-            if !path.extension().is_some_and(|ext| ext == "json") {
-                continue;
-            }
-            let Some(trace) = load_or_quarantine::<SessionTrace>(path, "trace") else {
-                // A corrupt trace only omits its own evidence refs; the
-                // decision's evidence from healthy traces is still collected.
-                continue;
-            };
-            for event in trace.events {
-                let event_decision_id =
-                    payload_string(&event.payload, &["decision_episode_id"]).unwrap_or_default();
-                if event_decision_id != decision_id {
-                    continue;
-                }
-                refs.push(EvidenceRef {
-                    trace_id: trace.id.clone(),
-                    event_id: event.id.clone(),
-                    session_id: trace.session_id.clone(),
-                    tile_id: extract_event_tile_id(&event.payload),
-                    model_id: extract_event_model_id(&event.payload),
-                    note: Some("Decision episode evidence".to_string()),
-                    source_type: Some("decision".to_string()),
-                    source_id: Some(decision_id.to_string()),
-                    source_label: Some("Decision episode evidence".to_string()),
-                    excerpt: None,
-                    speaker_role: None,
-                });
-            }
-        }
-        refs.sort_by(|a, b| a.event_id.cmp(&b.event_id));
-        Ok(refs)
-    }
-
-    fn decision_feedback_events(&self, episode: &DecisionEpisode) -> Result<Vec<TraceEvent>> {
-        Self::validate_file_id(&episode.session_id)?;
-        let path = self.trace_file_path(&episode.session_id);
-        if !path.exists() {
-            return Ok(Vec::new());
-        }
-
-        let trace = self.read_trace_file(&path)?;
-        let mut events = trace
-            .events
-            .into_iter()
-            .filter(|event| {
-                matches!(
-                    event.event_type,
-                    TraceEventType::FeedbackRecorded
-                        | TraceEventType::RankingRecorded
-                        | TraceEventType::InsightCaptured
-                )
-            })
-            .filter(|event| {
-                payload_string(&event.payload, &["decision_episode_id"])
-                    .is_some_and(|id| id == episode.id)
-                    || extract_event_tile_id(&event.payload)
-                        .is_some_and(|tile_id| tile_id == episode.tile_id)
-            })
-            .collect::<Vec<_>>();
-        events.sort_by(|a, b| b.created_at.cmp(&a.created_at));
-        Ok(events)
-    }
-
     pub fn list_memory_digest(&mut self) -> Result<Vec<MemoryDigestItem>> {
         self.ensure_record_cache()?;
         let mut existing = self.read_memory_digest_file()?;
@@ -1951,654 +770,6 @@ mod tests {
     };
     use tempfile::tempdir;
 
-    #[test]
-    fn decision_episode_and_reflection_card_persist_with_scores() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        let episode = store
-            .record_decision_episode(DecisionEpisodeCreate {
-                id: "decision-1".to_string(),
-                session_id: "session-1".to_string(),
-                tile_id: "tile-1".to_string(),
-                decision: "Should Grafyn build Decision Mirror first?".to_string(),
-                options: vec!["Decision Mirror".to_string(), "Topology".to_string()],
-                stakes: Some("Product direction".to_string()),
-                initial_leaning: Some("Decision Mirror".to_string()),
-                review_date: Some("2026-05-15".to_string()),
-                primitive_assessment: PrimitiveDecisionAssessment {
-                    stakes: Some("high".to_string()),
-                    reversibility: Some("medium".to_string()),
-                    time_horizon: Some("weeks".to_string()),
-                    uncertainty: Some("medium".to_string()),
-                    agency: Some("high".to_string()),
-                    value_tension: Some("ambition vs proof".to_string()),
-                    constraint_pressure: None,
-                    taste_aesthetic_pull: None,
-                    somatic_signal: None,
-                    action_gap_risk: None,
-                    outcome_feedback: None,
-                },
-                context_version: None,
-            })
-            .expect("decision episode should persist");
-
-        let card = store
-            .record_reflection_card(ReflectionCardCreate {
-                decision_episode_id: episode.id.clone(),
-                session_id: episode.session_id.clone(),
-                tile_id: episode.tile_id.clone(),
-                model_id: "openai/gpt-4".to_string(),
-                content: [
-                    "## Decision Frame",
-                    "You seem pulled toward ambitious topology.",
-                    "## Likely Reasoning Pattern",
-                    "You tend to prefer large architecture.",
-                    "## Recommendation",
-                    "Build the smaller proof first.",
-                ]
-                .join("\n"),
-                cited_note_ids: Vec::new(),
-                cited_user_record_ids: Vec::new(),
-                cited_constitution_item_ids: Vec::new(),
-                cited_action_gap_ids: Vec::new(),
-                evidence_packet: None,
-            })
-            .expect("reflection card should persist");
-
-        assert_eq!(card.decision_episode_id, "decision-1");
-        assert!(card.scores.unsupported_claim_count > 0);
-        assert!(card.scores.overall_score <= 1.0);
-        assert_eq!(card.evidence_packet.selected_sources.len(), 0);
-        assert_eq!(
-            card.evidence_packet
-                .config_snapshot
-                .as_ref()
-                .expect("config snapshot should persist")
-                .preset,
-            DecisionMirrorPreset::Balanced
-        );
-        store
-            .append_trace_event(
-                &episode.session_id,
-                TraceEventType::FeedbackRecorded,
-                json!({
-                    "feedback_type": "reject",
-                    "response": {
-                        "tile_id": episode.tile_id.clone(),
-                        "model_id": "openai/gpt-4",
-                    },
-                    "rationale": "Decision Mirror reflection marked Not Me",
-                }),
-            )
-            .expect("feedback event should persist");
-
-        let decision_rows = store
-            .list_decision_episodes_with_reflections()
-            .expect("decision rows should list with traces");
-        assert_eq!(decision_rows[0].reflection_cards.len(), 1);
-        assert_eq!(decision_rows[0].feedback_events.len(), 1);
-        assert_eq!(
-            decision_rows[0].feedback_events[0]
-                .payload
-                .get("feedback_type")
-                .and_then(|value| value.as_str()),
-            Some("reject")
-        );
-        let episodes = store
-            .list_decision_episodes()
-            .expect("episodes should list");
-        assert_eq!(episodes.len(), 1);
-
-        let legacy_card: ReflectionCard = serde_json::from_str(
-            r#"{
-                "id": "legacy-card",
-                "decision_episode_id": "decision-1",
-                "session_id": "session-1",
-                "tile_id": "tile-1",
-                "model_id": "openai/gpt-4",
-                "content": "legacy reflection",
-                "scores": { "overall_score": 0.5 },
-                "created_at": "2026-05-08T00:00:00Z"
-            }"#,
-        )
-        .expect("legacy reflection cards should deserialize");
-        assert!(legacy_card.evidence_packet.config_snapshot.is_none());
-    }
-
-    #[test]
-    fn decision_mirror_config_presets_persist() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        let default_config = store
-            .get_decision_mirror_config()
-            .expect("default config should load");
-        assert_eq!(default_config.preset, DecisionMirrorPreset::Balanced);
-
-        let updated = store
-            .update_decision_mirror_config(DecisionMirrorConfigUpdate {
-                preset: Some(DecisionMirrorPreset::EvidenceStrict),
-                weights: None,
-                advanced_enabled: Some(true),
-            })
-            .expect("config should update");
-        assert_eq!(updated.preset, DecisionMirrorPreset::EvidenceStrict);
-        assert!(
-            updated.weights.evidence_grounding_weight
-                > default_config.weights.evidence_grounding_weight
-        );
-
-        let persisted = store
-            .get_decision_mirror_config()
-            .expect("persisted config should load");
-        assert_eq!(persisted.preset, DecisionMirrorPreset::EvidenceStrict);
-
-        let reset = store
-            .reset_decision_mirror_config()
-            .expect("config should reset");
-        assert_eq!(reset.preset, DecisionMirrorPreset::Balanced);
-    }
-
-    #[test]
-    fn decision_episode_old_json_loads_with_default_prediction_fields() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        let old_json = r#"{
-            "id": "legacy-episode",
-            "session_id": "session-1",
-            "tile_id": "tile-1",
-            "decision": "Ship now or wait?",
-            "options": ["Ship now", "Wait"],
-            "chosen_option": "Ship now",
-            "created_at": "2026-01-01T00:00:00Z",
-            "updated_at": "2026-01-01T00:00:00Z"
-        }"#;
-        std::fs::create_dir_all(&store.decisions_path).expect("decisions dir");
-        std::fs::write(store.decisions_path.join("legacy-episode.json"), old_json)
-            .expect("legacy episode should write");
-
-        let episodes = store
-            .list_decision_episodes()
-            .expect("legacy episode should deserialize");
-        assert_eq!(episodes.len(), 1);
-        let episode = &episodes[0];
-        assert!(episode.twin_prediction.is_none());
-        assert!(episode.prediction_status.is_none());
-        assert!(episode.agreement.is_none());
-        assert!(episode.correction_note.is_none());
-        assert!(episode.context_version.is_none());
-        assert!(episode.outcome_recorded_at.is_none());
-    }
-
-    #[test]
-    fn sealed_prediction_redacted_from_reflections_until_outcome() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        let episode = store
-            .record_decision_episode(DecisionEpisodeCreate {
-                id: "decision-sealed".to_string(),
-                session_id: "session-1".to_string(),
-                tile_id: "tile-1".to_string(),
-                decision: "Take the Denver job?".to_string(),
-                options: vec!["Take it".to_string(), "Stay".to_string()],
-                stakes: None,
-                initial_leaning: None,
-                review_date: None,
-                primitive_assessment: PrimitiveDecisionAssessment::default(),
-                context_version: Some("ctx-test".to_string()),
-            })
-            .expect("decision episode should persist");
-        assert_eq!(episode.prediction_status.as_deref(), Some("requested"));
-
-        let mut sealed = episode.clone();
-        sealed.twin_prediction = Some(TwinPrediction {
-            predicted_option: "Stay".to_string(),
-            matched_option_index: Some(1),
-            confidence: Some(0.7),
-            rationale: Some("Family proximity outweighs salary here.".to_string()),
-            parse_mode: "json".to_string(),
-            model_id: "test/model".to_string(),
-            context_version: "ctx-test".to_string(),
-            sealed_at: Utc::now(),
-        });
-        sealed.prediction_status = Some("sealed".to_string());
-        store
-            .write_decision_file(&sealed)
-            .expect("sealed episode should write");
-
-        let listed = store
-            .list_decision_episodes_with_reflections()
-            .expect("episodes should list");
-        let item = listed
-            .iter()
-            .find(|item| item.episode.id == "decision-sealed")
-            .expect("episode should be listed");
-        assert!(item.prediction_sealed);
-        assert!(item.episode.twin_prediction.is_none());
-
-        store
-            .update_decision_outcome(
-                "decision-sealed",
-                DecisionOutcomeUpdate {
-                    chosen_option: Some("Stay".to_string()),
-                    ..DecisionOutcomeUpdate::default()
-                },
-            )
-            .expect("outcome should record");
-
-        let listed = store
-            .list_decision_episodes_with_reflections()
-            .expect("episodes should list after outcome");
-        let item = listed
-            .iter()
-            .find(|item| item.episode.id == "decision-sealed")
-            .expect("episode should be listed after outcome");
-        assert!(!item.prediction_sealed);
-        let prediction = item
-            .episode
-            .twin_prediction
-            .as_ref()
-            .expect("prediction should be revealed after outcome");
-        assert_eq!(prediction.predicted_option, "Stay");
-    }
-
-    fn decided_episode(
-        store: &mut TwinStore,
-        id: &str,
-        decision: &str,
-        chosen: &str,
-        correction_note: Option<&str>,
-    ) -> DecisionEpisode {
-        let episode = store
-            .record_decision_episode(DecisionEpisodeCreate {
-                id: id.to_string(),
-                session_id: "session-1".to_string(),
-                tile_id: format!("tile-{id}"),
-                decision: decision.to_string(),
-                options: vec!["Option A".to_string(), "Option B".to_string()],
-                stakes: None,
-                initial_leaning: None,
-                review_date: None,
-                primitive_assessment: PrimitiveDecisionAssessment::default(),
-                context_version: None,
-            })
-            .expect("episode should persist");
-        let mut decided = episode.clone();
-        decided.chosen_option = Some(chosen.to_string());
-        decided.correction_note = correction_note.map(|note| note.to_string());
-        store
-            .write_decision_file(&decided)
-            .expect("decided episode should write");
-        decided
-    }
-
-    #[test]
-    fn decision_cases_rank_relevance_above_correction_notes() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        decided_episode(
-            &mut store,
-            "case-relevant",
-            "Accept the Denver relocation offer with higher salary?",
-            "Option B",
-            None,
-        );
-        decided_episode(
-            &mut store,
-            "case-correction",
-            "Buy the relocation boxes early?",
-            "Option A",
-            Some("Twin guessed wrong here"),
-        );
-        // Undecided episode must never appear as a case.
-        store
-            .record_decision_episode(DecisionEpisodeCreate {
-                id: "case-undecided".to_string(),
-                session_id: "session-1".to_string(),
-                tile_id: "tile-undecided".to_string(),
-                decision: "Relocation salary salary salary?".to_string(),
-                options: vec!["A".to_string(), "B".to_string()],
-                stakes: None,
-                initial_leaning: None,
-                review_date: None,
-                primitive_assessment: PrimitiveDecisionAssessment::default(),
-                context_version: None,
-            })
-            .expect("undecided episode should persist");
-
-        let cases = store
-            .select_decision_cases("Denver relocation salary decision", None, 5)
-            .expect("cases should select");
-        assert_eq!(cases.len(), 2);
-        // The strongly relevant case outranks the weakly relevant one even
-        // though the weak one carries a correction note.
-        assert_eq!(cases[0].id, "case-relevant");
-        assert_eq!(cases[1].id, "case-correction");
-        assert!(cases.iter().all(|case| case.id != "case-undecided"));
-
-        let excluded = store
-            .select_decision_cases(
-                "Denver relocation salary decision",
-                Some("case-relevant"),
-                5,
-            )
-            .expect("exclusion should apply");
-        assert!(excluded.iter().all(|case| case.id != "case-relevant"));
-
-        // Zero overlap: most recent decided cases, capped at two.
-        let recent = store
-            .select_decision_cases("zzz qqq xyzzy", None, 5)
-            .expect("fallback should select");
-        assert!(!recent.is_empty());
-        assert!(recent.len() <= 2);
-        assert!(recent.iter().all(|case| case.chosen_option.is_some()));
-    }
-
-    fn prediction_options() -> Vec<String> {
-        vec![
-            "Take the Denver job".to_string(),
-            "Stay in Austin".to_string(),
-        ]
-    }
-
-    #[test]
-    fn parse_twin_prediction_strict_json() {
-        let raw = r#"{"predicted_option": "Stay in Austin", "option_index": 2, "confidence": 0.8, "rationale": "Family proximity wins."}"#;
-        let draft = parse_twin_prediction(raw, &prediction_options());
-        assert_eq!(draft.parse_mode, "json");
-        assert_eq!(draft.matched_option_index, Some(1));
-        assert_eq!(draft.predicted_option, "Stay in Austin");
-        assert_eq!(draft.confidence, Some(0.8));
-        assert_eq!(draft.rationale.as_deref(), Some("Family proximity wins."));
-    }
-
-    #[test]
-    fn parse_twin_prediction_fenced_json_with_language_tag() {
-        let raw = "```json\n{\"predicted_option\": \"Take the Denver job\", \"option_index\": 1, \"confidence\": 0.6, \"rationale\": \"Growth.\"}\n```";
-        let draft = parse_twin_prediction(raw, &prediction_options());
-        assert_eq!(draft.parse_mode, "json");
-        assert_eq!(draft.matched_option_index, Some(0));
-    }
-
-    #[test]
-    fn parse_twin_prediction_index_as_string_and_one_based() {
-        let raw = r#"{"option_index": "1", "confidence": 0.5}"#;
-        let draft = parse_twin_prediction(raw, &prediction_options());
-        // 1-based reading preferred: "1" means the first listed option.
-        assert_eq!(draft.matched_option_index, Some(0));
-        assert_eq!(draft.predicted_option, "Take the Denver job");
-    }
-
-    #[test]
-    fn parse_twin_prediction_text_beats_conflicting_index() {
-        let raw = r#"{"predicted_option": "Stay in Austin", "option_index": 1, "confidence": 0.9}"#;
-        let draft = parse_twin_prediction(raw, &prediction_options());
-        // The option text is what the model said; the conflicting index loses.
-        assert_eq!(draft.matched_option_index, Some(1));
-    }
-
-    #[test]
-    fn parse_twin_prediction_out_of_range_index_with_valid_text() {
-        let raw = r#"{"predicted_option": "Stay in Austin", "option_index": 9}"#;
-        let draft = parse_twin_prediction(raw, &prediction_options());
-        assert_eq!(draft.matched_option_index, Some(1));
-    }
-
-    #[test]
-    fn parse_twin_prediction_bare_text_and_labels() {
-        let options = prediction_options();
-        let bare = parse_twin_prediction("  Stay in Austin\n", &options);
-        assert_eq!(bare.parse_mode, "string_match");
-        assert_eq!(bare.matched_option_index, Some(1));
-
-        let letter = parse_twin_prediction("B", &options);
-        assert_eq!(letter.matched_option_index, Some(1));
-
-        let labeled = parse_twin_prediction("Option 2", &options);
-        assert_eq!(labeled.matched_option_index, Some(1));
-    }
-
-    #[test]
-    fn parse_twin_prediction_garbage_falls_to_raw() {
-        let long_garbage = "I think there are many considerations here ".repeat(40);
-        let draft = parse_twin_prediction(&long_garbage, &prediction_options());
-        assert_eq!(draft.parse_mode, "raw");
-        assert!(draft.matched_option_index.is_none());
-        assert!(draft.predicted_option.chars().count() <= 500);
-    }
-
-    #[test]
-    fn parse_twin_prediction_reversed_braces_does_not_panic() {
-        // The closing brace appears BEFORE the opening one, so `raw.find('{')` finds a
-        // start index greater than `raw.rfind('}')`'s end index. Slicing `&raw[start..=end]`
-        // without checking `start <= end` panics — which previously crashed the spawned
-        // sealed-prediction task, silently skipping both `attach_twin_prediction` and
-        // `mark_twin_prediction_failed`.
-        let raw = "Option A} — but {incomplete";
-        let draft = parse_twin_prediction(raw, &prediction_options());
-        // No panic reaching here is the primary assertion. The malformed brace pair is
-        // simply not treated as JSON, so it falls through the same fallback chain as any
-        // other non-JSON text.
-        assert_ne!(draft.parse_mode, "json");
-    }
-
-    #[test]
-    fn extract_json_slice_rejects_reversed_braces() {
-        assert_eq!(extract_json_slice("Option A} — but {incomplete"), None);
-        assert_eq!(extract_json_slice("no braces here"), None);
-        assert_eq!(extract_json_slice("only open {"), None);
-        assert_eq!(extract_json_slice("only close }"), None);
-        assert_eq!(
-            extract_json_slice(r#"prefix {"a": 1} suffix"#),
-            Some(r#"{"a": 1}"#)
-        );
-    }
-
-    #[test]
-    fn parse_twin_prediction_sanitizes_confidence() {
-        let options = prediction_options();
-        let percent = parse_twin_prediction(
-            r#"{"predicted_option": "Stay in Austin", "confidence": 73}"#,
-            &options,
-        );
-        assert_eq!(percent.confidence, Some(0.73));
-
-        let overshoot = parse_twin_prediction(
-            r#"{"predicted_option": "Stay in Austin", "confidence": 1.2}"#,
-            &options,
-        );
-        assert_eq!(overshoot.confidence, Some(1.0));
-
-        let negative = parse_twin_prediction(
-            r#"{"predicted_option": "Stay in Austin", "confidence": -0.1}"#,
-            &options,
-        );
-        assert_eq!(negative.confidence, Some(0.0));
-
-        let null = parse_twin_prediction(
-            r#"{"predicted_option": "Stay in Austin", "confidence": null}"#,
-            &options,
-        );
-        assert!(null.confidence.is_none());
-    }
-
-    #[test]
-    fn attach_twin_prediction_refuses_after_outcome_and_duplicates() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        let episode = store
-            .record_decision_episode(DecisionEpisodeCreate {
-                id: "decision-attach".to_string(),
-                session_id: "session-1".to_string(),
-                tile_id: "tile-1".to_string(),
-                decision: "Take the Denver job?".to_string(),
-                options: prediction_options(),
-                stakes: None,
-                initial_leaning: None,
-                review_date: None,
-                primitive_assessment: PrimitiveDecisionAssessment::default(),
-                context_version: Some("ctx-test".to_string()),
-            })
-            .expect("episode should persist");
-
-        let draft = parse_twin_prediction("Stay in Austin", &prediction_options());
-        let sealed = store
-            .attach_twin_prediction(&episode.id, draft.clone(), "test/model", "ctx-test")
-            .expect("first attach should seal");
-        assert_eq!(sealed.prediction_status.as_deref(), Some("sealed"));
-        let first_sealed_at = sealed.twin_prediction.as_ref().unwrap().sealed_at;
-
-        // Duplicate attach is a no-op.
-        let duplicate = store
-            .attach_twin_prediction(&episode.id, draft.clone(), "other/model", "ctx-test")
-            .expect("duplicate attach should not error");
-        assert_eq!(
-            duplicate.twin_prediction.as_ref().unwrap().sealed_at,
-            first_sealed_at
-        );
-        assert_eq!(
-            duplicate.twin_prediction.as_ref().unwrap().model_id,
-            "test/model"
-        );
-
-        // Outcome-first race: attach after the choice is recorded.
-        let late_episode = store
-            .record_decision_episode(DecisionEpisodeCreate {
-                id: "decision-late".to_string(),
-                session_id: "session-1".to_string(),
-                tile_id: "tile-2".to_string(),
-                decision: "Take the Denver job?".to_string(),
-                options: prediction_options(),
-                stakes: None,
-                initial_leaning: None,
-                review_date: None,
-                primitive_assessment: PrimitiveDecisionAssessment::default(),
-                context_version: None,
-            })
-            .expect("episode should persist");
-        store
-            .update_decision_outcome(
-                &late_episode.id,
-                DecisionOutcomeUpdate {
-                    chosen_option: Some("Stay in Austin".to_string()),
-                    ..DecisionOutcomeUpdate::default()
-                },
-            )
-            .expect("outcome should record");
-        let refused = store
-            .attach_twin_prediction(&late_episode.id, draft, "test/model", "ctx-test")
-            .expect("late attach should not error");
-        assert!(refused.twin_prediction.is_none());
-        assert_eq!(
-            refused.prediction_status.as_deref(),
-            Some("outcome_recorded_first")
-        );
-    }
-
-    #[test]
-    fn outcome_computes_agreement_and_canonicalizes_choice() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        let episode = store
-            .record_decision_episode(DecisionEpisodeCreate {
-                id: "decision-agree".to_string(),
-                session_id: "session-1".to_string(),
-                tile_id: "tile-1".to_string(),
-                decision: "Take the Denver job?".to_string(),
-                options: prediction_options(),
-                stakes: None,
-                initial_leaning: None,
-                review_date: None,
-                primitive_assessment: PrimitiveDecisionAssessment::default(),
-                context_version: Some("ctx-test".to_string()),
-            })
-            .expect("episode should persist");
-        let draft = parse_twin_prediction("Stay in Austin", &prediction_options());
-        store
-            .attach_twin_prediction(&episode.id, draft, "test/model", "ctx-test")
-            .expect("prediction should seal");
-
-        // Label + case variant resolves to the canonical option text and
-        // agreement computes via index comparison.
-        let updated = store
-            .update_decision_outcome(
-                &episode.id,
-                DecisionOutcomeUpdate {
-                    chosen_option: Some("option 2".to_string()),
-                    correction_note: None,
-                    ..DecisionOutcomeUpdate::default()
-                },
-            )
-            .expect("outcome should record");
-        assert_eq!(updated.chosen_option.as_deref(), Some("Stay in Austin"));
-        assert_eq!(updated.agreement, Some(true));
-        assert!(updated.outcome_recorded_at.is_some());
-
-        // Editing the choice recomputes agreement and accepts a correction
-        // note; outcome_recorded_at is not reset.
-        let first_recorded_at = updated.outcome_recorded_at;
-        let edited = store
-            .update_decision_outcome(
-                &episode.id,
-                DecisionOutcomeUpdate {
-                    chosen_option: Some("  TAKE the denver JOB ".to_string()),
-                    correction_note: Some("Twin overweighted family proximity.".to_string()),
-                    ..DecisionOutcomeUpdate::default()
-                },
-            )
-            .expect("edited outcome should record");
-        assert_eq!(edited.chosen_option.as_deref(), Some("Take the Denver job"));
-        assert_eq!(edited.agreement, Some(false));
-        assert_eq!(
-            edited.correction_note.as_deref(),
-            Some("Twin overweighted family proximity.")
-        );
-        assert_eq!(edited.outcome_recorded_at, first_recorded_at);
-    }
-
-    #[test]
-    fn outcome_without_prediction_records_no_agreement_and_keeps_free_text() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        let episode = store
-            .record_decision_episode(DecisionEpisodeCreate {
-                id: "decision-free".to_string(),
-                session_id: "session-1".to_string(),
-                tile_id: "tile-1".to_string(),
-                decision: "Take the Denver job?".to_string(),
-                options: prediction_options(),
-                stakes: None,
-                initial_leaning: None,
-                review_date: None,
-                primitive_assessment: PrimitiveDecisionAssessment::default(),
-                context_version: None,
-            })
-            .expect("episode should persist");
-
-        let updated = store
-            .update_decision_outcome(
-                &episode.id,
-                DecisionOutcomeUpdate {
-                    chosen_option: Some("Negotiated a remote arrangement instead".to_string()),
-                    ..DecisionOutcomeUpdate::default()
-                },
-            )
-            .expect("outcome should record");
-        // Free text that matches no option is preserved verbatim.
-        assert_eq!(
-            updated.chosen_option.as_deref(),
-            Some("Negotiated a remote arrangement instead")
-        );
-        assert!(updated.agreement.is_none());
-    }
-
     #[test]
     fn memory_digest_caps_review_items_and_updates_record_state() {
         let temp_dir = tempdir().expect("temp dir should be created");
@@ -2833,6 +1004,13 @@ mod tests {
         assert!(std::path::Path::new(&bundle.rejected_user_records.path).exists());
     }
 
+    fn prediction_options() -> Vec<String> {
+        vec![
+            "Take the Denver job".to_string(),
+            "Stay in Austin".to_string(),
+        ]
+    }
+
     #[test]
     fn export_redacts_sealed_predictions_and_filters_private_feedback_events() {
         let temp_dir = tempdir().expect("temp dir should be created");

From 20273024f2c56daf6276fb97600010a4af99ffe6 Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 15:59:25 +0800
Subject: [PATCH 14/30] refactor: extract twin::digest

Moves memory digest clustering and review (list_memory_digest,
review_memory_digest_item, clustering/staleness helpers) into
services/twin/digest.rs. Verbatim move; tests move with their code.
---
 .../src-tauri/src/services/twin/digest.rs     | 507 ++++++++++++++++++
 frontend/src-tauri/src/services/twin/mod.rs   | 461 +---------------
 2 files changed, 508 insertions(+), 460 deletions(-)
 create mode 100644 frontend/src-tauri/src/services/twin/digest.rs

diff --git a/frontend/src-tauri/src/services/twin/digest.rs b/frontend/src-tauri/src/services/twin/digest.rs
new file mode 100644
index 0000000..51c5528
--- /dev/null
+++ b/frontend/src-tauri/src/services/twin/digest.rs
@@ -0,0 +1,507 @@
+use crate::models::note::Note;
+use crate::models::twin::{
+    ActionGap, ActionGapCreate, ConstitutionInferenceSummary, ConstitutionItem,
+    ConstitutionItemCreate, ConstitutionItemUpdate, ConstitutionReviewRequest, ConstitutionSetup,
+    ConstitutionStatus, DecisionEpisode, DecisionEpisodeCreate, DecisionEpisodeWithReflections,
+    DecisionEvidencePacket, DecisionEvidenceSource, DecisionMirrorConfig,
+    DecisionMirrorConfigUpdate, DecisionMirrorWeights, DecisionOutcomeUpdate, EvidenceRef,
+    ExportBundle, ExportFileSummary, MemoryDigestAction, MemoryDigestItem,
+    MemoryDigestReviewRequest, MemoryDigestState, PromotionState, RecordOrigin, ReflectionCard,
+    ReflectionCardCreate, ReflectionScores, ResolvedEvidenceRef, SessionTrace, TraceEvent,
+    TraceEventType, TwinContextRecord, TwinExportRequest, TwinInferenceRunSummary, TwinPrediction,
+    TwinPredictionDraft, TwinReviewRecord, UserRecord, UserRecordCreate, UserRecordKind,
+    UserRecordUpdate,
+};
+#[cfg(test)]
+use crate::models::twin::{DecisionMirrorPreset, PrimitiveDecisionAssessment};
+use crate::services::atomic_io::write_atomic;
+use anyhow::{Context, Result};
+use chrono::Utc;
+use serde::de::DeserializeOwned;
+use serde::Serialize;
+use serde_json::{json, Value};
+use std::collections::hash_map::DefaultHasher;
+use std::collections::HashMap;
+use std::collections::HashSet;
+use std::hash::{Hash, Hasher};
+use std::path::{Path, PathBuf};
+use std::time::{SystemTime, UNIX_EPOCH};
+use walkdir::WalkDir;
+use super::TwinStore;
+use super::shared::{lexical_terms};
+use super::{AUTO_PROMOTE_CONFIDENCE, AUTO_PROMOTE_SUPPORT_COUNT};
+use super::constitution::normalize_key_text;
+
+const MAX_MEMORY_DIGEST_ITEMS: usize = 5;
+
+fn memory_digest_trigger(record: &UserRecord) -> Option<&'static str> {
+    if record.kind == UserRecordKind::Fact {
+        return None;
+    }
+
+    match record.promotion_state {
+        PromotionState::Rejected | PromotionState::Private | PromotionState::NoTrain => None,
+        PromotionState::AutoPromoted
+            if record.evidence_refs.len() >= AUTO_PROMOTE_SUPPORT_COUNT =>
+        {
+            Some("3+ evidence points support this durable pattern")
+        }
+        PromotionState::Candidate if record.evidence_refs.len() >= AUTO_PROMOTE_SUPPORT_COUNT => {
+            Some("candidate pattern has enough evidence for review")
+        }
+        PromotionState::Candidate
+            if record.confidence >= AUTO_PROMOTE_CONFIDENCE && !record.evidence_refs.is_empty() =>
+        {
+            Some("high-confidence candidate pattern needs review")
+        }
+        PromotionState::Endorsed if stale_for_review(record) => {
+            Some("endorsed pattern may be stale")
+        }
+        PromotionState::AutoPromoted => None,
+        PromotionState::Endorsed => None,
+        PromotionState::Candidate => None,
+    }
+}
+
+fn memory_digest_cluster_key(record: &UserRecord) -> String {
+    if let Some(signal_family) = record
+        .metadata
+        .get("signal_family")
+        .and_then(Value::as_str)
+        .filter(|value| !value.trim().is_empty())
+    {
+        return format!("{:?}::{}", record.kind, signal_family.trim().to_lowercase());
+    }
+
+    let mut terms = lexical_terms(&record.content)
+        .into_iter()
+        .collect::<Vec<_>>();
+    terms.sort();
+    terms.truncate(6);
+    if terms.is_empty() {
+        format!("{:?}::{}", record.kind, normalize_key_text(&record.content))
+    } else {
+        format!("{:?}::{}", record.kind, terms.join("-"))
+    }
+}
+
+fn stable_digest_id(records: &[UserRecord]) -> String {
+    let mut ids = records
+        .iter()
+        .map(|record| record.id.as_str())
+        .collect::<Vec<_>>();
+    ids.sort_unstable();
+    let mut hasher = DefaultHasher::new();
+    ids.hash(&mut hasher);
+    format!("digest-cluster-{:x}", hasher.finish())
+}
+
+fn stale_for_review(record: &UserRecord) -> bool {
+    Utc::now()
+        .signed_duration_since(record.updated_at)
+        .num_days()
+        >= 90
+}
+
+fn digest_state_sort_key(state: &MemoryDigestState) -> u8 {
+    match state {
+        MemoryDigestState::Pending => 0,
+        MemoryDigestState::Softened => 1,
+        MemoryDigestState::Kept => 2,
+        MemoryDigestState::NotMe => 3,
+        MemoryDigestState::Private => 4,
+        MemoryDigestState::NoTrain => 5,
+        MemoryDigestState::Rejected => 6,
+    }
+}
+
+fn memory_digest_state_for_action(action: &MemoryDigestAction) -> MemoryDigestState {
+    match action {
+        MemoryDigestAction::Keep => MemoryDigestState::Kept,
+        MemoryDigestAction::Soften => MemoryDigestState::Softened,
+        MemoryDigestAction::NotMe => MemoryDigestState::NotMe,
+        MemoryDigestAction::Private => MemoryDigestState::Private,
+        MemoryDigestAction::NoTrain => MemoryDigestState::NoTrain,
+        MemoryDigestAction::Reject => MemoryDigestState::Rejected,
+    }
+}
+
+
+impl TwinStore {
+    pub fn list_memory_digest(&mut self) -> Result<Vec<MemoryDigestItem>> {
+        self.ensure_record_cache()?;
+        let mut existing = self.read_memory_digest_file()?;
+        let mut existing_by_id = existing
+            .iter()
+            .cloned()
+            .map(|item| (item.id.clone(), item))
+            .collect::<HashMap<_, _>>();
+        let now = Utc::now();
+        let records = self
+            .record_cache
+            .values()
+            .filter(|record| memory_digest_trigger(record).is_some())
+            .cloned()
+            .collect::<Vec<_>>();
+        let mut clusters: HashMap<String, Vec<UserRecord>> = HashMap::new();
+
+        for record in records {
+            clusters
+                .entry(memory_digest_cluster_key(&record))
+                .or_default()
+                .push(record);
+        }
+
+        for mut records in clusters.into_values() {
+            records.sort_by(|a, b| {
+                b.evidence_refs
+                    .len()
+                    .cmp(&a.evidence_refs.len())
+                    .then_with(|| {
+                        b.confidence
+                            .partial_cmp(&a.confidence)
+                            .unwrap_or(std::cmp::Ordering::Equal)
+                    })
+                    .then_with(|| b.updated_at.cmp(&a.updated_at))
+            });
+            let primary = match records.first() {
+                Some(record) => record,
+                None => continue,
+            };
+            let item_id = stable_digest_id(&records);
+            if existing_by_id.contains_key(&item_id) {
+                continue;
+            }
+
+            let record_ids = records
+                .iter()
+                .map(|record| record.id.clone())
+                .collect::<Vec<_>>();
+            let evidence_count = records
+                .iter()
+                .map(|record| record.evidence_refs.len())
+                .sum::<usize>();
+            let confidence = records
+                .iter()
+                .map(|record| record.confidence)
+                .fold(0.0_f32, f32::max);
+            let trigger_reason = if records.len() > 1 {
+                format!("{} related patterns clustered for review", records.len())
+            } else {
+                memory_digest_trigger(primary)
+                    .unwrap_or("pattern needs review")
+                    .to_string()
+            };
+            let latest_evidence = self
+                .resolve_evidence_refs(&primary.evidence_refs)
+                .ok()
+                .and_then(|mut refs| refs.drain(..).next());
+            let item = MemoryDigestItem {
+                id: item_id.clone(),
+                pattern: primary.content.clone(),
+                evidence_count,
+                confidence,
+                trigger_reason,
+                latest_evidence,
+                record_ids,
+                state: MemoryDigestState::Pending,
+                created_at: now,
+                updated_at: now,
+            };
+            existing_by_id.insert(item_id, item);
+        }
+
+        existing = existing_by_id.into_values().collect();
+        existing.sort_by(|a, b| {
+            digest_state_sort_key(&a.state)
+                .cmp(&digest_state_sort_key(&b.state))
+                .then_with(|| b.evidence_count.cmp(&a.evidence_count))
+                .then_with(|| {
+                    b.confidence
+                        .partial_cmp(&a.confidence)
+                        .unwrap_or(std::cmp::Ordering::Equal)
+                })
+                .then_with(|| b.updated_at.cmp(&a.updated_at))
+        });
+        self.write_memory_digest_file(&existing)?;
+
+        Ok(existing
+            .into_iter()
+            .filter(|item| item.state == MemoryDigestState::Pending)
+            .take(MAX_MEMORY_DIGEST_ITEMS)
+            .collect())
+    }
+
+    pub fn review_memory_digest_item(
+        &mut self,
+        id: &str,
+        request: MemoryDigestReviewRequest,
+    ) -> Result<MemoryDigestItem> {
+        Self::validate_file_id(id)?;
+        let mut items = self.read_memory_digest_file()?;
+        if !items.iter().any(|item| item.id == id) {
+            let _ = self.list_memory_digest()?;
+            items = self.read_memory_digest_file()?;
+        }
+
+        let item_index = items
+            .iter()
+            .position(|item| item.id == id)
+            .ok_or_else(|| anyhow::anyhow!("Memory digest item not found: {}", id))?;
+        let mut item = items[item_index].clone();
+        item.state = memory_digest_state_for_action(&request.action);
+        item.updated_at = Utc::now();
+        items[item_index] = item.clone();
+        self.write_memory_digest_file(&items)?;
+
+        for record_id in &item.record_ids {
+            if self.get_user_record(record_id).is_err() {
+                continue;
+            }
+
+            let promotion_state = match request.action {
+                MemoryDigestAction::Keep => Some(PromotionState::Endorsed),
+                MemoryDigestAction::Soften => Some(PromotionState::Candidate),
+                MemoryDigestAction::NotMe | MemoryDigestAction::Reject => {
+                    Some(PromotionState::Rejected)
+                }
+                MemoryDigestAction::Private => Some(PromotionState::Private),
+                MemoryDigestAction::NoTrain => Some(PromotionState::NoTrain),
+            };
+
+            if let Some(state) = promotion_state {
+                let _ = self.set_user_record_promotion(
+                    record_id,
+                    state,
+                    request
+                        .rationale
+                        .clone()
+                        .or_else(|| Some(format!("Memory digest action: {:?}", request.action))),
+                );
+            }
+
+            if request.action == MemoryDigestAction::Soften {
+                if let Ok(record) = self.get_user_record(record_id) {
+                    let _ = self.update_user_record(
+                        record_id,
+                        UserRecordUpdate {
+                            confidence: Some((record.confidence * 0.85).max(0.35)),
+                            ..UserRecordUpdate::default()
+                        },
+                    );
+                }
+            }
+        }
+
+        Ok(item)
+    }
+
+    fn read_memory_digest_file(&self) -> Result<Vec<MemoryDigestItem>> {
+        if !self.digest_path.exists() {
+            return Ok(Vec::new());
+        }
+
+        let content = std::fs::read_to_string(&self.digest_path).with_context(|| {
+            format!(
+                "Failed to read memory digest file: {}",
+                self.digest_path.display()
+            )
+        })?;
+        serde_json::from_str(&content).with_context(|| {
+            format!(
+                "Failed to parse memory digest file: {}",
+                self.digest_path.display()
+            )
+        })
+    }
+
+    fn write_memory_digest_file(&self, items: &[MemoryDigestItem]) -> Result<()> {
+        self.write_pretty_json(&self.digest_path, &items)
+    }
+
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::models::note::{Note, NoteStatus};
+    use crate::models::twin::{
+        default_record_confidence, PromotionState, RecordLink, RecordLinkType, UserRecordKind,
+    };
+    use tempfile::tempdir;
+
+    #[test]
+    fn memory_digest_caps_review_items_and_updates_record_state() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        let mut record_ids = Vec::new();
+        for index in 0..6 {
+            let record = store
+                .create_user_record(UserRecordCreate {
+                    kind: UserRecordKind::ReasoningPattern,
+                    content: format!("Pattern {} benefits from evidence gates.", index),
+                    origin: RecordOrigin::Inferred,
+                    evidence_refs: vec![
+                        EvidenceRef {
+                            trace_id: "session-1".to_string(),
+                            event_id: format!("event-{}-1", index),
+                            session_id: "session-1".to_string(),
+                            tile_id: Some(format!("tile-{}", index)),
+                            model_id: None,
+                            note: None,
+                            source_type: Some("behavior".to_string()),
+                            source_id: None,
+                            source_label: None,
+                            excerpt: None,
+                            speaker_role: None,
+                        },
+                        EvidenceRef {
+                            trace_id: "session-1".to_string(),
+                            event_id: format!("event-{}-2", index),
+                            session_id: "session-1".to_string(),
+                            tile_id: Some(format!("tile-{}", index)),
+                            model_id: None,
+                            note: None,
+                            source_type: Some("behavior".to_string()),
+                            source_id: None,
+                            source_label: None,
+                            excerpt: None,
+                            speaker_role: None,
+                        },
+                        EvidenceRef {
+                            trace_id: "session-1".to_string(),
+                            event_id: format!("event-{}-3", index),
+                            session_id: "session-1".to_string(),
+                            tile_id: Some(format!("tile-{}", index)),
+                            model_id: None,
+                            note: None,
+                            source_type: Some("behavior".to_string()),
+                            source_id: None,
+                            source_label: None,
+                            excerpt: None,
+                            speaker_role: None,
+                        },
+                    ],
+                    confidence: 0.82,
+                    promotion_state: Some(PromotionState::Candidate),
+                    valid_from: None,
+                    valid_until: None,
+                    links: Vec::new(),
+                    metadata: HashMap::from([(
+                        "signal_family".to_string(),
+                        serde_json::json!(format!("evidence_gate_family_{}", index)),
+                    )]),
+                })
+                .expect("record should be created");
+            record_ids.push(record.id);
+        }
+
+        let digest = store.list_memory_digest().expect("digest should list");
+        assert_eq!(digest.len(), 5);
+        assert!(digest.iter().all(|item| item.evidence_count == 3));
+
+        let reviewed = store
+            .review_memory_digest_item(
+                &digest[0].id,
+                MemoryDigestReviewRequest {
+                    action: MemoryDigestAction::NoTrain,
+                    rationale: Some("Do not use this in twin context".to_string()),
+                },
+            )
+            .expect("digest item should update");
+        assert_eq!(reviewed.state, MemoryDigestState::NoTrain);
+
+        let linked_record = store
+            .get_user_record(&reviewed.record_ids[0])
+            .expect("linked record should still exist");
+        assert_eq!(linked_record.promotion_state, PromotionState::NoTrain);
+
+        let (approved, candidates) = store
+            .select_context_records("evidence gates")
+            .expect("context records should select");
+        assert!(!approved
+            .iter()
+            .any(|record| record.id == reviewed.record_ids[0]));
+        assert!(!candidates
+            .iter()
+            .any(|record| record.id == reviewed.record_ids[0]));
+        assert_eq!(record_ids.len(), 6);
+    }
+
+    #[test]
+    fn memory_digest_clusters_related_records() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        for index in 0..3 {
+            store
+                .create_user_record(UserRecordCreate {
+                    kind: UserRecordKind::ReasoningPattern,
+                    content: format!(
+                        "Pattern {} says the user benefits from hard evidence gates before scaling.",
+                        index
+                    ),
+                    origin: RecordOrigin::Inferred,
+                    evidence_refs: vec![
+                        EvidenceRef {
+                            trace_id: "session-1".to_string(),
+                            event_id: format!("cluster-event-{}-1", index),
+                            session_id: "session-1".to_string(),
+                            tile_id: Some(format!("cluster-tile-{}", index)),
+                            model_id: None,
+                            note: None,
+                            source_type: Some("behavior".to_string()),
+                            source_id: None,
+                            source_label: None,
+                            excerpt: None,
+                            speaker_role: None,
+                        },
+                        EvidenceRef {
+                            trace_id: "session-1".to_string(),
+                            event_id: format!("cluster-event-{}-2", index),
+                            session_id: "session-1".to_string(),
+                            tile_id: Some(format!("cluster-tile-{}", index)),
+                            model_id: None,
+                            note: None,
+                            source_type: Some("behavior".to_string()),
+                            source_id: None,
+                            source_label: None,
+                            excerpt: None,
+                            speaker_role: None,
+                        },
+                        EvidenceRef {
+                            trace_id: "session-1".to_string(),
+                            event_id: format!("cluster-event-{}-3", index),
+                            session_id: "session-1".to_string(),
+                            tile_id: Some(format!("cluster-tile-{}", index)),
+                            model_id: None,
+                            note: None,
+                            source_type: Some("behavior".to_string()),
+                            source_id: None,
+                            source_label: None,
+                            excerpt: None,
+                            speaker_role: None,
+                        },
+                    ],
+                    confidence: 0.84,
+                    promotion_state: Some(PromotionState::Candidate),
+                    valid_from: None,
+                    valid_until: None,
+                    links: Vec::new(),
+                    metadata: HashMap::from([(
+                        "signal_family".to_string(),
+                        serde_json::json!("evidence_gates"),
+                    )]),
+                })
+                .expect("record should be created");
+        }
+
+        let digest = store.list_memory_digest().expect("digest should list");
+        assert_eq!(digest.len(), 1);
+        assert_eq!(digest[0].record_ids.len(), 3);
+        assert_eq!(digest[0].evidence_count, 9);
+        assert!(digest[0].trigger_reason.contains("clustered"));
+    }
+
+}
diff --git a/frontend/src-tauri/src/services/twin/mod.rs b/frontend/src-tauri/src/services/twin/mod.rs
index 504c4ba..4e60328 100644
--- a/frontend/src-tauri/src/services/twin/mod.rs
+++ b/frontend/src-tauri/src/services/twin/mod.rs
@@ -33,14 +33,13 @@ mod traces;
 mod records;
 mod constitution;
 mod decisions;
+mod digest;
 
 use shared::*;
 pub use decisions::parse_twin_prediction;
-use constitution::normalize_key_text;
 
 const AUTO_PROMOTE_CONFIDENCE: f32 = 0.75;
 const AUTO_PROMOTE_SUPPORT_COUNT: usize = 3;
-const MAX_MEMORY_DIGEST_ITEMS: usize = 5;
 const DEFAULT_EVAL_PERCENTAGE: u8 = 10;
 const DEFAULT_HOLDOUT_PERCENTAGE: u8 = 10;
 
@@ -51,99 +50,6 @@ enum ExportSplit {
     Holdout,
 }
 
-fn memory_digest_trigger(record: &UserRecord) -> Option<&'static str> {
-    if record.kind == UserRecordKind::Fact {
-        return None;
-    }
-
-    match record.promotion_state {
-        PromotionState::Rejected | PromotionState::Private | PromotionState::NoTrain => None,
-        PromotionState::AutoPromoted
-            if record.evidence_refs.len() >= AUTO_PROMOTE_SUPPORT_COUNT =>
-        {
-            Some("3+ evidence points support this durable pattern")
-        }
-        PromotionState::Candidate if record.evidence_refs.len() >= AUTO_PROMOTE_SUPPORT_COUNT => {
-            Some("candidate pattern has enough evidence for review")
-        }
-        PromotionState::Candidate
-            if record.confidence >= AUTO_PROMOTE_CONFIDENCE && !record.evidence_refs.is_empty() =>
-        {
-            Some("high-confidence candidate pattern needs review")
-        }
-        PromotionState::Endorsed if stale_for_review(record) => {
-            Some("endorsed pattern may be stale")
-        }
-        PromotionState::AutoPromoted => None,
-        PromotionState::Endorsed => None,
-        PromotionState::Candidate => None,
-    }
-}
-
-fn memory_digest_cluster_key(record: &UserRecord) -> String {
-    if let Some(signal_family) = record
-        .metadata
-        .get("signal_family")
-        .and_then(Value::as_str)
-        .filter(|value| !value.trim().is_empty())
-    {
-        return format!("{:?}::{}", record.kind, signal_family.trim().to_lowercase());
-    }
-
-    let mut terms = lexical_terms(&record.content)
-        .into_iter()
-        .collect::<Vec<_>>();
-    terms.sort();
-    terms.truncate(6);
-    if terms.is_empty() {
-        format!("{:?}::{}", record.kind, normalize_key_text(&record.content))
-    } else {
-        format!("{:?}::{}", record.kind, terms.join("-"))
-    }
-}
-
-fn stable_digest_id(records: &[UserRecord]) -> String {
-    let mut ids = records
-        .iter()
-        .map(|record| record.id.as_str())
-        .collect::<Vec<_>>();
-    ids.sort_unstable();
-    let mut hasher = DefaultHasher::new();
-    ids.hash(&mut hasher);
-    format!("digest-cluster-{:x}", hasher.finish())
-}
-
-fn stale_for_review(record: &UserRecord) -> bool {
-    Utc::now()
-        .signed_duration_since(record.updated_at)
-        .num_days()
-        >= 90
-}
-
-fn digest_state_sort_key(state: &MemoryDigestState) -> u8 {
-    match state {
-        MemoryDigestState::Pending => 0,
-        MemoryDigestState::Softened => 1,
-        MemoryDigestState::Kept => 2,
-        MemoryDigestState::NotMe => 3,
-        MemoryDigestState::Private => 4,
-        MemoryDigestState::NoTrain => 5,
-        MemoryDigestState::Rejected => 6,
-    }
-}
-
-fn memory_digest_state_for_action(action: &MemoryDigestAction) -> MemoryDigestState {
-    match action {
-        MemoryDigestAction::Keep => MemoryDigestState::Kept,
-        MemoryDigestAction::Soften => MemoryDigestState::Softened,
-        MemoryDigestAction::NotMe => MemoryDigestState::NotMe,
-        MemoryDigestAction::Private => MemoryDigestState::Private,
-        MemoryDigestAction::NoTrain => MemoryDigestState::NoTrain,
-        MemoryDigestAction::Reject => MemoryDigestState::Rejected,
-    }
-}
-
-
 pub struct TwinStore {
     root_path: PathBuf,
     traces_path: PathBuf,
@@ -219,197 +125,6 @@ impl TwinStore {
         Ok(())
     }
 
-    pub fn list_memory_digest(&mut self) -> Result<Vec<MemoryDigestItem>> {
-        self.ensure_record_cache()?;
-        let mut existing = self.read_memory_digest_file()?;
-        let mut existing_by_id = existing
-            .iter()
-            .cloned()
-            .map(|item| (item.id.clone(), item))
-            .collect::<HashMap<_, _>>();
-        let now = Utc::now();
-        let records = self
-            .record_cache
-            .values()
-            .filter(|record| memory_digest_trigger(record).is_some())
-            .cloned()
-            .collect::<Vec<_>>();
-        let mut clusters: HashMap<String, Vec<UserRecord>> = HashMap::new();
-
-        for record in records {
-            clusters
-                .entry(memory_digest_cluster_key(&record))
-                .or_default()
-                .push(record);
-        }
-
-        for mut records in clusters.into_values() {
-            records.sort_by(|a, b| {
-                b.evidence_refs
-                    .len()
-                    .cmp(&a.evidence_refs.len())
-                    .then_with(|| {
-                        b.confidence
-                            .partial_cmp(&a.confidence)
-                            .unwrap_or(std::cmp::Ordering::Equal)
-                    })
-                    .then_with(|| b.updated_at.cmp(&a.updated_at))
-            });
-            let primary = match records.first() {
-                Some(record) => record,
-                None => continue,
-            };
-            let item_id = stable_digest_id(&records);
-            if existing_by_id.contains_key(&item_id) {
-                continue;
-            }
-
-            let record_ids = records
-                .iter()
-                .map(|record| record.id.clone())
-                .collect::<Vec<_>>();
-            let evidence_count = records
-                .iter()
-                .map(|record| record.evidence_refs.len())
-                .sum::<usize>();
-            let confidence = records
-                .iter()
-                .map(|record| record.confidence)
-                .fold(0.0_f32, f32::max);
-            let trigger_reason = if records.len() > 1 {
-                format!("{} related patterns clustered for review", records.len())
-            } else {
-                memory_digest_trigger(primary)
-                    .unwrap_or("pattern needs review")
-                    .to_string()
-            };
-            let latest_evidence = self
-                .resolve_evidence_refs(&primary.evidence_refs)
-                .ok()
-                .and_then(|mut refs| refs.drain(..).next());
-            let item = MemoryDigestItem {
-                id: item_id.clone(),
-                pattern: primary.content.clone(),
-                evidence_count,
-                confidence,
-                trigger_reason,
-                latest_evidence,
-                record_ids,
-                state: MemoryDigestState::Pending,
-                created_at: now,
-                updated_at: now,
-            };
-            existing_by_id.insert(item_id, item);
-        }
-
-        existing = existing_by_id.into_values().collect();
-        existing.sort_by(|a, b| {
-            digest_state_sort_key(&a.state)
-                .cmp(&digest_state_sort_key(&b.state))
-                .then_with(|| b.evidence_count.cmp(&a.evidence_count))
-                .then_with(|| {
-                    b.confidence
-                        .partial_cmp(&a.confidence)
-                        .unwrap_or(std::cmp::Ordering::Equal)
-                })
-                .then_with(|| b.updated_at.cmp(&a.updated_at))
-        });
-        self.write_memory_digest_file(&existing)?;
-
-        Ok(existing
-            .into_iter()
-            .filter(|item| item.state == MemoryDigestState::Pending)
-            .take(MAX_MEMORY_DIGEST_ITEMS)
-            .collect())
-    }
-
-    pub fn review_memory_digest_item(
-        &mut self,
-        id: &str,
-        request: MemoryDigestReviewRequest,
-    ) -> Result<MemoryDigestItem> {
-        Self::validate_file_id(id)?;
-        let mut items = self.read_memory_digest_file()?;
-        if !items.iter().any(|item| item.id == id) {
-            let _ = self.list_memory_digest()?;
-            items = self.read_memory_digest_file()?;
-        }
-
-        let item_index = items
-            .iter()
-            .position(|item| item.id == id)
-            .ok_or_else(|| anyhow::anyhow!("Memory digest item not found: {}", id))?;
-        let mut item = items[item_index].clone();
-        item.state = memory_digest_state_for_action(&request.action);
-        item.updated_at = Utc::now();
-        items[item_index] = item.clone();
-        self.write_memory_digest_file(&items)?;
-
-        for record_id in &item.record_ids {
-            if self.get_user_record(record_id).is_err() {
-                continue;
-            }
-
-            let promotion_state = match request.action {
-                MemoryDigestAction::Keep => Some(PromotionState::Endorsed),
-                MemoryDigestAction::Soften => Some(PromotionState::Candidate),
-                MemoryDigestAction::NotMe | MemoryDigestAction::Reject => {
-                    Some(PromotionState::Rejected)
-                }
-                MemoryDigestAction::Private => Some(PromotionState::Private),
-                MemoryDigestAction::NoTrain => Some(PromotionState::NoTrain),
-            };
-
-            if let Some(state) = promotion_state {
-                let _ = self.set_user_record_promotion(
-                    record_id,
-                    state,
-                    request
-                        .rationale
-                        .clone()
-                        .or_else(|| Some(format!("Memory digest action: {:?}", request.action))),
-                );
-            }
-
-            if request.action == MemoryDigestAction::Soften {
-                if let Ok(record) = self.get_user_record(record_id) {
-                    let _ = self.update_user_record(
-                        record_id,
-                        UserRecordUpdate {
-                            confidence: Some((record.confidence * 0.85).max(0.35)),
-                            ..UserRecordUpdate::default()
-                        },
-                    );
-                }
-            }
-        }
-
-        Ok(item)
-    }
-
-    fn read_memory_digest_file(&self) -> Result<Vec<MemoryDigestItem>> {
-        if !self.digest_path.exists() {
-            return Ok(Vec::new());
-        }
-
-        let content = std::fs::read_to_string(&self.digest_path).with_context(|| {
-            format!(
-                "Failed to read memory digest file: {}",
-                self.digest_path.display()
-            )
-        })?;
-        serde_json::from_str(&content).with_context(|| {
-            format!(
-                "Failed to parse memory digest file: {}",
-                self.digest_path.display()
-            )
-        })
-    }
-
-    fn write_memory_digest_file(&self, items: &[MemoryDigestItem]) -> Result<()> {
-        self.write_pretty_json(&self.digest_path, &items)
-    }
-
     pub fn export_bundle(&mut self, request: TwinExportRequest) -> Result<ExportBundle> {
         self.ensure_record_cache()?;
 
@@ -770,180 +485,6 @@ mod tests {
     };
     use tempfile::tempdir;
 
-    #[test]
-    fn memory_digest_caps_review_items_and_updates_record_state() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        let mut record_ids = Vec::new();
-        for index in 0..6 {
-            let record = store
-                .create_user_record(UserRecordCreate {
-                    kind: UserRecordKind::ReasoningPattern,
-                    content: format!("Pattern {} benefits from evidence gates.", index),
-                    origin: RecordOrigin::Inferred,
-                    evidence_refs: vec![
-                        EvidenceRef {
-                            trace_id: "session-1".to_string(),
-                            event_id: format!("event-{}-1", index),
-                            session_id: "session-1".to_string(),
-                            tile_id: Some(format!("tile-{}", index)),
-                            model_id: None,
-                            note: None,
-                            source_type: Some("behavior".to_string()),
-                            source_id: None,
-                            source_label: None,
-                            excerpt: None,
-                            speaker_role: None,
-                        },
-                        EvidenceRef {
-                            trace_id: "session-1".to_string(),
-                            event_id: format!("event-{}-2", index),
-                            session_id: "session-1".to_string(),
-                            tile_id: Some(format!("tile-{}", index)),
-                            model_id: None,
-                            note: None,
-                            source_type: Some("behavior".to_string()),
-                            source_id: None,
-                            source_label: None,
-                            excerpt: None,
-                            speaker_role: None,
-                        },
-                        EvidenceRef {
-                            trace_id: "session-1".to_string(),
-                            event_id: format!("event-{}-3", index),
-                            session_id: "session-1".to_string(),
-                            tile_id: Some(format!("tile-{}", index)),
-                            model_id: None,
-                            note: None,
-                            source_type: Some("behavior".to_string()),
-                            source_id: None,
-                            source_label: None,
-                            excerpt: None,
-                            speaker_role: None,
-                        },
-                    ],
-                    confidence: 0.82,
-                    promotion_state: Some(PromotionState::Candidate),
-                    valid_from: None,
-                    valid_until: None,
-                    links: Vec::new(),
-                    metadata: HashMap::from([(
-                        "signal_family".to_string(),
-                        serde_json::json!(format!("evidence_gate_family_{}", index)),
-                    )]),
-                })
-                .expect("record should be created");
-            record_ids.push(record.id);
-        }
-
-        let digest = store.list_memory_digest().expect("digest should list");
-        assert_eq!(digest.len(), 5);
-        assert!(digest.iter().all(|item| item.evidence_count == 3));
-
-        let reviewed = store
-            .review_memory_digest_item(
-                &digest[0].id,
-                MemoryDigestReviewRequest {
-                    action: MemoryDigestAction::NoTrain,
-                    rationale: Some("Do not use this in twin context".to_string()),
-                },
-            )
-            .expect("digest item should update");
-        assert_eq!(reviewed.state, MemoryDigestState::NoTrain);
-
-        let linked_record = store
-            .get_user_record(&reviewed.record_ids[0])
-            .expect("linked record should still exist");
-        assert_eq!(linked_record.promotion_state, PromotionState::NoTrain);
-
-        let (approved, candidates) = store
-            .select_context_records("evidence gates")
-            .expect("context records should select");
-        assert!(!approved
-            .iter()
-            .any(|record| record.id == reviewed.record_ids[0]));
-        assert!(!candidates
-            .iter()
-            .any(|record| record.id == reviewed.record_ids[0]));
-        assert_eq!(record_ids.len(), 6);
-    }
-
-    #[test]
-    fn memory_digest_clusters_related_records() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        for index in 0..3 {
-            store
-                .create_user_record(UserRecordCreate {
-                    kind: UserRecordKind::ReasoningPattern,
-                    content: format!(
-                        "Pattern {} says the user benefits from hard evidence gates before scaling.",
-                        index
-                    ),
-                    origin: RecordOrigin::Inferred,
-                    evidence_refs: vec![
-                        EvidenceRef {
-                            trace_id: "session-1".to_string(),
-                            event_id: format!("cluster-event-{}-1", index),
-                            session_id: "session-1".to_string(),
-                            tile_id: Some(format!("cluster-tile-{}", index)),
-                            model_id: None,
-                            note: None,
-                            source_type: Some("behavior".to_string()),
-                            source_id: None,
-                            source_label: None,
-                            excerpt: None,
-                            speaker_role: None,
-                        },
-                        EvidenceRef {
-                            trace_id: "session-1".to_string(),
-                            event_id: format!("cluster-event-{}-2", index),
-                            session_id: "session-1".to_string(),
-                            tile_id: Some(format!("cluster-tile-{}", index)),
-                            model_id: None,
-                            note: None,
-                            source_type: Some("behavior".to_string()),
-                            source_id: None,
-                            source_label: None,
-                            excerpt: None,
-                            speaker_role: None,
-                        },
-                        EvidenceRef {
-                            trace_id: "session-1".to_string(),
-                            event_id: format!("cluster-event-{}-3", index),
-                            session_id: "session-1".to_string(),
-                            tile_id: Some(format!("cluster-tile-{}", index)),
-                            model_id: None,
-                            note: None,
-                            source_type: Some("behavior".to_string()),
-                            source_id: None,
-                            source_label: None,
-                            excerpt: None,
-                            speaker_role: None,
-                        },
-                    ],
-                    confidence: 0.84,
-                    promotion_state: Some(PromotionState::Candidate),
-                    valid_from: None,
-                    valid_until: None,
-                    links: Vec::new(),
-                    metadata: HashMap::from([(
-                        "signal_family".to_string(),
-                        serde_json::json!("evidence_gates"),
-                    )]),
-                })
-                .expect("record should be created");
-        }
-
-        let digest = store.list_memory_digest().expect("digest should list");
-        assert_eq!(digest.len(), 1);
-        assert_eq!(digest[0].record_ids.len(), 3);
-        assert_eq!(digest[0].evidence_count, 9);
-        assert!(digest[0].trigger_reason.contains("clustered"));
-    }
-
     #[test]
     fn export_separates_approved_candidate_and_rejected_records() {
         let temp_dir = tempdir().expect("temp dir should be created");

From 9ed29fd45c2424e4aa98653b126e801de4172754 Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 16:06:20 +0800
Subject: [PATCH 15/30] refactor: extract twin::export

Moves the JSONL/manifest export bundle (export_bundle, per-split-bucket
helpers) into services/twin/export.rs. mod.rs now shrinks to the
TwinStore facade: struct fields, new(), write_pretty_json, and
validate_file_id -- the handful of helpers used by every domain
submodule, kept here so they're visible to all descendants without
pub(super). Public API is unchanged from the pre-split twin_store.rs.
Verbatim move; tests move with their code.
---
 .../src-tauri/src/services/twin/export.rs     | 580 +++++++++++++++++
 frontend/src-tauri/src/services/twin/mod.rs   | 603 +-----------------
 2 files changed, 608 insertions(+), 575 deletions(-)
 create mode 100644 frontend/src-tauri/src/services/twin/export.rs

diff --git a/frontend/src-tauri/src/services/twin/export.rs b/frontend/src-tauri/src/services/twin/export.rs
new file mode 100644
index 0000000..de129d9
--- /dev/null
+++ b/frontend/src-tauri/src/services/twin/export.rs
@@ -0,0 +1,580 @@
+use crate::models::note::Note;
+use crate::models::twin::{
+    ActionGap, ActionGapCreate, ConstitutionInferenceSummary, ConstitutionItem,
+    ConstitutionItemCreate, ConstitutionItemUpdate, ConstitutionReviewRequest, ConstitutionSetup,
+    ConstitutionStatus, DecisionEpisode, DecisionEpisodeCreate, DecisionEpisodeWithReflections,
+    DecisionEvidencePacket, DecisionEvidenceSource, DecisionMirrorConfig,
+    DecisionMirrorConfigUpdate, DecisionMirrorWeights, DecisionOutcomeUpdate, EvidenceRef,
+    ExportBundle, ExportFileSummary, MemoryDigestAction, MemoryDigestItem,
+    MemoryDigestReviewRequest, MemoryDigestState, PromotionState, RecordOrigin, ReflectionCard,
+    ReflectionCardCreate, ReflectionScores, ResolvedEvidenceRef, SessionTrace, TraceEvent,
+    TraceEventType, TwinContextRecord, TwinExportRequest, TwinInferenceRunSummary, TwinPrediction,
+    TwinPredictionDraft, TwinReviewRecord, UserRecord, UserRecordCreate, UserRecordKind,
+    UserRecordUpdate,
+};
+#[cfg(test)]
+use crate::models::twin::{DecisionMirrorPreset, PrimitiveDecisionAssessment};
+use crate::services::atomic_io::write_atomic;
+use anyhow::{Context, Result};
+use chrono::Utc;
+use serde::de::DeserializeOwned;
+use serde::Serialize;
+use serde_json::{json, Value};
+use std::collections::hash_map::DefaultHasher;
+use std::collections::HashMap;
+use std::collections::HashSet;
+use std::hash::{Hash, Hasher};
+use std::path::{Path, PathBuf};
+use std::time::{SystemTime, UNIX_EPOCH};
+use walkdir::WalkDir;
+use super::TwinStore;
+#[cfg(test)]
+use super::decisions::parse_twin_prediction;
+
+const DEFAULT_EVAL_PERCENTAGE: u8 = 10;
+const DEFAULT_HOLDOUT_PERCENTAGE: u8 = 10;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum ExportSplit {
+    Train,
+    Eval,
+    Holdout,
+}
+
+impl TwinStore {
+    pub fn export_bundle(&mut self, request: TwinExportRequest) -> Result<ExportBundle> {
+        self.ensure_record_cache()?;
+
+        let eval_percentage = request.eval_percentage.unwrap_or(DEFAULT_EVAL_PERCENTAGE);
+        let holdout_percentage = request
+            .holdout_percentage
+            .unwrap_or(DEFAULT_HOLDOUT_PERCENTAGE);
+
+        if eval_percentage + holdout_percentage >= 100 {
+            anyhow::bail!("Eval and holdout percentages must total less than 100");
+        }
+
+        let bundle_name = request.bundle_name.as_deref().unwrap_or("latest").trim();
+        if bundle_name.is_empty() {
+            anyhow::bail!("Bundle name cannot be empty");
+        }
+        Self::validate_file_id(bundle_name)?;
+
+        let output_dir = self.exports_path.join(bundle_name);
+        std::fs::create_dir_all(&output_dir).with_context(|| {
+            format!(
+                "Failed to create export directory: {}",
+                output_dir.display()
+            )
+        })?;
+
+        let approved_path = output_dir.join("approved_user_records.jsonl");
+        let candidate_path = output_dir.join("candidate_user_records.jsonl");
+        let rejected_path = output_dir.join("rejected_user_records.jsonl");
+        let train_path = output_dir.join("train.jsonl");
+        let eval_path = output_dir.join("eval.jsonl");
+        let holdout_path = output_dir.join("holdout.jsonl");
+        let benchmark_path = output_dir.join("decision_mirror_benchmark.jsonl");
+        let constitution_path = output_dir.join("constitution_items.jsonl");
+        let action_gaps_path = output_dir.join("action_gaps.jsonl");
+        let decision_episodes_path = output_dir.join("decision_episodes.jsonl");
+        let feedback_events_path = output_dir.join("feedback_events.jsonl");
+        let manifest_path = output_dir.join("manifest.json");
+
+        let mut records: Vec<UserRecord> = self.record_cache.values().cloned().collect();
+        records.sort_by(|a, b| a.id.cmp(&b.id));
+
+        let mut approved_lines = Vec::new();
+        let mut candidate_lines = Vec::new();
+        let mut rejected_lines = Vec::new();
+        let mut train_lines = Vec::new();
+        let mut eval_lines = Vec::new();
+        let mut holdout_lines = Vec::new();
+        let mut included_record_ids = Vec::new();
+        let mut private_or_no_train_record_ids = Vec::new();
+
+        for record in records {
+            let line = serde_json::to_string(&Self::record_to_export_value(&record))?;
+
+            match record.promotion_state {
+                PromotionState::AutoPromoted | PromotionState::Endorsed => {
+                    included_record_ids.push(record.id.clone());
+                    approved_lines.push(line.clone());
+                    match Self::split_for_record(&record, eval_percentage, holdout_percentage) {
+                        ExportSplit::Train => train_lines.push(line),
+                        ExportSplit::Eval => eval_lines.push(line),
+                        ExportSplit::Holdout => holdout_lines.push(line),
+                    }
+                }
+                PromotionState::Candidate => {
+                    candidate_lines.push(line);
+                }
+                PromotionState::Rejected => {
+                    rejected_lines.push(line);
+                }
+                PromotionState::Private | PromotionState::NoTrain => {
+                    private_or_no_train_record_ids.push(record.id.clone());
+                }
+            }
+        }
+
+        self.write_jsonl_file(&approved_path, &approved_lines)?;
+        self.write_jsonl_file(&candidate_path, &candidate_lines)?;
+        self.write_jsonl_file(&rejected_path, &rejected_lines)?;
+        self.write_jsonl_file(&train_path, &train_lines)?;
+        self.write_jsonl_file(&eval_path, &eval_lines)?;
+        self.write_jsonl_file(&holdout_path, &holdout_lines)?;
+        let decision_mirror_config = self.get_decision_mirror_config()?;
+        let benchmark_lines = self
+            .list_decision_episodes_with_reflections()?
+            .into_iter()
+            .map(|entry| {
+                serde_json::to_string(&json!({
+                    "variant": "decision_mirror",
+                    "baseline_variants": [
+                        "generic_llm",
+                        "persona_prompt",
+                        "vault_only_rag",
+                        "twin_rag",
+                        "decision_mirror"
+                    ],
+                    "config": decision_mirror_config.clone(),
+                    "episode": entry.episode,
+                    "reflection_cards": entry.reflection_cards,
+                }))
+            })
+            .collect::<std::result::Result<Vec<_>, _>>()?;
+        self.write_jsonl_file(&benchmark_path, &benchmark_lines)?;
+        let constitution_lines = self
+            .list_constitution_items()?
+            .into_iter()
+            .map(|item| serde_json::to_string(&item))
+            .collect::<std::result::Result<Vec<_>, _>>()?;
+        self.write_jsonl_file(&constitution_path, &constitution_lines)?;
+        let action_gap_lines = self
+            .list_action_gaps()?
+            .into_iter()
+            .map(|gap| serde_json::to_string(&gap))
+            .collect::<std::result::Result<Vec<_>, _>>()?;
+        self.write_jsonl_file(&action_gaps_path, &action_gap_lines)?;
+
+        // Decision episodes with sealed-prediction integrity: while an
+        // episode has no recorded choice, its prediction exports as a
+        // non-revealing stub so the bet cannot leak through an early export.
+        let decision_episode_lines = self
+            .list_decision_episodes()?
+            .into_iter()
+            .map(|episode| {
+                let still_sealed =
+                    episode.twin_prediction.is_some() && episode.chosen_option.is_none();
+                let mut value = serde_json::to_value(&episode)?;
+                if still_sealed {
+                    if let Some(object) = value.as_object_mut() {
+                        let stub = episode.twin_prediction.as_ref().map(|prediction| {
+                            serde_json::json!({
+                                "sealed": true,
+                                "sealed_at": prediction.sealed_at,
+                                "model_id": prediction.model_id,
+                                "context_version": prediction.context_version,
+                                "parse_mode": prediction.parse_mode,
+                            })
+                        });
+                        object.insert("twin_prediction".to_string(), stub.unwrap_or(Value::Null));
+                    }
+                }
+                serde_json::to_string(&value).map_err(anyhow::Error::from)
+            })
+            .collect::<Result<Vec<_>>>()?;
+        self.write_jsonl_file(&decision_episodes_path, &decision_episode_lines)?;
+
+        // Ranking / Matches-Me / insight raw material. Privacy rule: skip
+        // events that are evidence for records now marked Rejected, Private,
+        // or NoTrain.
+        let excluded_event_ids: HashSet<String> = self
+            .record_cache
+            .values()
+            .filter(|record| {
+                matches!(
+                    record.promotion_state,
+                    PromotionState::Rejected | PromotionState::Private | PromotionState::NoTrain
+                )
+            })
+            .flat_map(|record| {
+                record
+                    .evidence_refs
+                    .iter()
+                    .map(|evidence| evidence.event_id.clone())
+            })
+            .collect();
+        let feedback_event_lines = self
+            .list_session_traces()?
+            .into_iter()
+            .flat_map(|trace| {
+                let session_id = trace.session_id.clone();
+                let trace_id = trace.id.clone();
+                trace
+                    .events
+                    .into_iter()
+                    .filter(|event| {
+                        matches!(
+                            event.event_type,
+                            TraceEventType::FeedbackRecorded
+                                | TraceEventType::RankingRecorded
+                                | TraceEventType::InsightCaptured
+                        ) && !excluded_event_ids.contains(&event.id)
+                    })
+                    .map(move |event| {
+                        serde_json::to_string(&serde_json::json!({
+                            "session_id": session_id,
+                            "trace_id": trace_id,
+                            "event": event,
+                        }))
+                        .map_err(anyhow::Error::from)
+                    })
+                    .collect::<Vec<_>>()
+            })
+            .collect::<Result<Vec<_>>>()?;
+        self.write_jsonl_file(&feedback_events_path, &feedback_event_lines)?;
+
+        let manifest = serde_json::json!({
+            "bundle_schema_version": 2,
+            "generated_at": Utc::now(),
+            "root_path": self.root_path.display().to_string(),
+            "eval_percentage": eval_percentage,
+            "holdout_percentage": holdout_percentage,
+            "included_record_ids": included_record_ids,
+            "record_files": {
+                "approved_user_records": {
+                    "path": approved_path.display().to_string(),
+                    "count": approved_lines.len(),
+                },
+                "candidate_user_records": {
+                    "path": candidate_path.display().to_string(),
+                    "count": candidate_lines.len(),
+                },
+                "rejected_user_records": {
+                    "path": rejected_path.display().to_string(),
+                    "count": rejected_lines.len(),
+                },
+                "decision_mirror_benchmark": {
+                    "path": benchmark_path.display().to_string(),
+                    "count": benchmark_lines.len(),
+                },
+                "constitution_items": {
+                    "path": constitution_path.display().to_string(),
+                    "count": constitution_lines.len(),
+                },
+                "action_gaps": {
+                    "path": action_gaps_path.display().to_string(),
+                    "count": action_gap_lines.len(),
+                },
+                "decision_episodes": {
+                    "path": decision_episodes_path.display().to_string(),
+                    "count": decision_episode_lines.len(),
+                },
+                "feedback_events": {
+                    "path": feedback_events_path.display().to_string(),
+                    "count": feedback_event_lines.len(),
+                },
+            },
+            "excluded_counts": {
+                "private_or_no_train": private_or_no_train_record_ids.len(),
+            }
+        });
+        self.write_pretty_json(&manifest_path, &manifest)?;
+
+        Ok(ExportBundle {
+            output_dir: output_dir.display().to_string(),
+            approved_user_records: ExportFileSummary {
+                path: approved_path.display().to_string(),
+                count: approved_lines.len(),
+            },
+            candidate_user_records: ExportFileSummary {
+                path: candidate_path.display().to_string(),
+                count: candidate_lines.len(),
+            },
+            rejected_user_records: ExportFileSummary {
+                path: rejected_path.display().to_string(),
+                count: rejected_lines.len(),
+            },
+            decision_mirror_benchmark: ExportFileSummary {
+                path: benchmark_path.display().to_string(),
+                count: benchmark_lines.len(),
+            },
+            constitution_items: ExportFileSummary {
+                path: constitution_path.display().to_string(),
+                count: constitution_lines.len(),
+            },
+            action_gaps: ExportFileSummary {
+                path: action_gaps_path.display().to_string(),
+                count: action_gap_lines.len(),
+            },
+            decision_episodes: ExportFileSummary {
+                path: decision_episodes_path.display().to_string(),
+                count: decision_episode_lines.len(),
+            },
+            feedback_events: ExportFileSummary {
+                path: feedback_events_path.display().to_string(),
+                count: feedback_event_lines.len(),
+            },
+            train: ExportFileSummary {
+                path: train_path.display().to_string(),
+                count: train_lines.len(),
+            },
+            eval: ExportFileSummary {
+                path: eval_path.display().to_string(),
+                count: eval_lines.len(),
+            },
+            holdout: ExportFileSummary {
+                path: holdout_path.display().to_string(),
+                count: holdout_lines.len(),
+            },
+            manifest_path: manifest_path.display().to_string(),
+            included_records: train_lines.len() + eval_lines.len() + holdout_lines.len(),
+            excluded_records: private_or_no_train_record_ids.len(),
+        })
+    }
+
+    fn split_for_record(
+        record: &UserRecord,
+        eval_percentage: u8,
+        holdout_percentage: u8,
+    ) -> ExportSplit {
+        let key = format!(
+            "{}:{}:{}:{}",
+            record.id,
+            serde_json::to_string(&record.kind).unwrap_or_default(),
+            record.content,
+            record.updated_at
+        );
+        let bucket = Self::stable_bucket(&key);
+
+        if bucket < holdout_percentage {
+            ExportSplit::Holdout
+        } else if bucket < holdout_percentage + eval_percentage {
+            ExportSplit::Eval
+        } else {
+            ExportSplit::Train
+        }
+    }
+
+    fn stable_bucket(key: &str) -> u8 {
+        let mut hasher = DefaultHasher::new();
+        key.hash(&mut hasher);
+        (hasher.finish() % 100) as u8
+    }
+
+    fn record_to_export_value(record: &UserRecord) -> serde_json::Value {
+        serde_json::json!({
+            "id": record.id,
+            "kind": record.kind,
+            "content": record.content,
+            "origin": record.origin,
+            "promotion_state": record.promotion_state,
+            "confidence": record.confidence,
+            "created_at": record.created_at,
+            "updated_at": record.updated_at,
+            "valid_from": record.valid_from,
+            "valid_until": record.valid_until,
+            "links": record.links,
+            "evidence_refs": record.evidence_refs,
+            "metadata": record.metadata,
+        })
+    }
+
+    fn write_jsonl_file(&self, path: &Path, lines: &[String]) -> Result<()> {
+        let mut content = lines.join("\n");
+        if !content.is_empty() {
+            content.push('\n');
+        }
+        write_atomic(path, content.as_bytes())
+            .with_context(|| format!("Failed to write JSONL file: {}", path.display()))
+    }
+
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::models::note::{Note, NoteStatus};
+    use crate::models::twin::{
+        default_record_confidence, PromotionState, RecordLink, RecordLinkType, UserRecordKind,
+    };
+    use tempfile::tempdir;
+
+    #[test]
+    fn export_separates_approved_candidate_and_rejected_records() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::Fact,
+                content: "Approved".to_string(),
+                origin: RecordOrigin::User,
+                evidence_refs: Vec::new(),
+                confidence: 0.9,
+                promotion_state: Some(PromotionState::Endorsed),
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
+            })
+            .expect("approved record should be created");
+        store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::Preference,
+                content: "Candidate".to_string(),
+                origin: RecordOrigin::Inferred,
+                evidence_refs: Vec::new(),
+                confidence: 0.6,
+                promotion_state: Some(PromotionState::Candidate),
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
+            })
+            .expect("candidate record should be created");
+        store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::ReasoningPattern,
+                content: "Rejected".to_string(),
+                origin: RecordOrigin::Inferred,
+                evidence_refs: Vec::new(),
+                confidence: 0.8,
+                promotion_state: Some(PromotionState::Rejected),
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
+            })
+            .expect("rejected record should be created");
+
+        let bundle = store
+            .export_bundle(TwinExportRequest::default())
+            .expect("export should succeed");
+
+        assert_eq!(bundle.approved_user_records.count, 1);
+        assert_eq!(bundle.candidate_user_records.count, 1);
+        assert_eq!(bundle.rejected_user_records.count, 1);
+        assert!(std::path::Path::new(&bundle.approved_user_records.path).exists());
+        assert!(std::path::Path::new(&bundle.candidate_user_records.path).exists());
+        assert!(std::path::Path::new(&bundle.rejected_user_records.path).exists());
+    }
+
+    fn prediction_options() -> Vec<String> {
+        vec![
+            "Take the Denver job".to_string(),
+            "Stay in Austin".to_string(),
+        ]
+    }
+
+    #[test]
+    fn export_redacts_sealed_predictions_and_filters_private_feedback_events() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
+
+        for (id, record_outcome) in [("episode-sealed", false), ("episode-revealed", true)] {
+            store
+                .record_decision_episode(DecisionEpisodeCreate {
+                    id: id.to_string(),
+                    session_id: "session-1".to_string(),
+                    tile_id: format!("tile-{id}"),
+                    decision: "Take the Denver job?".to_string(),
+                    options: prediction_options(),
+                    stakes: None,
+                    initial_leaning: None,
+                    review_date: None,
+                    primitive_assessment: PrimitiveDecisionAssessment::default(),
+                    context_version: Some("ctx-test".to_string()),
+                })
+                .expect("episode should persist");
+            let draft = parse_twin_prediction("Stay in Austin", &prediction_options());
+            store
+                .attach_twin_prediction(id, draft, "test/model", "ctx-test")
+                .expect("prediction should seal");
+            if record_outcome {
+                store
+                    .update_decision_outcome(
+                        id,
+                        DecisionOutcomeUpdate {
+                            chosen_option: Some("Stay in Austin".to_string()),
+                            ..DecisionOutcomeUpdate::default()
+                        },
+                    )
+                    .expect("outcome should record");
+            }
+        }
+
+        // One feedback event tied to a record later marked Private, one free.
+        let private_event = store
+            .append_trace_event(
+                "session-1",
+                TraceEventType::FeedbackRecorded,
+                json!({"rationale": "extremely sensitive rationale"}),
+            )
+            .expect("event should append");
+        let exportable_event = store
+            .append_trace_event(
+                "session-1",
+                TraceEventType::RankingRecorded,
+                json!({"ranking": ["a", "b"]}),
+            )
+            .expect("event should append");
+        store
+            .create_user_record(UserRecordCreate {
+                kind: UserRecordKind::Preference,
+                content: "Private claim".to_string(),
+                origin: RecordOrigin::User,
+                evidence_refs: vec![EvidenceRef {
+                    trace_id: "session-1".to_string(),
+                    event_id: private_event.id.clone(),
+                    session_id: "session-1".to_string(),
+                    tile_id: None,
+                    model_id: None,
+                    note: None,
+                    source_type: None,
+                    source_id: None,
+                    source_label: None,
+                    excerpt: None,
+                    speaker_role: None,
+                }],
+                confidence: default_record_confidence(),
+                promotion_state: Some(PromotionState::Private),
+                valid_from: None,
+                valid_until: None,
+                links: Vec::new(),
+                metadata: HashMap::new(),
+            })
+            .expect("private record should be created");
+
+        let bundle = store
+            .export_bundle(TwinExportRequest::default())
+            .expect("export should succeed");
+        assert_eq!(bundle.decision_episodes.count, 2);
+
+        let episodes_content = std::fs::read_to_string(&bundle.decision_episodes.path)
+            .expect("decision episodes file should read");
+        let sealed_line = episodes_content
+            .lines()
+            .find(|line| line.contains("episode-sealed"))
+            .expect("sealed episode should export");
+        assert!(sealed_line.contains("\"sealed\":true"));
+        assert!(!sealed_line.contains("predicted_option"));
+        assert!(!sealed_line.contains("rationale"));
+        let revealed_line = episodes_content
+            .lines()
+            .find(|line| line.contains("episode-revealed"))
+            .expect("revealed episode should export");
+        assert!(revealed_line.contains("predicted_option"));
+        assert!(revealed_line.contains("\"agreement\":true"));
+        assert!(revealed_line.contains("ctx-test"));
+
+        let feedback_content = std::fs::read_to_string(&bundle.feedback_events.path)
+            .expect("feedback events file should read");
+        assert!(!feedback_content.contains("extremely sensitive rationale"));
+        assert!(!feedback_content.contains(&private_event.id));
+        assert!(feedback_content.contains(&exportable_event.id));
+    }
+
+}
diff --git a/frontend/src-tauri/src/services/twin/mod.rs b/frontend/src-tauri/src/services/twin/mod.rs
index 4e60328..4503b70 100644
--- a/frontend/src-tauri/src/services/twin/mod.rs
+++ b/frontend/src-tauri/src/services/twin/mod.rs
@@ -1,54 +1,42 @@
-use crate::models::note::Note;
-use crate::models::twin::{
-    ActionGap, ActionGapCreate, ConstitutionInferenceSummary, ConstitutionItem,
-    ConstitutionItemCreate, ConstitutionItemUpdate, ConstitutionReviewRequest, ConstitutionSetup,
-    ConstitutionStatus, DecisionEpisode, DecisionEpisodeCreate, DecisionEpisodeWithReflections,
-    DecisionEvidencePacket, DecisionEvidenceSource, DecisionMirrorConfig,
-    DecisionMirrorConfigUpdate, DecisionMirrorWeights, DecisionOutcomeUpdate, EvidenceRef,
-    ExportBundle, ExportFileSummary, MemoryDigestAction, MemoryDigestItem,
-    MemoryDigestReviewRequest, MemoryDigestState, PromotionState, RecordOrigin, ReflectionCard,
-    ReflectionCardCreate, ReflectionScores, ResolvedEvidenceRef, SessionTrace, TraceEvent,
-    TraceEventType, TwinContextRecord, TwinExportRequest, TwinInferenceRunSummary, TwinPrediction,
-    TwinPredictionDraft, TwinReviewRecord, UserRecord, UserRecordCreate, UserRecordKind,
-    UserRecordUpdate,
-};
-#[cfg(test)]
-use crate::models::twin::{DecisionMirrorPreset, PrimitiveDecisionAssessment};
-use crate::services::atomic_io::write_atomic;
-use anyhow::{Context, Result};
-use chrono::Utc;
-use serde::de::DeserializeOwned;
-use serde::Serialize;
-use serde_json::{json, Value};
-use std::collections::hash_map::DefaultHasher;
-use std::collections::HashMap;
-use std::collections::HashSet;
-use std::hash::{Hash, Hasher};
-use std::path::{Path, PathBuf};
-use std::time::{SystemTime, UNIX_EPOCH};
-use walkdir::WalkDir;
+//! Twin evidence store: sealed decisions, Constitution, action gaps, memory
+//! digest, session traces, and export. Split into focused submodules (Task 4.2):
+//! - `shared` -- quarantine/load-or-quarantine file helpers and cross-cutting
+//!   text/payload utilities used by every domain submodule below.
+//! - `traces` -- session trace append/read and evidence-ref resolution.
+//! - `records` -- user record CRUD, promotion, and behavioral inference.
+//! - `constitution` -- Constitution items, action gaps, guided setup, and
+//!   constitution inference (including interview-note extraction).
+//! - `decisions` -- decision episodes, reflection cards, and sealed twin
+//!   predictions (seal-integrity logic intact, see `attach_twin_prediction`).
+//! - `digest` -- memory digest clustering and review.
+//! - `export` -- the JSONL/manifest export bundle.
+//!
+//! `TwinStore`'s fields and the few helpers used by every domain (`new`,
+//! `write_pretty_json`, `validate_file_id`) stay here so they're visible to
+//! all of the above (private items defined in a parent module are visible to
+//! descendant modules in Rust -- no `pub(super)` needed for these). Public
+//! method signatures on `TwinStore` are unchanged from the pre-split
+//! `twin_store.rs` -- callers in `commands/twin.rs` and
+//! `commands/canvas/context.rs` do not need to change.
 
 mod shared;
 mod traces;
 mod records;
 mod constitution;
 mod decisions;
+pub use decisions::parse_twin_prediction;
 mod digest;
+mod export;
 
-use shared::*;
-pub use decisions::parse_twin_prediction;
+use crate::models::twin::{SessionTrace, UserRecord};
+use crate::services::atomic_io::write_atomic;
+use anyhow::{Context, Result};
+use serde::Serialize;
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
 
 const AUTO_PROMOTE_CONFIDENCE: f32 = 0.75;
 const AUTO_PROMOTE_SUPPORT_COUNT: usize = 3;
-const DEFAULT_EVAL_PERCENTAGE: u8 = 10;
-const DEFAULT_HOLDOUT_PERCENTAGE: u8 = 10;
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-enum ExportSplit {
-    Train,
-    Eval,
-    Holdout,
-}
 
 pub struct TwinStore {
     root_path: PathBuf,
@@ -125,539 +113,4 @@ impl TwinStore {
         Ok(())
     }
 
-    pub fn export_bundle(&mut self, request: TwinExportRequest) -> Result<ExportBundle> {
-        self.ensure_record_cache()?;
-
-        let eval_percentage = request.eval_percentage.unwrap_or(DEFAULT_EVAL_PERCENTAGE);
-        let holdout_percentage = request
-            .holdout_percentage
-            .unwrap_or(DEFAULT_HOLDOUT_PERCENTAGE);
-
-        if eval_percentage + holdout_percentage >= 100 {
-            anyhow::bail!("Eval and holdout percentages must total less than 100");
-        }
-
-        let bundle_name = request.bundle_name.as_deref().unwrap_or("latest").trim();
-        if bundle_name.is_empty() {
-            anyhow::bail!("Bundle name cannot be empty");
-        }
-        Self::validate_file_id(bundle_name)?;
-
-        let output_dir = self.exports_path.join(bundle_name);
-        std::fs::create_dir_all(&output_dir).with_context(|| {
-            format!(
-                "Failed to create export directory: {}",
-                output_dir.display()
-            )
-        })?;
-
-        let approved_path = output_dir.join("approved_user_records.jsonl");
-        let candidate_path = output_dir.join("candidate_user_records.jsonl");
-        let rejected_path = output_dir.join("rejected_user_records.jsonl");
-        let train_path = output_dir.join("train.jsonl");
-        let eval_path = output_dir.join("eval.jsonl");
-        let holdout_path = output_dir.join("holdout.jsonl");
-        let benchmark_path = output_dir.join("decision_mirror_benchmark.jsonl");
-        let constitution_path = output_dir.join("constitution_items.jsonl");
-        let action_gaps_path = output_dir.join("action_gaps.jsonl");
-        let decision_episodes_path = output_dir.join("decision_episodes.jsonl");
-        let feedback_events_path = output_dir.join("feedback_events.jsonl");
-        let manifest_path = output_dir.join("manifest.json");
-
-        let mut records: Vec<UserRecord> = self.record_cache.values().cloned().collect();
-        records.sort_by(|a, b| a.id.cmp(&b.id));
-
-        let mut approved_lines = Vec::new();
-        let mut candidate_lines = Vec::new();
-        let mut rejected_lines = Vec::new();
-        let mut train_lines = Vec::new();
-        let mut eval_lines = Vec::new();
-        let mut holdout_lines = Vec::new();
-        let mut included_record_ids = Vec::new();
-        let mut private_or_no_train_record_ids = Vec::new();
-
-        for record in records {
-            let line = serde_json::to_string(&Self::record_to_export_value(&record))?;
-
-            match record.promotion_state {
-                PromotionState::AutoPromoted | PromotionState::Endorsed => {
-                    included_record_ids.push(record.id.clone());
-                    approved_lines.push(line.clone());
-                    match Self::split_for_record(&record, eval_percentage, holdout_percentage) {
-                        ExportSplit::Train => train_lines.push(line),
-                        ExportSplit::Eval => eval_lines.push(line),
-                        ExportSplit::Holdout => holdout_lines.push(line),
-                    }
-                }
-                PromotionState::Candidate => {
-                    candidate_lines.push(line);
-                }
-                PromotionState::Rejected => {
-                    rejected_lines.push(line);
-                }
-                PromotionState::Private | PromotionState::NoTrain => {
-                    private_or_no_train_record_ids.push(record.id.clone());
-                }
-            }
-        }
-
-        self.write_jsonl_file(&approved_path, &approved_lines)?;
-        self.write_jsonl_file(&candidate_path, &candidate_lines)?;
-        self.write_jsonl_file(&rejected_path, &rejected_lines)?;
-        self.write_jsonl_file(&train_path, &train_lines)?;
-        self.write_jsonl_file(&eval_path, &eval_lines)?;
-        self.write_jsonl_file(&holdout_path, &holdout_lines)?;
-        let decision_mirror_config = self.get_decision_mirror_config()?;
-        let benchmark_lines = self
-            .list_decision_episodes_with_reflections()?
-            .into_iter()
-            .map(|entry| {
-                serde_json::to_string(&json!({
-                    "variant": "decision_mirror",
-                    "baseline_variants": [
-                        "generic_llm",
-                        "persona_prompt",
-                        "vault_only_rag",
-                        "twin_rag",
-                        "decision_mirror"
-                    ],
-                    "config": decision_mirror_config.clone(),
-                    "episode": entry.episode,
-                    "reflection_cards": entry.reflection_cards,
-                }))
-            })
-            .collect::<std::result::Result<Vec<_>, _>>()?;
-        self.write_jsonl_file(&benchmark_path, &benchmark_lines)?;
-        let constitution_lines = self
-            .list_constitution_items()?
-            .into_iter()
-            .map(|item| serde_json::to_string(&item))
-            .collect::<std::result::Result<Vec<_>, _>>()?;
-        self.write_jsonl_file(&constitution_path, &constitution_lines)?;
-        let action_gap_lines = self
-            .list_action_gaps()?
-            .into_iter()
-            .map(|gap| serde_json::to_string(&gap))
-            .collect::<std::result::Result<Vec<_>, _>>()?;
-        self.write_jsonl_file(&action_gaps_path, &action_gap_lines)?;
-
-        // Decision episodes with sealed-prediction integrity: while an
-        // episode has no recorded choice, its prediction exports as a
-        // non-revealing stub so the bet cannot leak through an early export.
-        let decision_episode_lines = self
-            .list_decision_episodes()?
-            .into_iter()
-            .map(|episode| {
-                let still_sealed =
-                    episode.twin_prediction.is_some() && episode.chosen_option.is_none();
-                let mut value = serde_json::to_value(&episode)?;
-                if still_sealed {
-                    if let Some(object) = value.as_object_mut() {
-                        let stub = episode.twin_prediction.as_ref().map(|prediction| {
-                            serde_json::json!({
-                                "sealed": true,
-                                "sealed_at": prediction.sealed_at,
-                                "model_id": prediction.model_id,
-                                "context_version": prediction.context_version,
-                                "parse_mode": prediction.parse_mode,
-                            })
-                        });
-                        object.insert("twin_prediction".to_string(), stub.unwrap_or(Value::Null));
-                    }
-                }
-                serde_json::to_string(&value).map_err(anyhow::Error::from)
-            })
-            .collect::<Result<Vec<_>>>()?;
-        self.write_jsonl_file(&decision_episodes_path, &decision_episode_lines)?;
-
-        // Ranking / Matches-Me / insight raw material. Privacy rule: skip
-        // events that are evidence for records now marked Rejected, Private,
-        // or NoTrain.
-        let excluded_event_ids: HashSet<String> = self
-            .record_cache
-            .values()
-            .filter(|record| {
-                matches!(
-                    record.promotion_state,
-                    PromotionState::Rejected | PromotionState::Private | PromotionState::NoTrain
-                )
-            })
-            .flat_map(|record| {
-                record
-                    .evidence_refs
-                    .iter()
-                    .map(|evidence| evidence.event_id.clone())
-            })
-            .collect();
-        let feedback_event_lines = self
-            .list_session_traces()?
-            .into_iter()
-            .flat_map(|trace| {
-                let session_id = trace.session_id.clone();
-                let trace_id = trace.id.clone();
-                trace
-                    .events
-                    .into_iter()
-                    .filter(|event| {
-                        matches!(
-                            event.event_type,
-                            TraceEventType::FeedbackRecorded
-                                | TraceEventType::RankingRecorded
-                                | TraceEventType::InsightCaptured
-                        ) && !excluded_event_ids.contains(&event.id)
-                    })
-                    .map(move |event| {
-                        serde_json::to_string(&serde_json::json!({
-                            "session_id": session_id,
-                            "trace_id": trace_id,
-                            "event": event,
-                        }))
-                        .map_err(anyhow::Error::from)
-                    })
-                    .collect::<Vec<_>>()
-            })
-            .collect::<Result<Vec<_>>>()?;
-        self.write_jsonl_file(&feedback_events_path, &feedback_event_lines)?;
-
-        let manifest = serde_json::json!({
-            "bundle_schema_version": 2,
-            "generated_at": Utc::now(),
-            "root_path": self.root_path.display().to_string(),
-            "eval_percentage": eval_percentage,
-            "holdout_percentage": holdout_percentage,
-            "included_record_ids": included_record_ids,
-            "record_files": {
-                "approved_user_records": {
-                    "path": approved_path.display().to_string(),
-                    "count": approved_lines.len(),
-                },
-                "candidate_user_records": {
-                    "path": candidate_path.display().to_string(),
-                    "count": candidate_lines.len(),
-                },
-                "rejected_user_records": {
-                    "path": rejected_path.display().to_string(),
-                    "count": rejected_lines.len(),
-                },
-                "decision_mirror_benchmark": {
-                    "path": benchmark_path.display().to_string(),
-                    "count": benchmark_lines.len(),
-                },
-                "constitution_items": {
-                    "path": constitution_path.display().to_string(),
-                    "count": constitution_lines.len(),
-                },
-                "action_gaps": {
-                    "path": action_gaps_path.display().to_string(),
-                    "count": action_gap_lines.len(),
-                },
-                "decision_episodes": {
-                    "path": decision_episodes_path.display().to_string(),
-                    "count": decision_episode_lines.len(),
-                },
-                "feedback_events": {
-                    "path": feedback_events_path.display().to_string(),
-                    "count": feedback_event_lines.len(),
-                },
-            },
-            "excluded_counts": {
-                "private_or_no_train": private_or_no_train_record_ids.len(),
-            }
-        });
-        self.write_pretty_json(&manifest_path, &manifest)?;
-
-        Ok(ExportBundle {
-            output_dir: output_dir.display().to_string(),
-            approved_user_records: ExportFileSummary {
-                path: approved_path.display().to_string(),
-                count: approved_lines.len(),
-            },
-            candidate_user_records: ExportFileSummary {
-                path: candidate_path.display().to_string(),
-                count: candidate_lines.len(),
-            },
-            rejected_user_records: ExportFileSummary {
-                path: rejected_path.display().to_string(),
-                count: rejected_lines.len(),
-            },
-            decision_mirror_benchmark: ExportFileSummary {
-                path: benchmark_path.display().to_string(),
-                count: benchmark_lines.len(),
-            },
-            constitution_items: ExportFileSummary {
-                path: constitution_path.display().to_string(),
-                count: constitution_lines.len(),
-            },
-            action_gaps: ExportFileSummary {
-                path: action_gaps_path.display().to_string(),
-                count: action_gap_lines.len(),
-            },
-            decision_episodes: ExportFileSummary {
-                path: decision_episodes_path.display().to_string(),
-                count: decision_episode_lines.len(),
-            },
-            feedback_events: ExportFileSummary {
-                path: feedback_events_path.display().to_string(),
-                count: feedback_event_lines.len(),
-            },
-            train: ExportFileSummary {
-                path: train_path.display().to_string(),
-                count: train_lines.len(),
-            },
-            eval: ExportFileSummary {
-                path: eval_path.display().to_string(),
-                count: eval_lines.len(),
-            },
-            holdout: ExportFileSummary {
-                path: holdout_path.display().to_string(),
-                count: holdout_lines.len(),
-            },
-            manifest_path: manifest_path.display().to_string(),
-            included_records: train_lines.len() + eval_lines.len() + holdout_lines.len(),
-            excluded_records: private_or_no_train_record_ids.len(),
-        })
-    }
-
-    fn split_for_record(
-        record: &UserRecord,
-        eval_percentage: u8,
-        holdout_percentage: u8,
-    ) -> ExportSplit {
-        let key = format!(
-            "{}:{}:{}:{}",
-            record.id,
-            serde_json::to_string(&record.kind).unwrap_or_default(),
-            record.content,
-            record.updated_at
-        );
-        let bucket = Self::stable_bucket(&key);
-
-        if bucket < holdout_percentage {
-            ExportSplit::Holdout
-        } else if bucket < holdout_percentage + eval_percentage {
-            ExportSplit::Eval
-        } else {
-            ExportSplit::Train
-        }
-    }
-
-    fn stable_bucket(key: &str) -> u8 {
-        let mut hasher = DefaultHasher::new();
-        key.hash(&mut hasher);
-        (hasher.finish() % 100) as u8
-    }
-
-    fn record_to_export_value(record: &UserRecord) -> serde_json::Value {
-        serde_json::json!({
-            "id": record.id,
-            "kind": record.kind,
-            "content": record.content,
-            "origin": record.origin,
-            "promotion_state": record.promotion_state,
-            "confidence": record.confidence,
-            "created_at": record.created_at,
-            "updated_at": record.updated_at,
-            "valid_from": record.valid_from,
-            "valid_until": record.valid_until,
-            "links": record.links,
-            "evidence_refs": record.evidence_refs,
-            "metadata": record.metadata,
-        })
-    }
-
-    fn write_jsonl_file(&self, path: &Path, lines: &[String]) -> Result<()> {
-        let mut content = lines.join("\n");
-        if !content.is_empty() {
-            content.push('\n');
-        }
-        write_atomic(path, content.as_bytes())
-            .with_context(|| format!("Failed to write JSONL file: {}", path.display()))
-    }
-
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::models::note::{Note, NoteStatus};
-    use crate::models::twin::{
-        default_record_confidence, PromotionState, RecordLink, RecordLinkType, UserRecordKind,
-    };
-    use tempfile::tempdir;
-
-    #[test]
-    fn export_separates_approved_candidate_and_rejected_records() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::Fact,
-                content: "Approved".to_string(),
-                origin: RecordOrigin::User,
-                evidence_refs: Vec::new(),
-                confidence: 0.9,
-                promotion_state: Some(PromotionState::Endorsed),
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
-            })
-            .expect("approved record should be created");
-        store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::Preference,
-                content: "Candidate".to_string(),
-                origin: RecordOrigin::Inferred,
-                evidence_refs: Vec::new(),
-                confidence: 0.6,
-                promotion_state: Some(PromotionState::Candidate),
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
-            })
-            .expect("candidate record should be created");
-        store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::ReasoningPattern,
-                content: "Rejected".to_string(),
-                origin: RecordOrigin::Inferred,
-                evidence_refs: Vec::new(),
-                confidence: 0.8,
-                promotion_state: Some(PromotionState::Rejected),
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
-            })
-            .expect("rejected record should be created");
-
-        let bundle = store
-            .export_bundle(TwinExportRequest::default())
-            .expect("export should succeed");
-
-        assert_eq!(bundle.approved_user_records.count, 1);
-        assert_eq!(bundle.candidate_user_records.count, 1);
-        assert_eq!(bundle.rejected_user_records.count, 1);
-        assert!(std::path::Path::new(&bundle.approved_user_records.path).exists());
-        assert!(std::path::Path::new(&bundle.candidate_user_records.path).exists());
-        assert!(std::path::Path::new(&bundle.rejected_user_records.path).exists());
-    }
-
-    fn prediction_options() -> Vec<String> {
-        vec![
-            "Take the Denver job".to_string(),
-            "Stay in Austin".to_string(),
-        ]
-    }
-
-    #[test]
-    fn export_redacts_sealed_predictions_and_filters_private_feedback_events() {
-        let temp_dir = tempdir().expect("temp dir should be created");
-        let mut store = TwinStore::new(temp_dir.path().to_path_buf());
-
-        for (id, record_outcome) in [("episode-sealed", false), ("episode-revealed", true)] {
-            store
-                .record_decision_episode(DecisionEpisodeCreate {
-                    id: id.to_string(),
-                    session_id: "session-1".to_string(),
-                    tile_id: format!("tile-{id}"),
-                    decision: "Take the Denver job?".to_string(),
-                    options: prediction_options(),
-                    stakes: None,
-                    initial_leaning: None,
-                    review_date: None,
-                    primitive_assessment: PrimitiveDecisionAssessment::default(),
-                    context_version: Some("ctx-test".to_string()),
-                })
-                .expect("episode should persist");
-            let draft = parse_twin_prediction("Stay in Austin", &prediction_options());
-            store
-                .attach_twin_prediction(id, draft, "test/model", "ctx-test")
-                .expect("prediction should seal");
-            if record_outcome {
-                store
-                    .update_decision_outcome(
-                        id,
-                        DecisionOutcomeUpdate {
-                            chosen_option: Some("Stay in Austin".to_string()),
-                            ..DecisionOutcomeUpdate::default()
-                        },
-                    )
-                    .expect("outcome should record");
-            }
-        }
-
-        // One feedback event tied to a record later marked Private, one free.
-        let private_event = store
-            .append_trace_event(
-                "session-1",
-                TraceEventType::FeedbackRecorded,
-                json!({"rationale": "extremely sensitive rationale"}),
-            )
-            .expect("event should append");
-        let exportable_event = store
-            .append_trace_event(
-                "session-1",
-                TraceEventType::RankingRecorded,
-                json!({"ranking": ["a", "b"]}),
-            )
-            .expect("event should append");
-        store
-            .create_user_record(UserRecordCreate {
-                kind: UserRecordKind::Preference,
-                content: "Private claim".to_string(),
-                origin: RecordOrigin::User,
-                evidence_refs: vec![EvidenceRef {
-                    trace_id: "session-1".to_string(),
-                    event_id: private_event.id.clone(),
-                    session_id: "session-1".to_string(),
-                    tile_id: None,
-                    model_id: None,
-                    note: None,
-                    source_type: None,
-                    source_id: None,
-                    source_label: None,
-                    excerpt: None,
-                    speaker_role: None,
-                }],
-                confidence: default_record_confidence(),
-                promotion_state: Some(PromotionState::Private),
-                valid_from: None,
-                valid_until: None,
-                links: Vec::new(),
-                metadata: HashMap::new(),
-            })
-            .expect("private record should be created");
-
-        let bundle = store
-            .export_bundle(TwinExportRequest::default())
-            .expect("export should succeed");
-        assert_eq!(bundle.decision_episodes.count, 2);
-
-        let episodes_content = std::fs::read_to_string(&bundle.decision_episodes.path)
-            .expect("decision episodes file should read");
-        let sealed_line = episodes_content
-            .lines()
-            .find(|line| line.contains("episode-sealed"))
-            .expect("sealed episode should export");
-        assert!(sealed_line.contains("\"sealed\":true"));
-        assert!(!sealed_line.contains("predicted_option"));
-        assert!(!sealed_line.contains("rationale"));
-        let revealed_line = episodes_content
-            .lines()
-            .find(|line| line.contains("episode-revealed"))
-            .expect("revealed episode should export");
-        assert!(revealed_line.contains("predicted_option"));
-        assert!(revealed_line.contains("\"agreement\":true"));
-        assert!(revealed_line.contains("ctx-test"));
-
-        let feedback_content = std::fs::read_to_string(&bundle.feedback_events.path)
-            .expect("feedback events file should read");
-        assert!(!feedback_content.contains("extremely sensitive rationale"));
-        assert!(!feedback_content.contains(&private_event.id));
-        assert!(feedback_content.contains(&exportable_event.id));
-    }
-
 }

From 0e961b4d8b306e9fe415c6d283f1b07c8990bbb3 Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 16:36:58 +0800
Subject: [PATCH 16/30] chore: trim unused imports across twin/ submodules

The domain split left each file with the full pre-split kitchen-sink
`use crate::models::twin::{...}` block; most entries were dead weight
once each domain only needed its own subset. Trims every submodule down
to what it actually references, cfg(test)-gating symbols that are only
used by that file's own test module so `cargo build --features mcp`
(which doesn't compile tests) stays warning-free too. Zero behavior
change; cargo test (280/280), the mcp build, and clippy (still ~42
pre-existing warnings, none added) all confirm this is imports-only.
---
 .../src/services/twin/constitution.rs         | 32 +++-----------
 .../src-tauri/src/services/twin/decisions.rs  | 31 +++----------
 .../src-tauri/src/services/twin/digest.rs     | 43 +++++--------------
 .../src-tauri/src/services/twin/export.rs     | 40 ++++++-----------
 frontend/src-tauri/src/services/twin/mod.rs   | 11 +++--
 .../src-tauri/src/services/twin/records.rs    | 38 +++++-----------
 .../src-tauri/src/services/twin/shared.rs     | 36 +++++-----------
 .../src-tauri/src/services/twin/traces.rs     | 29 ++-----------
 8 files changed, 68 insertions(+), 192 deletions(-)

diff --git a/frontend/src-tauri/src/services/twin/constitution.rs b/frontend/src-tauri/src/services/twin/constitution.rs
index dbb9f95..ce5fd7f 100644
--- a/frontend/src-tauri/src/services/twin/constitution.rs
+++ b/frontend/src-tauri/src/services/twin/constitution.rs
@@ -1,35 +1,20 @@
+use super::shared::{excerpt, lexical_terms, load_or_quarantine, text_contains_any};
+use super::TwinStore;
+use super::AUTO_PROMOTE_SUPPORT_COUNT;
 use crate::models::note::Note;
 use crate::models::twin::{
     ActionGap, ActionGapCreate, ConstitutionInferenceSummary, ConstitutionItem,
     ConstitutionItemCreate, ConstitutionItemUpdate, ConstitutionReviewRequest, ConstitutionSetup,
-    ConstitutionStatus, DecisionEpisode, DecisionEpisodeCreate, DecisionEpisodeWithReflections,
-    DecisionEvidencePacket, DecisionEvidenceSource, DecisionMirrorConfig,
-    DecisionMirrorConfigUpdate, DecisionMirrorWeights, DecisionOutcomeUpdate, EvidenceRef,
-    ExportBundle, ExportFileSummary, MemoryDigestAction, MemoryDigestItem,
-    MemoryDigestReviewRequest, MemoryDigestState, PromotionState, RecordOrigin, ReflectionCard,
-    ReflectionCardCreate, ReflectionScores, ResolvedEvidenceRef, SessionTrace, TraceEvent,
-    TraceEventType, TwinContextRecord, TwinExportRequest, TwinInferenceRunSummary, TwinPrediction,
-    TwinPredictionDraft, TwinReviewRecord, UserRecord, UserRecordCreate, UserRecordKind,
-    UserRecordUpdate,
+    ConstitutionStatus, EvidenceRef, MemoryDigestAction, PromotionState, RecordOrigin,
+    TraceEventType, UserRecord, UserRecordCreate, UserRecordKind,
 };
-#[cfg(test)]
-use crate::models::twin::{DecisionMirrorPreset, PrimitiveDecisionAssessment};
-use crate::services::atomic_io::write_atomic;
 use anyhow::{Context, Result};
 use chrono::Utc;
-use serde::de::DeserializeOwned;
-use serde::Serialize;
 use serde_json::{json, Value};
-use std::collections::hash_map::DefaultHasher;
 use std::collections::HashMap;
 use std::collections::HashSet;
-use std::hash::{Hash, Hasher};
 use std::path::{Path, PathBuf};
-use std::time::{SystemTime, UNIX_EPOCH};
 use walkdir::WalkDir;
-use super::TwinStore;
-use super::shared::{excerpt, lexical_terms, load_or_quarantine, text_contains_any};
-use super::{AUTO_PROMOTE_SUPPORT_COUNT};
 
 fn clean_setup_entries(entries: Vec<String>) -> Vec<String> {
     let mut seen = HashSet::new();
@@ -615,7 +600,6 @@ fn action_gap_relevance(gap: &ActionGap, query_terms: &HashSet<String>) -> usize
     query_terms.intersection(&gap_terms).count()
 }
 
-
 impl TwinStore {
     pub fn list_constitution_items(&self) -> Result<Vec<ConstitutionItem>> {
         let mut items = Vec::new();
@@ -1384,16 +1368,13 @@ impl TwinStore {
 
         Ok(())
     }
-
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
     use crate::models::note::{Note, NoteStatus};
-    use crate::models::twin::{
-        default_record_confidence, PromotionState, RecordLink, RecordLinkType, UserRecordKind,
-    };
+    use crate::models::twin::{PromotionState, UserRecordKind};
     use tempfile::tempdir;
 
     use crate::models::twin::ConstitutionStatus;
@@ -1743,5 +1724,4 @@ mod tests {
             vec!["Use reviewed notes only.".to_string()]
         );
     }
-
 }
diff --git a/frontend/src-tauri/src/services/twin/decisions.rs b/frontend/src-tauri/src/services/twin/decisions.rs
index d5b0437..522be6b 100644
--- a/frontend/src-tauri/src/services/twin/decisions.rs
+++ b/frontend/src-tauri/src/services/twin/decisions.rs
@@ -1,34 +1,24 @@
-use crate::models::note::Note;
+use super::shared::{
+    excerpt, extract_event_model_id, extract_event_tile_id, lexical_terms, load_or_quarantine,
+    payload_string,
+};
+use super::TwinStore;
 use crate::models::twin::{
-    ActionGap, ActionGapCreate, ConstitutionInferenceSummary, ConstitutionItem,
-    ConstitutionItemCreate, ConstitutionItemUpdate, ConstitutionReviewRequest, ConstitutionSetup,
     ConstitutionStatus, DecisionEpisode, DecisionEpisodeCreate, DecisionEpisodeWithReflections,
     DecisionEvidencePacket, DecisionEvidenceSource, DecisionMirrorConfig,
     DecisionMirrorConfigUpdate, DecisionMirrorWeights, DecisionOutcomeUpdate, EvidenceRef,
-    ExportBundle, ExportFileSummary, MemoryDigestAction, MemoryDigestItem,
-    MemoryDigestReviewRequest, MemoryDigestState, PromotionState, RecordOrigin, ReflectionCard,
-    ReflectionCardCreate, ReflectionScores, ResolvedEvidenceRef, SessionTrace, TraceEvent,
-    TraceEventType, TwinContextRecord, TwinExportRequest, TwinInferenceRunSummary, TwinPrediction,
-    TwinPredictionDraft, TwinReviewRecord, UserRecord, UserRecordCreate, UserRecordKind,
-    UserRecordUpdate,
+    PromotionState, ReflectionCard, ReflectionCardCreate, ReflectionScores, SessionTrace,
+    TraceEvent, TraceEventType, TwinPrediction, TwinPredictionDraft,
 };
 #[cfg(test)]
 use crate::models::twin::{DecisionMirrorPreset, PrimitiveDecisionAssessment};
-use crate::services::atomic_io::write_atomic;
 use anyhow::{Context, Result};
 use chrono::Utc;
-use serde::de::DeserializeOwned;
-use serde::Serialize;
 use serde_json::{json, Value};
-use std::collections::hash_map::DefaultHasher;
 use std::collections::HashMap;
 use std::collections::HashSet;
-use std::hash::{Hash, Hasher};
 use std::path::{Path, PathBuf};
-use std::time::{SystemTime, UNIX_EPOCH};
 use walkdir::WalkDir;
-use super::TwinStore;
-use super::shared::{excerpt, extract_event_model_id, extract_event_tile_id, lexical_terms, load_or_quarantine, payload_string};
 
 fn clamp_decision_mirror_weights(mut weights: DecisionMirrorWeights) -> DecisionMirrorWeights {
     weights.notes_weight = clamp_weight(weights.notes_weight);
@@ -487,7 +477,6 @@ fn decision_case_relevance(episode: &DecisionEpisode, query_terms: &HashSet<Stri
     query_terms.intersection(&episode_terms).count()
 }
 
-
 impl TwinStore {
     pub fn get_decision_mirror_config(&self) -> Result<DecisionMirrorConfig> {
         if !self.decision_mirror_config_path.exists() {
@@ -1214,16 +1203,11 @@ impl TwinStore {
         events.sort_by(|a, b| b.created_at.cmp(&a.created_at));
         Ok(events)
     }
-
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::models::note::{Note, NoteStatus};
-    use crate::models::twin::{
-        default_record_confidence, PromotionState, RecordLink, RecordLinkType, UserRecordKind,
-    };
     use tempfile::tempdir;
 
     #[test]
@@ -1873,5 +1857,4 @@ mod tests {
         );
         assert!(updated.agreement.is_none());
     }
-
 }
diff --git a/frontend/src-tauri/src/services/twin/digest.rs b/frontend/src-tauri/src/services/twin/digest.rs
index 51c5528..1413924 100644
--- a/frontend/src-tauri/src/services/twin/digest.rs
+++ b/frontend/src-tauri/src/services/twin/digest.rs
@@ -1,36 +1,19 @@
-use crate::models::note::Note;
+use super::constitution::normalize_key_text;
+use super::shared::lexical_terms;
+use super::TwinStore;
+use super::{AUTO_PROMOTE_CONFIDENCE, AUTO_PROMOTE_SUPPORT_COUNT};
+#[cfg(test)]
+use crate::models::twin::{EvidenceRef, RecordOrigin, UserRecordCreate};
 use crate::models::twin::{
-    ActionGap, ActionGapCreate, ConstitutionInferenceSummary, ConstitutionItem,
-    ConstitutionItemCreate, ConstitutionItemUpdate, ConstitutionReviewRequest, ConstitutionSetup,
-    ConstitutionStatus, DecisionEpisode, DecisionEpisodeCreate, DecisionEpisodeWithReflections,
-    DecisionEvidencePacket, DecisionEvidenceSource, DecisionMirrorConfig,
-    DecisionMirrorConfigUpdate, DecisionMirrorWeights, DecisionOutcomeUpdate, EvidenceRef,
-    ExportBundle, ExportFileSummary, MemoryDigestAction, MemoryDigestItem,
-    MemoryDigestReviewRequest, MemoryDigestState, PromotionState, RecordOrigin, ReflectionCard,
-    ReflectionCardCreate, ReflectionScores, ResolvedEvidenceRef, SessionTrace, TraceEvent,
-    TraceEventType, TwinContextRecord, TwinExportRequest, TwinInferenceRunSummary, TwinPrediction,
-    TwinPredictionDraft, TwinReviewRecord, UserRecord, UserRecordCreate, UserRecordKind,
-    UserRecordUpdate,
+    MemoryDigestAction, MemoryDigestItem, MemoryDigestReviewRequest, MemoryDigestState,
+    PromotionState, UserRecord, UserRecordKind, UserRecordUpdate,
 };
-#[cfg(test)]
-use crate::models::twin::{DecisionMirrorPreset, PrimitiveDecisionAssessment};
-use crate::services::atomic_io::write_atomic;
 use anyhow::{Context, Result};
 use chrono::Utc;
-use serde::de::DeserializeOwned;
-use serde::Serialize;
-use serde_json::{json, Value};
+use serde_json::Value;
 use std::collections::hash_map::DefaultHasher;
 use std::collections::HashMap;
-use std::collections::HashSet;
 use std::hash::{Hash, Hasher};
-use std::path::{Path, PathBuf};
-use std::time::{SystemTime, UNIX_EPOCH};
-use walkdir::WalkDir;
-use super::TwinStore;
-use super::shared::{lexical_terms};
-use super::{AUTO_PROMOTE_CONFIDENCE, AUTO_PROMOTE_SUPPORT_COUNT};
-use super::constitution::normalize_key_text;
 
 const MAX_MEMORY_DIGEST_ITEMS: usize = 5;
 
@@ -126,7 +109,6 @@ fn memory_digest_state_for_action(action: &MemoryDigestAction) -> MemoryDigestSt
     }
 }
 
-
 impl TwinStore {
     pub fn list_memory_digest(&mut self) -> Result<Vec<MemoryDigestItem>> {
         self.ensure_record_cache()?;
@@ -318,16 +300,12 @@ impl TwinStore {
     fn write_memory_digest_file(&self, items: &[MemoryDigestItem]) -> Result<()> {
         self.write_pretty_json(&self.digest_path, &items)
     }
-
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::models::note::{Note, NoteStatus};
-    use crate::models::twin::{
-        default_record_confidence, PromotionState, RecordLink, RecordLinkType, UserRecordKind,
-    };
+    use crate::models::twin::{PromotionState, UserRecordKind};
     use tempfile::tempdir;
 
     #[test]
@@ -503,5 +481,4 @@ mod tests {
         assert_eq!(digest[0].evidence_count, 9);
         assert!(digest[0].trigger_reason.contains("clustered"));
     }
-
 }
diff --git a/frontend/src-tauri/src/services/twin/export.rs b/frontend/src-tauri/src/services/twin/export.rs
index de129d9..e1f51c4 100644
--- a/frontend/src-tauri/src/services/twin/export.rs
+++ b/frontend/src-tauri/src/services/twin/export.rs
@@ -1,35 +1,24 @@
-use crate::models::note::Note;
+#[cfg(test)]
+use super::decisions::parse_twin_prediction;
+use super::TwinStore;
+#[cfg(test)]
 use crate::models::twin::{
-    ActionGap, ActionGapCreate, ConstitutionInferenceSummary, ConstitutionItem,
-    ConstitutionItemCreate, ConstitutionItemUpdate, ConstitutionReviewRequest, ConstitutionSetup,
-    ConstitutionStatus, DecisionEpisode, DecisionEpisodeCreate, DecisionEpisodeWithReflections,
-    DecisionEvidencePacket, DecisionEvidenceSource, DecisionMirrorConfig,
-    DecisionMirrorConfigUpdate, DecisionMirrorWeights, DecisionOutcomeUpdate, EvidenceRef,
-    ExportBundle, ExportFileSummary, MemoryDigestAction, MemoryDigestItem,
-    MemoryDigestReviewRequest, MemoryDigestState, PromotionState, RecordOrigin, ReflectionCard,
-    ReflectionCardCreate, ReflectionScores, ResolvedEvidenceRef, SessionTrace, TraceEvent,
-    TraceEventType, TwinContextRecord, TwinExportRequest, TwinInferenceRunSummary, TwinPrediction,
-    TwinPredictionDraft, TwinReviewRecord, UserRecord, UserRecordCreate, UserRecordKind,
-    UserRecordUpdate,
+    DecisionEpisodeCreate, DecisionOutcomeUpdate, EvidenceRef, PrimitiveDecisionAssessment,
+    RecordOrigin, UserRecordCreate,
+};
+use crate::models::twin::{
+    ExportBundle, ExportFileSummary, PromotionState, TraceEventType, TwinExportRequest, UserRecord,
 };
-#[cfg(test)]
-use crate::models::twin::{DecisionMirrorPreset, PrimitiveDecisionAssessment};
 use crate::services::atomic_io::write_atomic;
 use anyhow::{Context, Result};
 use chrono::Utc;
-use serde::de::DeserializeOwned;
-use serde::Serialize;
 use serde_json::{json, Value};
 use std::collections::hash_map::DefaultHasher;
+#[cfg(test)]
 use std::collections::HashMap;
 use std::collections::HashSet;
 use std::hash::{Hash, Hasher};
-use std::path::{Path, PathBuf};
-use std::time::{SystemTime, UNIX_EPOCH};
-use walkdir::WalkDir;
-use super::TwinStore;
-#[cfg(test)]
-use super::decisions::parse_twin_prediction;
+use std::path::Path;
 
 const DEFAULT_EVAL_PERCENTAGE: u8 = 10;
 const DEFAULT_HOLDOUT_PERCENTAGE: u8 = 10;
@@ -390,16 +379,12 @@ impl TwinStore {
         write_atomic(path, content.as_bytes())
             .with_context(|| format!("Failed to write JSONL file: {}", path.display()))
     }
-
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::models::note::{Note, NoteStatus};
-    use crate::models::twin::{
-        default_record_confidence, PromotionState, RecordLink, RecordLinkType, UserRecordKind,
-    };
+    use crate::models::twin::{default_record_confidence, PromotionState, UserRecordKind};
     use tempfile::tempdir;
 
     #[test]
@@ -576,5 +561,4 @@ mod tests {
         assert!(!feedback_content.contains(&private_event.id));
         assert!(feedback_content.contains(&exportable_event.id));
     }
-
 }
diff --git a/frontend/src-tauri/src/services/twin/mod.rs b/frontend/src-tauri/src/services/twin/mod.rs
index 4503b70..68ff052 100644
--- a/frontend/src-tauri/src/services/twin/mod.rs
+++ b/frontend/src-tauri/src/services/twin/mod.rs
@@ -19,11 +19,15 @@
 //! `twin_store.rs` -- callers in `commands/twin.rs` and
 //! `commands/canvas/context.rs` do not need to change.
 
-mod shared;
-mod traces;
-mod records;
 mod constitution;
 mod decisions;
+mod records;
+mod shared;
+mod traces;
+// The mcp binary (grafyn-mcp) compiles this whole module tree but has no
+// caller for this re-export -- only the desktop app's commands/canvas/context.rs
+// imports `crate::services::twin::parse_twin_prediction`.
+#[allow(unused_imports)]
 pub use decisions::parse_twin_prediction;
 mod digest;
 mod export;
@@ -112,5 +116,4 @@ impl TwinStore {
 
         Ok(())
     }
-
 }
diff --git a/frontend/src-tauri/src/services/twin/records.rs b/frontend/src-tauri/src/services/twin/records.rs
index be0b205..c8edff9 100644
--- a/frontend/src-tauri/src/services/twin/records.rs
+++ b/frontend/src-tauri/src/services/twin/records.rs
@@ -1,35 +1,23 @@
-use crate::models::note::Note;
-use crate::models::twin::{
-    ActionGap, ActionGapCreate, ConstitutionInferenceSummary, ConstitutionItem,
-    ConstitutionItemCreate, ConstitutionItemUpdate, ConstitutionReviewRequest, ConstitutionSetup,
-    ConstitutionStatus, DecisionEpisode, DecisionEpisodeCreate, DecisionEpisodeWithReflections,
-    DecisionEvidencePacket, DecisionEvidenceSource, DecisionMirrorConfig,
-    DecisionMirrorConfigUpdate, DecisionMirrorWeights, DecisionOutcomeUpdate, EvidenceRef,
-    ExportBundle, ExportFileSummary, MemoryDigestAction, MemoryDigestItem,
-    MemoryDigestReviewRequest, MemoryDigestState, PromotionState, RecordOrigin, ReflectionCard,
-    ReflectionCardCreate, ReflectionScores, ResolvedEvidenceRef, SessionTrace, TraceEvent,
-    TraceEventType, TwinContextRecord, TwinExportRequest, TwinInferenceRunSummary, TwinPrediction,
-    TwinPredictionDraft, TwinReviewRecord, UserRecord, UserRecordCreate, UserRecordKind,
-    UserRecordUpdate,
+use super::shared::{
+    event_text, evidence_note, excerpt, extract_event_model_id, extract_event_tile_id,
+    lexical_terms, load_or_quarantine, payload_string, text_contains_any, value_contains_key,
 };
+use super::TwinStore;
+use super::{AUTO_PROMOTE_CONFIDENCE, AUTO_PROMOTE_SUPPORT_COUNT};
 #[cfg(test)]
-use crate::models::twin::{DecisionMirrorPreset, PrimitiveDecisionAssessment};
-use crate::services::atomic_io::write_atomic;
+use crate::models::twin::TwinExportRequest;
+use crate::models::twin::{
+    EvidenceRef, PromotionState, RecordOrigin, ResolvedEvidenceRef, SessionTrace, TraceEvent,
+    TraceEventType, TwinContextRecord, TwinInferenceRunSummary, TwinReviewRecord, UserRecord,
+    UserRecordCreate, UserRecordKind, UserRecordUpdate,
+};
 use anyhow::{Context, Result};
 use chrono::Utc;
-use serde::de::DeserializeOwned;
-use serde::Serialize;
 use serde_json::{json, Value};
-use std::collections::hash_map::DefaultHasher;
 use std::collections::HashMap;
 use std::collections::HashSet;
-use std::hash::{Hash, Hasher};
 use std::path::{Path, PathBuf};
-use std::time::{SystemTime, UNIX_EPOCH};
 use walkdir::WalkDir;
-use super::TwinStore;
-use super::shared::{event_text, evidence_note, excerpt, extract_event_model_id, extract_event_tile_id, lexical_terms, load_or_quarantine, payload_string, text_contains_any, value_contains_key};
-use super::{AUTO_PROMOTE_CONFIDENCE, AUTO_PROMOTE_SUPPORT_COUNT};
 
 const TWIN_INFERENCE_VERSION: &str = "local-signal-v1";
 const MAX_TWIN_CANDIDATE_CONTEXT_RECORDS: usize = 8;
@@ -491,7 +479,6 @@ fn looks_implementation_detailed(text: &str) -> bool {
     )
 }
 
-
 impl TwinStore {
     pub fn list_user_records(&mut self) -> Result<Vec<UserRecord>> {
         self.ensure_record_cache()?;
@@ -892,13 +879,11 @@ impl TwinStore {
         let path = self.record_file_path(&record.id);
         self.write_pretty_json(&path, record)
     }
-
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::models::note::{Note, NoteStatus};
     use crate::models::twin::{
         default_record_confidence, PromotionState, RecordLink, RecordLinkType, UserRecordKind,
     };
@@ -1333,5 +1318,4 @@ mod tests {
         assert!(fallback.len() <= MAX_TWIN_APPROVED_FALLBACK_RECORDS);
         assert!(fallback[0].content.contains("woodworking"));
     }
-
 }
diff --git a/frontend/src-tauri/src/services/twin/shared.rs b/frontend/src-tauri/src/services/twin/shared.rs
index 52e814b..d2a290c 100644
--- a/frontend/src-tauri/src/services/twin/shared.rs
+++ b/frontend/src-tauri/src/services/twin/shared.rs
@@ -1,33 +1,22 @@
+#[cfg(test)]
 use super::TwinStore;
-use crate::models::note::Note;
+#[cfg(test)]
 use crate::models::twin::{
-    ActionGap, ActionGapCreate, ConstitutionInferenceSummary, ConstitutionItem,
-    ConstitutionItemCreate, ConstitutionItemUpdate, ConstitutionReviewRequest, ConstitutionSetup,
-    ConstitutionStatus, DecisionEpisode, DecisionEpisodeCreate, DecisionEpisodeWithReflections,
-    DecisionEvidencePacket, DecisionEvidenceSource, DecisionMirrorConfig,
-    DecisionMirrorConfigUpdate, DecisionMirrorWeights, DecisionOutcomeUpdate, EvidenceRef,
-    ExportBundle, ExportFileSummary, MemoryDigestAction, MemoryDigestItem,
-    MemoryDigestReviewRequest, MemoryDigestState, PromotionState, RecordOrigin, ReflectionCard,
-    ReflectionCardCreate, ReflectionScores, ResolvedEvidenceRef, SessionTrace, TraceEvent,
-    TraceEventType, TwinContextRecord, TwinExportRequest, TwinInferenceRunSummary, TwinPrediction,
-    TwinPredictionDraft, TwinReviewRecord, UserRecord, UserRecordCreate, UserRecordKind,
-    UserRecordUpdate,
+    ActionGapCreate, ConstitutionItemCreate, ConstitutionStatus, DecisionEpisodeCreate,
+    PrimitiveDecisionAssessment, RecordOrigin, ReflectionCardCreate, UserRecord,
 };
+use crate::models::twin::{TraceEvent, TraceEventType};
 #[cfg(test)]
-use crate::models::twin::{DecisionMirrorPreset, PrimitiveDecisionAssessment};
-use crate::services::atomic_io::write_atomic;
-use anyhow::{Context, Result};
 use chrono::Utc;
 use serde::de::DeserializeOwned;
-use serde::Serialize;
-use serde_json::{json, Value};
-use std::collections::hash_map::DefaultHasher;
+#[cfg(test)]
+use serde_json::json;
+use serde_json::Value;
+#[cfg(test)]
 use std::collections::HashMap;
 use std::collections::HashSet;
-use std::hash::{Hash, Hasher};
-use std::path::{Path, PathBuf};
+use std::path::Path;
 use std::time::{SystemTime, UNIX_EPOCH};
-use walkdir::WalkDir;
 
 const EXCERPT_MAX_CHARS: usize = 220;
 
@@ -251,10 +240,7 @@ pub(super) fn excerpt(content: &str) -> String {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::models::note::{Note, NoteStatus};
-    use crate::models::twin::{
-        default_record_confidence, PromotionState, RecordLink, RecordLinkType, UserRecordKind,
-    };
+    use crate::models::twin::{default_record_confidence, PromotionState, UserRecordKind};
     use tempfile::tempdir;
 
     /// Corrupt-file quarantine sweep (Task 1.5): a directory listing must never brick
diff --git a/frontend/src-tauri/src/services/twin/traces.rs b/frontend/src-tauri/src/services/twin/traces.rs
index 4ff2487..3931fd1 100644
--- a/frontend/src-tauri/src/services/twin/traces.rs
+++ b/frontend/src-tauri/src/services/twin/traces.rs
@@ -3,34 +3,16 @@ use super::shared::{
     load_or_quarantine, payload_string,
 };
 use super::TwinStore;
-use crate::models::note::Note;
 use crate::models::twin::{
-    ActionGap, ActionGapCreate, ConstitutionInferenceSummary, ConstitutionItem,
-    ConstitutionItemCreate, ConstitutionItemUpdate, ConstitutionReviewRequest, ConstitutionSetup,
-    ConstitutionStatus, DecisionEpisode, DecisionEpisodeCreate, DecisionEpisodeWithReflections,
-    DecisionEvidencePacket, DecisionEvidenceSource, DecisionMirrorConfig,
-    DecisionMirrorConfigUpdate, DecisionMirrorWeights, DecisionOutcomeUpdate, EvidenceRef,
-    ExportBundle, ExportFileSummary, MemoryDigestAction, MemoryDigestItem,
-    MemoryDigestReviewRequest, MemoryDigestState, PromotionState, RecordOrigin, ReflectionCard,
-    ReflectionCardCreate, ReflectionScores, ResolvedEvidenceRef, SessionTrace, TraceEvent,
-    TraceEventType, TwinContextRecord, TwinExportRequest, TwinInferenceRunSummary, TwinPrediction,
-    TwinPredictionDraft, TwinReviewRecord, UserRecord, UserRecordCreate, UserRecordKind,
-    UserRecordUpdate,
+    EvidenceRef, ResolvedEvidenceRef, SessionTrace, TraceEvent, TraceEventType,
 };
 #[cfg(test)]
-use crate::models::twin::{DecisionMirrorPreset, PrimitiveDecisionAssessment};
-use crate::services::atomic_io::write_atomic;
+use crate::models::twin::{RecordOrigin, UserRecordCreate};
 use anyhow::{Context, Result};
 use chrono::Utc;
-use serde::de::DeserializeOwned;
-use serde::Serialize;
-use serde_json::{json, Value};
-use std::collections::hash_map::DefaultHasher;
+#[cfg(test)]
 use std::collections::HashMap;
-use std::collections::HashSet;
-use std::hash::{Hash, Hasher};
 use std::path::{Path, PathBuf};
-use std::time::{SystemTime, UNIX_EPOCH};
 use walkdir::WalkDir;
 
 fn resolve_event_evidence(
@@ -273,10 +255,7 @@ impl TwinStore {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::models::note::{Note, NoteStatus};
-    use crate::models::twin::{
-        default_record_confidence, PromotionState, RecordLink, RecordLinkType, UserRecordKind,
-    };
+    use crate::models::twin::{PromotionState, UserRecordKind};
     use tempfile::tempdir;
 
     #[test]

From c162a4e88bdc0dbd3c8d5129523061d71efa0c24 Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 16:44:42 +0800
Subject: [PATCH 17/30] fix: take write lock for twin store read-modify-write
 commands

update_decision_mirror_config, create_constitution_item, and
update_constitution_item took twin_store.read() despite update_constitution_item
and update_decision_mirror_config doing a read-modify-write file sequence
(read current file, apply the update, write the whole thing back). Two
concurrent calls under a shared read lock can both read the same
pre-update state; the second writer then silently clobbers the first's
change. Switches all three to .write() so the read-modify-write sequence
is fully serialized.

Adds a regression test demonstrating that two concurrent
update_constitution_item calls to the same item -- one changing claim,
the other priority -- both persist under the write lock instead of one
clobbering the other.
---
 frontend/src-tauri/src/commands/twin.rs | 113 +++++++++++++++++++++++-
 1 file changed, 110 insertions(+), 3 deletions(-)

diff --git a/frontend/src-tauri/src/commands/twin.rs b/frontend/src-tauri/src/commands/twin.rs
index dcdf6e0..84198d3 100644
--- a/frontend/src-tauri/src/commands/twin.rs
+++ b/frontend/src-tauri/src/commands/twin.rs
@@ -148,7 +148,10 @@ pub async fn update_decision_mirror_config(
     update: DecisionMirrorConfigUpdate,
     state: State<'_, AppState>,
 ) -> Result<DecisionMirrorConfig, String> {
-    let store = state.twin_store.read().await;
+    // Read-modify-write over the config file: must hold the write lock so two
+    // concurrent updates can't both read the same on-disk state and have the
+    // second writer silently clobber the first's change.
+    let store = state.twin_store.write().await;
     store
         .update_decision_mirror_config(update)
         .map_err(|error| error.to_string())
@@ -201,7 +204,9 @@ pub async fn create_constitution_item(
     item: ConstitutionItemCreate,
     state: State<'_, AppState>,
 ) -> Result<ConstitutionItem, String> {
-    let store = state.twin_store.read().await;
+    // Write lock: create_constitution_item does a read-modify-write file
+    // sequence (see update_decision_mirror_config above for why read() is unsafe here).
+    let store = state.twin_store.write().await;
     store
         .create_constitution_item(item)
         .map_err(|error| error.to_string())
@@ -213,7 +218,11 @@ pub async fn update_constitution_item(
     update: ConstitutionItemUpdate,
     state: State<'_, AppState>,
 ) -> Result<ConstitutionItem, String> {
-    let store = state.twin_store.read().await;
+    // Write lock: update_constitution_item reads the current item file, applies the
+    // update, then writes it back. Two concurrent updates to the same item under a
+    // shared read lock could both read the pre-update file and the second writer
+    // would silently clobber the first's change.
+    let store = state.twin_store.write().await;
     store
         .update_constitution_item(&id, update)
         .map_err(|error| error.to_string())
@@ -669,3 +678,101 @@ fn excerpt(content: &str) -> String {
     excerpt.push_str("...");
     excerpt
 }
+
+#[cfg(test)]
+mod tests {
+    use crate::models::twin::{ConstitutionItemCreate, ConstitutionItemUpdate};
+    use crate::services::twin::TwinStore;
+    use std::sync::Arc;
+    use tempfile::tempdir;
+    use tokio::sync::RwLock;
+
+    /// Regression test for the read-modify-write lock fix: `update_constitution_item`
+    /// reads the current item file, applies the update's `Some` fields, and writes the
+    /// whole item back. Two concurrent updates to the *same* item under a shared read
+    /// lock (the pre-fix behavior) could both read the same pre-update file and the
+    /// second writer would silently clobber the first's change — a classic lost
+    /// update. With the write lock in place, `Arc<RwLock<TwinStore>>::write().await`
+    /// fully serializes the two calls (tokio's RwLock allows only one writer at a
+    /// time, with no `.await` point inside `update_constitution_item` for the second
+    /// task to interleave into), so both edits — one to `claim`, the other to
+    /// `priority` — must survive.
+    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+    async fn concurrent_constitution_updates_do_not_lose_a_write() {
+        let temp_dir = tempdir().expect("temp dir should be created");
+        let store = Arc::new(RwLock::new(TwinStore::new(temp_dir.path().to_path_buf())));
+
+        let item = {
+            let guard = store.read().await;
+            guard
+                .create_constitution_item(ConstitutionItemCreate {
+                    claim: "Original claim".to_string(),
+                    dimension: "values".to_string(),
+                    scope: vec!["general".to_string()],
+                    priority: 0.5,
+                    confidence: 0.5,
+                    status: Default::default(),
+                    evidence_refs: Vec::new(),
+                    tensions: Vec::new(),
+                    linked_record_ids: Vec::new(),
+                    source: None,
+                })
+                .expect("constitution item should be created")
+        };
+
+        let store_a = store.clone();
+        let item_id_a = item.id.clone();
+        let claim_update = tokio::spawn(async move {
+            // Mirrors the fixed `update_constitution_item` command: acquire the
+            // write lock for the whole read-modify-write sequence.
+            let guard = store_a.write().await;
+            guard
+                .update_constitution_item(
+                    &item_id_a,
+                    ConstitutionItemUpdate {
+                        claim: Some("Updated claim".to_string()),
+                        ..Default::default()
+                    },
+                )
+                .expect("claim update should persist")
+        });
+
+        let store_b = store.clone();
+        let item_id_b = item.id.clone();
+        let priority_update = tokio::spawn(async move {
+            let guard = store_b.write().await;
+            guard
+                .update_constitution_item(
+                    &item_id_b,
+                    ConstitutionItemUpdate {
+                        priority: Some(0.9),
+                        ..Default::default()
+                    },
+                )
+                .expect("priority update should persist")
+        });
+
+        let (a, b) = tokio::join!(claim_update, priority_update);
+        a.expect("claim-update task panicked");
+        b.expect("priority-update task panicked");
+
+        let final_item = {
+            let guard = store.read().await;
+            guard
+                .list_constitution_items()
+                .expect("constitution items should list")
+                .into_iter()
+                .find(|candidate| candidate.id == item.id)
+                .expect("updated item should still exist")
+        };
+
+        assert_eq!(
+            final_item.claim, "Updated claim",
+            "claim update must not be lost to the concurrent priority update"
+        );
+        assert_eq!(
+            final_item.priority, 0.9,
+            "priority update must not be lost to the concurrent claim update"
+        );
+    }
+}

From e106a4e538216797505b8c3b0c7778817ccb3c81 Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 17:04:19 +0800
Subject: [PATCH 18/30] fix: restore #[derive(Debug)] dropped from TwinStore in
 the split

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 frontend/src-tauri/src/services/twin/mod.rs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/frontend/src-tauri/src/services/twin/mod.rs b/frontend/src-tauri/src/services/twin/mod.rs
index 68ff052..3021b8a 100644
--- a/frontend/src-tauri/src/services/twin/mod.rs
+++ b/frontend/src-tauri/src/services/twin/mod.rs
@@ -42,6 +42,7 @@ use std::path::{Path, PathBuf};
 const AUTO_PROMOTE_CONFIDENCE: f32 = 0.75;
 const AUTO_PROMOTE_SUPPORT_COUNT: usize = 3;
 
+#[derive(Debug)]
 pub struct TwinStore {
     root_path: PathBuf,
     traces_path: PathBuf,

From 444fbd42b9839d5798f4c91e35cb2c50added288 Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 17:21:47 +0800
Subject: [PATCH 19/30] refactor: add stores/twin.js scaffold for Twin
 Workspace decomposition

Adds the Pinia store, shared formatting utils, and shared stylesheet that
TwinReviewView.vue's tabs will be migrated onto in follow-up commits
(Task 4.3). Not yet wired into the view.
---
 .../src/__tests__/unit/stores/twin.spec.js    | 208 ++++
 .../src/components/twin/twin-workspace.css    | 944 ++++++++++++++++++
 frontend/src/stores/twin.js                   | 355 +++++++
 frontend/src/utils/twinFormat.js              | 184 ++++
 4 files changed, 1691 insertions(+)
 create mode 100644 frontend/src/__tests__/unit/stores/twin.spec.js
 create mode 100644 frontend/src/components/twin/twin-workspace.css
 create mode 100644 frontend/src/stores/twin.js
 create mode 100644 frontend/src/utils/twinFormat.js

diff --git a/frontend/src/__tests__/unit/stores/twin.spec.js b/frontend/src/__tests__/unit/stores/twin.spec.js
new file mode 100644
index 0000000..4d6d446
--- /dev/null
+++ b/frontend/src/__tests__/unit/stores/twin.spec.js
@@ -0,0 +1,208 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { createPinia, setActivePinia } from 'pinia'
+import { useTwinStore } from '@/stores/twin'
+import * as apiClient from '@/api/client'
+
+describe('Twin Store', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    vi.restoreAllMocks()
+    localStorage.clear()
+  })
+
+  it('loadWorkspace loads records, digest, constitution, gaps, decisions, setup, and config', async () => {
+    vi.spyOn(apiClient.twin, 'getReview').mockResolvedValue([
+      { record: { id: 'r1', promotion_state: 'candidate' }, evidence_count: 1 }
+    ])
+    vi.spyOn(apiClient.twin, 'listMemoryDigest').mockResolvedValue([{ id: 'd1' }])
+    vi.spyOn(apiClient.twin, 'listConstitutionItems').mockResolvedValue([
+      { id: 'c1', dimension: 'values', status: 'active' }
+    ])
+    vi.spyOn(apiClient.twin, 'listActionGaps').mockResolvedValue([{ id: 'g1', status: 'candidate' }])
+    vi.spyOn(apiClient.twin, 'listDecisionEpisodes').mockResolvedValue([
+      { episode: { id: 'e1', outcome: null } }
+    ])
+    vi.spyOn(apiClient.twin, 'getConstitutionSetup').mockResolvedValue({
+      twin_name: 'Alex',
+      twin_role: 'founder',
+      values: ['evidence-backed work']
+    })
+    vi.spyOn(apiClient.twin, 'getDecisionMirrorConfig').mockResolvedValue({
+      preset: 'evidence_strict',
+      advanced_enabled: true,
+      weights: { notes_weight: 2 }
+    })
+
+    const store = useTwinStore()
+    await store.loadWorkspace()
+
+    expect(store.reviewRecords).toHaveLength(1)
+    expect(store.memoryDigestItems).toHaveLength(1)
+    expect(store.constitutionItems).toHaveLength(1)
+    expect(store.actionGaps).toHaveLength(1)
+    expect(store.decisions).toHaveLength(1)
+    expect(store.setupDraft.twin_name).toBe('Alex')
+    expect(store.setupDraft.values).toBe('evidence-backed work')
+    expect(store.configDraft.preset).toBe('evidence_strict')
+    expect(store.configDraft.advanced_enabled).toBe(true)
+    expect(store.configDraft.weights.notes_weight).toBe(2)
+    // defaults still merged in for weights not present in the response
+    expect(store.configDraft.weights.action_gaps_weight).toBe(1)
+    expect(store.activeConstitutionCount).toBe(1)
+    expect(store.activeActionGapCount).toBe(1)
+    expect(store.pendingReviewCount).toBe(2)
+    expect(store.pendingOutcomeCount).toBe(1)
+    expect(store.healthSummary).toBe('1 principles / 1 gaps / 1 decisions')
+  })
+
+  it('loadWorkspace sets an error message when the API call fails', async () => {
+    vi.spyOn(apiClient.twin, 'getReview').mockRejectedValue(new Error('boom'))
+    vi.spyOn(apiClient.twin, 'listMemoryDigest').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'listConstitutionItems').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'listActionGaps').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'listDecisionEpisodes').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'getConstitutionSetup').mockResolvedValue({})
+    vi.spyOn(apiClient.twin, 'getDecisionMirrorConfig').mockResolvedValue({})
+
+    const store = useTwinStore()
+    await store.loadWorkspace()
+
+    expect(store.message).toEqual({ type: 'error', text: 'boom' })
+  })
+
+  it('reviewConstitutionItem calls the api with the given action and reloads', async () => {
+    vi.spyOn(apiClient.twin, 'getReview').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'listMemoryDigest').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'listConstitutionItems').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'listActionGaps').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'listDecisionEpisodes').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'getConstitutionSetup').mockResolvedValue({})
+    vi.spyOn(apiClient.twin, 'getDecisionMirrorConfig').mockResolvedValue({})
+    const reviewSpy = vi.spyOn(apiClient.twin, 'reviewConstitutionItem').mockResolvedValue({})
+
+    const store = useTwinStore()
+    await store.reviewConstitutionItem('c1', 'keep')
+
+    expect(reviewSpy).toHaveBeenCalledWith('c1', { action: 'keep' })
+    expect(store.message.type).toBe('success')
+  })
+
+  it('reviewConstitutionItem sets an error message on failure', async () => {
+    vi.spyOn(apiClient.twin, 'reviewConstitutionItem').mockRejectedValue(new Error('nope'))
+
+    const store = useTwinStore()
+    await store.reviewConstitutionItem('c1', 'keep')
+
+    expect(store.message).toEqual({ type: 'error', text: 'nope' })
+  })
+
+  it('reviewActionGap and reviewMemoryDigestItem call their respective api functions', async () => {
+    vi.spyOn(apiClient.twin, 'getReview').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'listMemoryDigest').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'listConstitutionItems').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'listActionGaps').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'listDecisionEpisodes').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'getConstitutionSetup').mockResolvedValue({})
+    vi.spyOn(apiClient.twin, 'getDecisionMirrorConfig').mockResolvedValue({})
+    const gapSpy = vi.spyOn(apiClient.twin, 'reviewActionGap').mockResolvedValue({})
+    const digestSpy = vi.spyOn(apiClient.twin, 'reviewMemoryDigestItem').mockResolvedValue({})
+
+    const store = useTwinStore()
+    await store.reviewActionGap('g1', 'soften')
+    await store.reviewMemoryDigestItem('d1', 'reject')
+
+    expect(gapSpy).toHaveBeenCalledWith('g1', { action: 'soften' })
+    expect(digestSpy).toHaveBeenCalledWith('d1', { action: 'reject' })
+  })
+
+  it('setPromotion calls the api and reports the new state', async () => {
+    vi.spyOn(apiClient.twin, 'getReview').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'listMemoryDigest').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'listConstitutionItems').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'listActionGaps').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'listDecisionEpisodes').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'getConstitutionSetup').mockResolvedValue({})
+    vi.spyOn(apiClient.twin, 'getDecisionMirrorConfig').mockResolvedValue({})
+    const promoSpy = vi.spyOn(apiClient.twin, 'setPromotion').mockResolvedValue({})
+
+    const store = useTwinStore()
+    await store.setPromotion('r1', 'endorsed')
+
+    expect(promoSpy).toHaveBeenCalledWith('r1', 'endorsed', null)
+    expect(store.message.text).toBe('Set record to Endorsed')
+  })
+
+  it('openEvidence loads evidence for a record and tracks loading state', async () => {
+    let resolveEvidence
+    vi.spyOn(apiClient.twin, 'resolveEvidence').mockImplementation(() => new Promise(resolve => {
+      resolveEvidence = resolve
+    }))
+
+    const store = useTwinStore()
+    const promise = store.openEvidence('r1')
+    expect(store.selectedRecordId).toBe('r1')
+    expect(store.evidenceLoading).toBe(true)
+
+    resolveEvidence([{ event_id: 'evt-1' }])
+    await promise
+
+    expect(store.evidenceLoading).toBe(false)
+    expect(store.selectedEvidence).toEqual([{ event_id: 'evt-1' }])
+  })
+
+  it('openEvidence sets an error message and stops loading on failure', async () => {
+    vi.spyOn(apiClient.twin, 'resolveEvidence').mockRejectedValue(new Error('evidence failed'))
+
+    const store = useTwinStore()
+    await store.openEvidence('r1')
+
+    expect(store.evidenceLoading).toBe(false)
+    expect(store.message).toEqual({ type: 'error', text: 'evidence failed' })
+  })
+
+  it('saveSetup splits textarea drafts into arrays before calling the api', async () => {
+    vi.spyOn(apiClient.twin, 'getReview').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'listMemoryDigest').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'listConstitutionItems').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'listActionGaps').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'listDecisionEpisodes').mockResolvedValue([])
+    vi.spyOn(apiClient.twin, 'getConstitutionSetup').mockResolvedValue({})
+    vi.spyOn(apiClient.twin, 'getDecisionMirrorConfig').mockResolvedValue({})
+    const saveSpy = vi.spyOn(apiClient.twin, 'saveConstitutionSetup').mockResolvedValue({})
+
+    const store = useTwinStore()
+    store.setupDraft.twin_name = ' Alex Chen '
+    store.setupDraft.twin_role = ' founder '
+    store.setupDraft.values = 'evidence-backed work\nfast feedback'
+
+    await store.saveSetup()
+
+    expect(saveSpy).toHaveBeenCalledWith(expect.objectContaining({
+      twin_name: 'Alex Chen',
+      twin_role: 'founder',
+      values: ['evidence-backed work', 'fast feedback']
+    }))
+  })
+
+  it('dismissTutorial persists the dismissal and clears the intro flag', () => {
+    const store = useTwinStore()
+    expect(store.showTutorialIntro).toBe(true)
+
+    store.dismissTutorial()
+
+    expect(store.showTutorialIntro).toBe(false)
+    expect(localStorage.getItem('grafyn.twinWorkspaceTutorial.dismissed')).toBe('true')
+  })
+
+  it('exportDecisionBenchmark reports the exported decision count', async () => {
+    vi.spyOn(apiClient.twin, 'exportData').mockResolvedValue({
+      decision_mirror_benchmark: { count: 4 }
+    })
+
+    const store = useTwinStore()
+    await store.exportDecisionBenchmark()
+
+    expect(store.message.text).toBe('Exported benchmark: 4 decisions')
+    expect(store.exportingBenchmark).toBe(false)
+  })
+})
diff --git a/frontend/src/components/twin/twin-workspace.css b/frontend/src/components/twin/twin-workspace.css
new file mode 100644
index 0000000..43a2780
--- /dev/null
+++ b/frontend/src/components/twin/twin-workspace.css
@@ -0,0 +1,944 @@
+.twin-workspace {
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+  overflow: hidden;
+  background: var(--bg-primary);
+  color: var(--text-primary);
+}
+
+.twin-workspace .workspace-header {
+  flex: 0 0 auto;
+  display: grid;
+  grid-template-columns: 1fr auto 1fr;
+  align-items: center;
+  gap: var(--spacing-md);
+  padding: var(--spacing-sm) var(--spacing-lg);
+  border-bottom: 1px solid var(--border-default);
+  background: var(--bg-secondary);
+}
+
+.twin-workspace .header-links,
+.twin-workspace .header-actions {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-sm);
+}
+
+.twin-workspace .header-actions {
+  justify-content: flex-end;
+}
+
+.twin-workspace .header-actions.compact {
+  gap: 6px;
+}
+
+.twin-workspace .header-links a {
+  color: var(--text-secondary);
+  text-decoration: none;
+}
+
+.twin-workspace .header-links a:hover {
+  color: var(--accent-primary);
+}
+
+.twin-workspace .header-title {
+  text-align: center;
+}
+
+.twin-workspace .header-title h1 {
+  margin: 0;
+  font-size: 1.125rem;
+}
+
+.twin-workspace .header-title span,
+.twin-workspace .panel-header span,
+.twin-workspace .card-topline,
+.twin-workspace .metric-tile small,
+.twin-workspace .evidence-item small,
+.twin-workspace .digest-card small,
+.twin-workspace .muted {
+  color: var(--text-muted);
+  font-size: 0.75rem;
+}
+
+.twin-workspace .header-title span {
+  font-family: 'Fira Code', monospace;
+  font-size: 0.7rem;
+  letter-spacing: 0.02em;
+}
+
+/* Body: fixed rail + independently scrolling main pane.
+   #app is overflow:hidden, so this view must own its scrolling. */
+.twin-workspace .workspace-body {
+  flex: 1;
+  display: flex;
+  min-height: 0;
+}
+
+.twin-workspace .workspace-rail {
+  flex: 0 0 212px;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  padding: var(--spacing-sm) var(--spacing-sm) var(--spacing-lg) 0;
+  overflow-y: auto;
+  border-right: 1px solid var(--border-default);
+  background: var(--bg-secondary);
+}
+
+.twin-workspace .rail-label {
+  margin: var(--spacing-md) var(--spacing-sm) 4px var(--spacing-md);
+  font-size: 0.65rem;
+  font-weight: 700;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+  color: var(--text-muted);
+}
+
+.twin-workspace .tab-button {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  width: 100%;
+  min-height: 34px;
+  padding: 0 var(--spacing-sm) 0 13px;
+  border: none;
+  border-left: 3px solid transparent;
+  border-radius: 0 var(--radius-sm) var(--radius-sm) 0;
+  background: transparent;
+  color: var(--text-secondary);
+  font-size: 0.85rem;
+  text-align: left;
+  cursor: pointer;
+  transition: background var(--transition-fast), color var(--transition-fast);
+}
+
+.twin-workspace .tab-button:hover {
+  background: var(--bg-hover);
+  color: var(--text-primary);
+}
+
+.twin-workspace .tab-button.active {
+  border-left-color: var(--accent-primary);
+  background: color-mix(in srgb, var(--accent-primary) 12%, transparent);
+  color: var(--accent-primary);
+  font-weight: 600;
+}
+
+.twin-workspace .tab-button strong {
+  min-width: 22px;
+  font-family: 'Fira Code', monospace;
+  font-size: 0.7rem;
+  font-weight: 500;
+  text-align: right;
+  color: var(--text-muted);
+}
+
+.twin-workspace .tab-button.active strong {
+  color: var(--accent-primary);
+}
+
+.twin-workspace .workspace-main {
+  flex: 1;
+  min-width: 0;
+  overflow-y: auto;
+  padding: var(--spacing-lg);
+}
+
+.twin-workspace .tab-panel {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-md);
+  max-width: 980px;
+  margin: 0 auto;
+}
+
+.twin-workspace .overview-stats {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: var(--spacing-md);
+}
+
+.twin-workspace .metric-tile {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 2px;
+  padding: var(--spacing-md);
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-lg);
+  background: var(--bg-secondary);
+  color: var(--text-secondary);
+  text-align: left;
+  cursor: pointer;
+  transition: border-color var(--transition-fast), box-shadow var(--transition-fast), transform var(--transition-fast);
+}
+
+.twin-workspace .metric-tile:hover {
+  border-color: var(--accent-primary);
+  box-shadow: var(--shadow-md);
+  transform: translateY(-1px);
+}
+
+.twin-workspace .metric-tile strong {
+  display: block;
+  margin: 4px 0;
+  font-family: 'Fira Code', monospace;
+  font-size: 1.8rem;
+  font-weight: 600;
+  color: var(--text-primary);
+  line-height: 1.1;
+}
+
+.twin-workspace .workspace-band,
+.twin-workspace .constitution-card,
+.twin-workspace .action-gap-card,
+.twin-workspace .decision-card,
+.twin-workspace .digest-card,
+.twin-workspace .record-card,
+.twin-workspace .evidence-drawer {
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-md);
+  background: var(--bg-secondary);
+}
+
+.twin-workspace .workspace-band {
+  padding: var(--spacing-md);
+}
+
+.twin-workspace .tutorial-intro {
+  border-left: 3px solid var(--accent-primary);
+}
+
+.twin-workspace .band-header,
+.twin-workspace .panel-header,
+.twin-workspace .card-topline,
+.twin-workspace .drawer-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--spacing-sm);
+}
+
+.twin-workspace .band-header {
+  margin-bottom: var(--spacing-sm);
+}
+
+.twin-workspace .panel-header h2,
+.twin-workspace .band-header h2,
+.twin-workspace .drawer-header h2 {
+  margin: 0;
+  font-size: 1rem;
+}
+
+.twin-workspace .panel-header.compact {
+  margin-bottom: var(--spacing-sm);
+}
+
+.twin-workspace .text-button,
+.twin-workspace .record-actions button,
+.twin-workspace .review-actions button,
+.twin-workspace .drawer-header button {
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-sm);
+  background: transparent;
+  color: var(--text-secondary);
+  cursor: pointer;
+}
+
+.twin-workspace .text-button {
+  border: none;
+  color: var(--accent-primary);
+}
+
+.twin-workspace .empty-panel {
+  padding: var(--spacing-lg);
+  border: 1px dashed var(--border-default);
+  border-radius: var(--radius-md);
+  color: var(--text-muted);
+  text-align: center;
+}
+
+/* Compact triage rows on the overview */
+.twin-workspace .compact-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  padding: 8px 10px;
+  margin-bottom: 6px;
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-sm);
+  background: transparent;
+  color: var(--text-primary);
+  text-align: left;
+  cursor: pointer;
+  transition: border-color var(--transition-fast), background var(--transition-fast);
+}
+
+.twin-workspace .compact-row:hover {
+  border-color: var(--accent-primary);
+  background: var(--bg-hover);
+}
+
+.twin-workspace .compact-row.highlighted {
+  border-color: var(--accent-cyan);
+}
+
+.twin-workspace .row-dot {
+  flex: 0 0 8px;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--text-muted);
+}
+
+.twin-workspace .row-dot.is-sealed {
+  background: var(--accent-primary);
+}
+
+.twin-workspace .row-dot.is-pending {
+  background: var(--accent-warning);
+}
+
+.twin-workspace .row-dot.is-match {
+  background: var(--accent-green);
+}
+
+.twin-workspace .row-dot.is-miss {
+  background: var(--accent-red);
+}
+
+.twin-workspace .row-title {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 0.85rem;
+}
+
+.twin-workspace .row-chips,
+.twin-workspace .topline-chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+}
+
+.twin-workspace .chip {
+  display: inline-flex;
+  align-items: center;
+  padding: 1px 8px;
+  border: 1px solid var(--border-default);
+  border-radius: 999px;
+  font-size: 0.68rem;
+  font-weight: 600;
+  color: var(--text-secondary);
+  white-space: nowrap;
+}
+
+.twin-workspace .chip-sealed {
+  border-style: dashed;
+  border-color: color-mix(in srgb, var(--accent-primary) 55%, transparent);
+  color: var(--accent-primary);
+}
+
+.twin-workspace .chip-pending {
+  border-color: color-mix(in srgb, var(--accent-warning) 55%, transparent);
+  background: color-mix(in srgb, var(--accent-warning) 10%, transparent);
+  color: var(--accent-warning);
+}
+
+.twin-workspace .chip-match {
+  border-color: color-mix(in srgb, var(--accent-green) 55%, transparent);
+  background: color-mix(in srgb, var(--accent-green) 10%, transparent);
+  color: var(--accent-green);
+}
+
+.twin-workspace .chip-miss {
+  border-color: color-mix(in srgb, var(--accent-red) 55%, transparent);
+  background: color-mix(in srgb, var(--accent-red) 10%, transparent);
+  color: var(--accent-red);
+}
+
+.twin-workspace .dimension-section h3 {
+  margin: 0 0 var(--spacing-sm);
+  font-size: 0.875rem;
+  color: var(--text-secondary);
+}
+
+.twin-workspace .constitution-card,
+.twin-workspace .action-gap-card,
+.twin-workspace .decision-card,
+.twin-workspace .digest-card,
+.twin-workspace .record-card {
+  padding: var(--spacing-md);
+  margin-bottom: var(--spacing-sm);
+}
+
+/* Decision cards carry their state on the left edge */
+.twin-workspace .decision-card {
+  border-left: 3px solid var(--border-strong);
+}
+
+.twin-workspace .decision-card.is-sealed {
+  border-left-color: var(--accent-primary);
+}
+
+.twin-workspace .decision-card.is-pending {
+  border-left-color: var(--accent-warning);
+}
+
+.twin-workspace .decision-card.is-match {
+  border-left-color: var(--accent-green);
+}
+
+.twin-workspace .decision-card.is-miss {
+  border-left-color: var(--accent-red);
+}
+
+.twin-workspace .decision-card.highlighted {
+  border-color: var(--accent-cyan);
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--accent-cyan) 18%, transparent);
+}
+
+.twin-workspace .decision-card h3 {
+  font-size: 0.95rem;
+  line-height: 1.4;
+}
+
+.twin-workspace .constitution-card p,
+.twin-workspace .action-gap-card p,
+.twin-workspace .decision-card h3,
+.twin-workspace .digest-card p,
+.twin-workspace .record-card p,
+.twin-workspace .evidence-item p {
+  margin: var(--spacing-sm) 0;
+}
+
+.twin-workspace .card-topline {
+  flex-wrap: wrap;
+  justify-content: flex-start;
+}
+
+.twin-workspace .card-topline .topline-chips {
+  margin-left: auto;
+}
+
+.twin-workspace .status-pill,
+.twin-workspace .tag-row span,
+.twin-workspace .source-row span {
+  display: inline-flex;
+  align-items: center;
+  min-height: 22px;
+  padding: 0 7px;
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-sm);
+  color: var(--text-secondary);
+  font-size: 0.6875rem;
+}
+
+.twin-workspace .tag-row,
+.twin-workspace .source-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+}
+
+.twin-workspace .review-actions,
+.twin-workspace .record-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin-top: var(--spacing-sm);
+}
+
+.twin-workspace .prediction-sealed-badge {
+  margin-top: var(--spacing-sm);
+  padding: 6px 10px;
+  border: 1px dashed color-mix(in srgb, var(--accent-primary) 45%, transparent);
+  border-radius: var(--radius-sm);
+  color: var(--accent-primary);
+  font-size: 0.8rem;
+}
+
+.twin-workspace .prediction-reveal {
+  margin-top: var(--spacing-sm);
+  padding: var(--spacing-sm);
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-sm);
+  background: color-mix(in srgb, var(--bg-tertiary) 75%, transparent);
+}
+
+.twin-workspace .prediction-headline {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 6px;
+  font-size: 0.85rem;
+}
+
+.twin-workspace .prediction-confidence {
+  color: var(--text-secondary);
+}
+
+.twin-workspace .prediction-rationale {
+  margin: 6px 0 0;
+  color: var(--text-secondary);
+  font-size: 0.8rem;
+}
+
+.twin-workspace .agreement-badge {
+  padding: 2px 8px;
+  border-radius: 999px;
+  font-size: 0.72rem;
+}
+
+.twin-workspace .agreement-badge.match {
+  background: color-mix(in srgb, var(--accent-green, #22c55e) 18%, transparent);
+  color: var(--accent-green, #22c55e);
+}
+
+.twin-workspace .agreement-badge.miss {
+  background: color-mix(in srgb, var(--accent-red, #ef4444) 18%, transparent);
+  color: var(--accent-red, #ef4444);
+}
+
+.twin-workspace .review-actions button,
+.twin-workspace .record-actions button {
+  min-height: 28px;
+  padding: 4px 8px;
+}
+
+.twin-workspace .review-actions button:hover,
+.twin-workspace .record-actions button:hover {
+  border-color: var(--accent-primary);
+  color: var(--accent-primary);
+}
+
+.twin-workspace .gap-columns {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: var(--spacing-md);
+}
+
+.twin-workspace .gap-columns small {
+  color: var(--text-muted);
+}
+
+.twin-workspace .primitive-grid {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin: var(--spacing-sm) 0;
+}
+
+.twin-workspace .primitive-grid span {
+  padding: 4px 8px;
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-sm);
+  color: var(--text-secondary);
+  font-size: 0.75rem;
+}
+
+.twin-workspace .reflection-details {
+  margin-top: var(--spacing-sm);
+}
+
+.twin-workspace .context-trace-details {
+  margin-top: var(--spacing-sm);
+  border-top: 1px solid var(--border-subtle);
+  padding-top: var(--spacing-sm);
+}
+
+.twin-workspace .context-trace-details summary,
+.twin-workspace .reflection-details summary,
+.twin-workspace .outcome-details summary {
+  cursor: pointer;
+  font-weight: 700;
+}
+
+.twin-workspace .reflection-details pre {
+  max-height: 220px;
+  overflow: auto;
+  white-space: pre-wrap;
+  padding: var(--spacing-sm);
+  background: var(--bg-tertiary);
+  border-radius: var(--radius-sm);
+}
+
+.twin-workspace .trace-metrics,
+.twin-workspace .trace-score-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(120px, 1fr));
+  gap: 6px;
+  margin: var(--spacing-sm) 0;
+}
+
+.twin-workspace .trace-metrics span,
+.twin-workspace .trace-score-grid span {
+  padding: 6px 8px;
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-sm);
+  color: var(--text-secondary);
+  font-size: 0.78rem;
+}
+
+.twin-workspace .trace-warning {
+  padding: 6px 8px;
+  border: 1px solid color-mix(in srgb, var(--accent-warning) 55%, transparent);
+  border-radius: var(--radius-sm);
+  color: var(--accent-warning);
+  background: color-mix(in srgb, var(--accent-warning) 10%, transparent);
+}
+
+.twin-workspace .trace-section {
+  margin-top: var(--spacing-sm);
+}
+
+.twin-workspace .trace-section h4 {
+  margin: 0 0 6px;
+  font-size: 0.78rem;
+  color: var(--text-primary);
+}
+
+.twin-workspace .trace-source-list,
+.twin-workspace .trace-feedback-list {
+  display: grid;
+  gap: 6px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.twin-workspace .trace-source-list li,
+.twin-workspace .trace-feedback-list li {
+  display: grid;
+  gap: 2px;
+  padding: 7px 8px;
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-sm);
+  background: var(--bg-primary);
+}
+
+.twin-workspace .trace-source-list li span,
+.twin-workspace .trace-feedback-list li span {
+  color: var(--accent-cyan);
+  font-size: 0.72rem;
+  font-weight: 700;
+}
+
+.twin-workspace .trace-source-list li small,
+.twin-workspace .trace-feedback-list li small {
+  color: var(--text-secondary);
+}
+
+/* Outcome recording: labeled form, open until an outcome exists */
+.twin-workspace .outcome-details {
+  margin-top: var(--spacing-sm);
+  padding-top: var(--spacing-sm);
+  border-top: 1px dashed var(--border-default);
+}
+
+.twin-workspace .outcome-details summary {
+  font-size: 0.8rem;
+  color: var(--text-secondary);
+}
+
+.twin-workspace .outcome-row {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 10px;
+  align-items: end;
+  margin-top: var(--spacing-sm);
+}
+
+.twin-workspace .outcome-field {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.twin-workspace .outcome-field > span {
+  font-size: 0.68rem;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--text-muted);
+}
+
+.twin-workspace .outcome-field input,
+.twin-workspace .outcome-field select,
+.twin-workspace .config-row select,
+.twin-workspace .identity-field input,
+.twin-workspace .setup-field textarea,
+.twin-workspace .panel-header select {
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-sm);
+  background: var(--bg-primary);
+  color: var(--text-primary);
+}
+
+.twin-workspace .outcome-field input,
+.twin-workspace .outcome-field select {
+  min-height: 32px;
+  padding: 4px 8px;
+}
+
+.twin-workspace .outcome-row .save-outcome {
+  grid-column: 1 / -1;
+  justify-self: start;
+}
+
+.twin-workspace .correction-row {
+  margin-top: 10px;
+}
+
+.twin-workspace .memory-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  align-items: start;
+}
+
+.twin-workspace .setup-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+}
+
+.twin-workspace .guide-panel,
+.twin-workspace .config-panel {
+  display: flex;
+  flex-direction: column;
+}
+
+.twin-workspace .guide-walkthrough ol {
+  margin: var(--spacing-sm) 0 0;
+  padding-left: 1.2rem;
+}
+
+.twin-workspace .guide-group dl {
+  display: grid;
+  grid-template-columns: minmax(120px, 180px) 1fr;
+  gap: 8px var(--spacing-md);
+  margin: var(--spacing-sm) 0 0;
+}
+
+.twin-workspace .guide-group dt {
+  font-weight: 700;
+}
+
+.twin-workspace .guide-group dd {
+  margin: 0;
+  color: var(--text-secondary);
+}
+
+.twin-workspace .config-row,
+.twin-workspace .config-toggle,
+.twin-workspace .weight-row,
+.twin-workspace .config-actions {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-sm);
+}
+
+.twin-workspace .config-row,
+.twin-workspace .weight-row {
+  justify-content: space-between;
+}
+
+.twin-workspace .config-row select {
+  min-height: 32px;
+  padding: 4px 8px;
+}
+
+.twin-workspace .config-toggle {
+  margin-top: var(--spacing-sm);
+}
+
+.twin-workspace .config-actions {
+  margin-top: var(--spacing-sm);
+}
+
+.twin-workspace .weight-row {
+  margin-top: var(--spacing-sm);
+}
+
+.twin-workspace .weight-row span {
+  min-width: 160px;
+}
+
+.twin-workspace .weight-row input {
+  flex: 1;
+}
+
+.twin-workspace .weight-row strong {
+  min-width: 44px;
+  text-align: right;
+  font-family: 'Fira Code', monospace;
+  font-weight: 500;
+}
+
+.twin-workspace .setup-field {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-xs);
+  padding: var(--spacing-md);
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-md);
+  background: var(--bg-secondary);
+}
+
+.twin-workspace .identity-section,
+.twin-workspace .setup-section-heading {
+  grid-column: 1 / -1;
+}
+
+.twin-workspace .identity-section {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: var(--spacing-md);
+  padding: var(--spacing-md);
+  border: 1px solid var(--border-default);
+  border-left: 3px solid var(--accent-primary);
+  border-radius: var(--radius-md);
+  background: var(--bg-secondary);
+}
+
+.twin-workspace .identity-section > div {
+  grid-column: 1 / -1;
+}
+
+.twin-workspace .identity-section h2,
+.twin-workspace .setup-section-heading h2 {
+  margin: 0;
+}
+
+.twin-workspace .identity-section span,
+.twin-workspace .setup-section-heading span {
+  color: var(--text-secondary);
+}
+
+.twin-workspace .identity-field {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-xs);
+}
+
+.twin-workspace .identity-field span {
+  font-weight: 600;
+  color: var(--text-primary);
+}
+
+.twin-workspace .identity-field input {
+  min-height: 36px;
+  padding: 4px 8px;
+}
+
+.twin-workspace .identity-section .setup-field {
+  grid-column: 1 / -1;
+  padding: 0;
+  border: none;
+  background: transparent;
+}
+
+.twin-workspace .setup-field span {
+  font-weight: 600;
+}
+
+.twin-workspace .setup-field textarea {
+  resize: vertical;
+  padding: var(--spacing-sm);
+}
+
+.twin-workspace .setup-actions {
+  grid-column: 1 / -1;
+  display: flex;
+  align-items: flex-start;
+}
+
+.twin-workspace .evidence-drawer {
+  position: fixed;
+  top: 72px;
+  right: var(--spacing-lg);
+  width: min(420px, calc(100vw - 32px));
+  max-height: calc(100vh - 104px);
+  overflow: auto;
+  padding: var(--spacing-md);
+  background: var(--bg-elevated, var(--bg-secondary));
+  box-shadow: var(--shadow-xl);
+  z-index: 40;
+}
+
+.twin-workspace .evidence-item {
+  padding: var(--spacing-sm) 0;
+  border-top: 1px solid var(--border-subtle);
+}
+
+.twin-workspace .save-toast {
+  position: fixed;
+  bottom: var(--spacing-lg);
+  right: var(--spacing-lg);
+  padding: var(--spacing-sm) var(--spacing-md);
+  border-radius: var(--radius-sm);
+  background: var(--bg-secondary);
+  border: 1px solid var(--border-default);
+  box-shadow: var(--shadow-lg);
+  z-index: 50;
+}
+
+.twin-workspace .save-toast.success {
+  border-color: var(--accent-green);
+}
+
+.twin-workspace .save-toast.error {
+  border-color: var(--accent-red);
+}
+
+@media (max-width: 980px) {
+  .twin-workspace .workspace-header,
+.twin-workspace .overview-stats,
+.twin-workspace .identity-section,
+.twin-workspace .memory-grid,
+.twin-workspace .setup-grid,
+.twin-workspace .gap-columns,
+.twin-workspace .outcome-row {
+    grid-template-columns: 1fr;
+  }
+
+  .twin-workspace .workspace-body {
+    flex-direction: column;
+  }
+
+  .twin-workspace .workspace-rail {
+    flex: 0 0 auto;
+    flex-direction: row;
+    align-items: center;
+    overflow-x: auto;
+    overflow-y: hidden;
+    padding: var(--spacing-xs) var(--spacing-sm);
+    border-right: none;
+    border-bottom: 1px solid var(--border-default);
+  }
+
+  .twin-workspace .rail-label {
+    display: none;
+  }
+
+  .twin-workspace .tab-button {
+    width: auto;
+    flex: 0 0 auto;
+    border-left: none;
+    border-bottom: 3px solid transparent;
+    border-radius: var(--radius-sm) var(--radius-sm) 0 0;
+  }
+
+  .twin-workspace .tab-button.active {
+    border-bottom-color: var(--accent-primary);
+  }
+
+  .twin-workspace .header-title {
+    text-align: left;
+  }
+}
diff --git a/frontend/src/stores/twin.js b/frontend/src/stores/twin.js
new file mode 100644
index 0000000..73bc181
--- /dev/null
+++ b/frontend/src/stores/twin.js
@@ -0,0 +1,355 @@
+import { defineStore } from 'pinia'
+import { computed, reactive, ref } from 'vue'
+import { twin as twinApi } from '@/api/client'
+import { defaultDecisionMirrorWeights, splitLines, constitutionRunSummary, statusLabel } from '@/utils/twinFormat'
+
+const TUTORIAL_STORAGE_KEY = 'grafyn.twinWorkspaceTutorial.dismissed'
+
+/**
+ * Owns all Twin Workspace UI state and API calls (`TwinReviewView.vue` and its
+ * per-tab components under `components/twin/`). Extracted from the view in
+ * Task 4.3 — behavior-identical, state names preserved from the original refs.
+ */
+export const useTwinStore = defineStore('twin', () => {
+  // State
+  const activeTab = ref('overview')
+  const reviewRecords = ref([])
+  const memoryDigestItems = ref([])
+  const constitutionItems = ref([])
+  const actionGaps = ref([])
+  const decisions = ref([])
+  const selectedRecordState = ref('candidate')
+  const selectedRecordId = ref(null)
+  const selectedEvidence = ref([])
+  const evidenceLoading = ref(false)
+  const runningTwinInference = ref(false)
+  const runningConstitutionInference = ref(false)
+  const savingSetup = ref(false)
+  const savingConfig = ref(false)
+  const exportingBenchmark = ref(false)
+  const message = ref(null)
+  const showTutorialIntro = ref(localStorage.getItem(TUTORIAL_STORAGE_KEY) !== 'true')
+  const setupDraft = reactive({
+    twin_name: '',
+    twin_role: '',
+    source_boundaries: '',
+    values: '',
+    tastes: '',
+    constraints: '',
+    somatic_cues: '',
+    action_tendencies: ''
+  })
+  const configDraft = reactive({
+    preset: 'balanced',
+    advanced_enabled: false,
+    weights: defaultDecisionMirrorWeights()
+  })
+
+  // Getters
+  const activeConstitutionCount = computed(() =>
+    constitutionItems.value.filter(item => ['active', 'candidate', 'softened'].includes(item.status)).length
+  )
+  const activeActionGapCount = computed(() =>
+    actionGaps.value.filter(gap => ['active', 'candidate', 'softened'].includes(gap.status)).length
+  )
+  const pendingReviewCount = computed(() =>
+    memoryDigestItems.value.length + reviewRecords.value.filter(item => item.record.promotion_state === 'candidate').length
+  )
+  const pendingOutcomeCount = computed(() =>
+    decisions.value.filter(item => !item.episode.outcome).length
+  )
+  const healthSummary = computed(() =>
+    `${constitutionItems.value.length} principles / ${actionGaps.value.length} gaps / ${decisions.value.length} decisions`
+  )
+  const recentDecisions = computed(() => decisions.value.slice(0, 4))
+  const topActionGaps = computed(() => actionGaps.value.slice(0, 4))
+  const filteredReviewRecords = computed(() =>
+    reviewRecords.value.filter(item => item.record.promotion_state === selectedRecordState.value)
+  )
+  const groupedConstitution = computed(() => {
+    const groups = new Map()
+    for (const item of constitutionItems.value) {
+      const key = item.dimension || 'general'
+      if (!groups.has(key)) groups.set(key, [])
+      groups.get(key).push(item)
+    }
+    return [...groups.entries()]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([dimension, items]) => ({ dimension, items }))
+  })
+
+  // Actions
+  async function loadWorkspace() {
+    try {
+      const [
+        review,
+        digest,
+        constitution,
+        gaps,
+        decisionRows,
+        setup,
+        mirrorConfig
+      ] = await Promise.all([
+        twinApi.getReview(),
+        twinApi.listMemoryDigest(),
+        twinApi.listConstitutionItems(),
+        twinApi.listActionGaps(),
+        twinApi.listDecisionEpisodes(),
+        twinApi.getConstitutionSetup(),
+        twinApi.getDecisionMirrorConfig()
+      ])
+      reviewRecords.value = review
+      memoryDigestItems.value = digest
+      constitutionItems.value = constitution
+      actionGaps.value = gaps
+      decisions.value = decisionRows
+      loadSetupDraft(setup)
+      loadConfigDraft(mirrorConfig)
+    } catch (err) {
+      showMessage('error', err.message || 'Failed to load twin workspace')
+    }
+  }
+
+  async function runTwinInference() {
+    runningTwinInference.value = true
+    try {
+      const summary = await twinApi.runInference()
+      await loadWorkspace()
+      showMessage('success', `Records: ${summary.created_records} created, ${summary.updated_records} updated`, 3500)
+    } catch (err) {
+      showMessage('error', err.message || 'Failed to run record inference')
+    } finally {
+      runningTwinInference.value = false
+    }
+  }
+
+  async function runConstitutionInference() {
+    runningConstitutionInference.value = true
+    try {
+      const summary = await twinApi.runConstitutionInference()
+      await loadWorkspace()
+      showMessage('success', constitutionRunSummary(summary), 4500)
+    } catch (err) {
+      showMessage('error', err.message || 'Failed to run constitution inference')
+    } finally {
+      runningConstitutionInference.value = false
+    }
+  }
+
+  async function reviewConstitutionItem(id, action) {
+    try {
+      await twinApi.reviewConstitutionItem(id, { action })
+      await loadWorkspace()
+      showMessage('success', 'Updated constitution item', 1800)
+    } catch (err) {
+      showMessage('error', err.message || 'Failed to update constitution item')
+    }
+  }
+
+  async function reviewActionGap(id, action) {
+    try {
+      await twinApi.reviewActionGap(id, { action })
+      await loadWorkspace()
+      showMessage('success', 'Updated action gap', 1800)
+    } catch (err) {
+      showMessage('error', err.message || 'Failed to update action gap')
+    }
+  }
+
+  async function reviewMemoryDigestItem(id, action) {
+    try {
+      await twinApi.reviewMemoryDigestItem(id, { action })
+      await loadWorkspace()
+      showMessage('success', 'Updated digest item', 1800)
+    } catch (err) {
+      showMessage('error', err.message || 'Failed to update digest item')
+    }
+  }
+
+  async function setPromotion(recordId, promotionState) {
+    try {
+      await twinApi.setPromotion(recordId, promotionState, null)
+      await loadWorkspace()
+      showMessage('success', `Set record to ${statusLabel(promotionState)}`, 1800)
+    } catch (err) {
+      showMessage('error', err.message || 'Failed to update record')
+    }
+  }
+
+  async function openEvidence(recordId) {
+    selectedRecordId.value = recordId
+    selectedEvidence.value = []
+    evidenceLoading.value = true
+    try {
+      selectedEvidence.value = await twinApi.resolveEvidence(recordId)
+    } catch (err) {
+      showMessage('error', err.message || 'Failed to load evidence')
+    } finally {
+      evidenceLoading.value = false
+    }
+  }
+
+  async function updateDecisionOutcome(id, update) {
+    try {
+      const payload = { ...update }
+      if (payload.regret_score == null) delete payload.regret_score
+      await twinApi.updateDecisionOutcome(id, payload)
+      await loadWorkspace()
+      showMessage('success', 'Updated decision outcome', 1800)
+    } catch (err) {
+      showMessage('error', err.message || 'Failed to update decision')
+    }
+  }
+
+  async function saveSetup() {
+    savingSetup.value = true
+    try {
+      await twinApi.saveConstitutionSetup({
+        twin_name: setupDraft.twin_name.trim(),
+        twin_role: setupDraft.twin_role.trim(),
+        source_boundaries: splitLines(setupDraft.source_boundaries),
+        values: splitLines(setupDraft.values),
+        tastes: splitLines(setupDraft.tastes),
+        constraints: splitLines(setupDraft.constraints),
+        somatic_cues: splitLines(setupDraft.somatic_cues),
+        action_tendencies: splitLines(setupDraft.action_tendencies)
+      })
+      await loadWorkspace()
+      showMessage('success', 'Saved setup', 2000)
+    } catch (err) {
+      showMessage('error', err.message || 'Failed to save setup')
+    } finally {
+      savingSetup.value = false
+    }
+  }
+
+  async function saveDecisionMirrorConfig() {
+    savingConfig.value = true
+    try {
+      const update = {
+        preset: configDraft.preset,
+        advanced_enabled: configDraft.advanced_enabled
+      }
+      if (configDraft.advanced_enabled) {
+        update.weights = { ...configDraft.weights }
+      }
+      const config = await twinApi.updateDecisionMirrorConfig(update)
+      loadConfigDraft(config)
+      showMessage('success', 'Saved Decision Mirror config', 2000)
+    } catch (err) {
+      showMessage('error', err.message || 'Failed to save Decision Mirror config')
+    } finally {
+      savingConfig.value = false
+    }
+  }
+
+  async function resetDecisionMirrorConfig() {
+    savingConfig.value = true
+    try {
+      const config = await twinApi.resetDecisionMirrorConfig()
+      loadConfigDraft(config)
+      showMessage('success', 'Reset Decision Mirror config', 2000)
+    } catch (err) {
+      showMessage('error', err.message || 'Failed to reset Decision Mirror config')
+    } finally {
+      savingConfig.value = false
+    }
+  }
+
+  async function exportDecisionBenchmark() {
+    exportingBenchmark.value = true
+    try {
+      const bundle = await twinApi.exportData({ bundle_name: 'decision-mirror-benchmark' })
+      showMessage(
+        'success',
+        `Exported benchmark: ${bundle.decision_mirror_benchmark?.count || 0} decisions`,
+        3500
+      )
+    } catch (err) {
+      showMessage('error', err.message || 'Failed to export benchmark')
+    } finally {
+      exportingBenchmark.value = false
+    }
+  }
+
+  function dismissTutorial() {
+    localStorage.setItem(TUTORIAL_STORAGE_KEY, 'true')
+    showTutorialIntro.value = false
+  }
+
+  function loadSetupDraft(setup) {
+    setupDraft.twin_name = setup?.twin_name || ''
+    setupDraft.twin_role = setup?.twin_role || ''
+    setupDraft.source_boundaries = (setup?.source_boundaries || []).join('\n')
+    setupDraft.values = (setup?.values || []).join('\n')
+    setupDraft.tastes = (setup?.tastes || []).join('\n')
+    setupDraft.constraints = (setup?.constraints || []).join('\n')
+    setupDraft.somatic_cues = (setup?.somatic_cues || []).join('\n')
+    setupDraft.action_tendencies = (setup?.action_tendencies || []).join('\n')
+  }
+
+  function loadConfigDraft(config) {
+    configDraft.preset = config?.preset || 'balanced'
+    configDraft.advanced_enabled = Boolean(config?.advanced_enabled)
+    configDraft.weights = {
+      ...defaultDecisionMirrorWeights(),
+      ...(config?.weights || {})
+    }
+  }
+
+  function showMessage(type, text, duration = 3500) {
+    message.value = { type, text }
+    setTimeout(() => {
+      if (message.value?.text === text) message.value = null
+    }, duration)
+  }
+
+  return {
+    // State
+    activeTab,
+    reviewRecords,
+    memoryDigestItems,
+    constitutionItems,
+    actionGaps,
+    decisions,
+    selectedRecordState,
+    selectedRecordId,
+    selectedEvidence,
+    evidenceLoading,
+    runningTwinInference,
+    runningConstitutionInference,
+    savingSetup,
+    savingConfig,
+    exportingBenchmark,
+    message,
+    showTutorialIntro,
+    setupDraft,
+    configDraft,
+    // Getters
+    activeConstitutionCount,
+    activeActionGapCount,
+    pendingReviewCount,
+    pendingOutcomeCount,
+    healthSummary,
+    recentDecisions,
+    topActionGaps,
+    filteredReviewRecords,
+    groupedConstitution,
+    // Actions
+    loadWorkspace,
+    runTwinInference,
+    runConstitutionInference,
+    reviewConstitutionItem,
+    reviewActionGap,
+    reviewMemoryDigestItem,
+    setPromotion,
+    openEvidence,
+    updateDecisionOutcome,
+    saveSetup,
+    saveDecisionMirrorConfig,
+    resetDecisionMirrorConfig,
+    exportDecisionBenchmark,
+    dismissTutorial,
+    showMessage
+  }
+})
diff --git a/frontend/src/utils/twinFormat.js b/frontend/src/utils/twinFormat.js
new file mode 100644
index 0000000..fce18ca
--- /dev/null
+++ b/frontend/src/utils/twinFormat.js
@@ -0,0 +1,184 @@
+// Pure formatting/labeling helpers shared across Twin Workspace components and
+// the twin Pinia store. Extracted verbatim from TwinReviewView.vue (Task 4.3) —
+// no behavior changes, just relocated so multiple components can share them.
+
+export const decisionMirrorPresets = [
+  { value: 'balanced', label: 'Balanced' },
+  { value: 'evidence_strict', label: 'Stricter Evidence' },
+  { value: 'insight_search', label: 'Find Blind Spots' },
+  { value: 'action_bias', label: 'Push Next Action' }
+]
+
+export const configWeightRows = [
+  { key: 'notes_weight', label: 'Vault Evidence' },
+  { key: 'approved_records_weight', label: 'Trusted Self-Model' },
+  { key: 'candidate_records_weight', label: 'Tentative Patterns' },
+  { key: 'constitution_weight', label: 'Values Fit' },
+  { key: 'action_gaps_weight', label: 'Follow-Through Risk' },
+  { key: 'recency_weight', label: 'Current Self' },
+  { key: 'evidence_count_weight', label: 'Repeated Evidence' },
+  { key: 'outcome_history_weight', label: 'Past Outcomes' },
+  { key: 'contradiction_weight', label: 'Tensions' },
+  { key: 'breadth_weight', label: 'Reflection Breadth' },
+  { key: 'depth_weight', label: 'Reflection Depth' },
+  { key: 'evidence_grounding_weight', label: 'Grounded Claims' },
+  { key: 'blind_spot_weight', label: 'Blind Spots' },
+  { key: 'counter_position_weight', label: 'Counterargument' },
+  { key: 'actionability_weight', label: 'Next Step Clarity' },
+  { key: 'uncertainty_weight', label: 'Honest Uncertainty' },
+  { key: 'privacy_weight', label: 'Privacy Safety' },
+  { key: 'unsupported_penalty_weight', label: 'Unsupported Claim Penalty' }
+]
+
+export function defaultDecisionMirrorWeights() {
+  return Object.fromEntries(configWeightRows.map(row => [row.key, 1]))
+}
+
+export function splitLines(value) {
+  return value
+    .split('\n')
+    .map(line => line.trim())
+    .filter(Boolean)
+}
+
+export function decisionState(item) {
+  if (item.prediction_sealed) return 'is-sealed'
+  if (item.episode.agreement === true) return 'is-match'
+  if (item.episode.agreement === false) return 'is-miss'
+  if (!item.episode.outcome) return 'is-pending'
+  return ''
+}
+
+export function decisionChips(item) {
+  const chips = []
+  if (item.prediction_sealed) chips.push({ id: 'sealed', label: 'Sealed', cls: 'chip-sealed' })
+  if (item.episode.agreement === true) chips.push({ id: 'match', label: 'Matched', cls: 'chip-match' })
+  if (item.episode.agreement === false) chips.push({ id: 'miss', label: 'Missed', cls: 'chip-miss' })
+  if (!item.episode.outcome) chips.push({ id: 'pending', label: 'Outcome pending', cls: 'chip-pending' })
+  return chips
+}
+
+export function actionLabel(action) {
+  return {
+    keep: 'Keep',
+    soften: 'Soften',
+    not_me: 'Not Me',
+    private: 'Private',
+    no_train: 'No Train',
+    reject: 'Reject'
+  }[action] || action
+}
+
+export function statusLabel(value) {
+  return String(value || 'unknown')
+    .split('_')
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ')
+}
+
+export function kindLabel(value) {
+  return statusLabel(value)
+}
+
+export function dimensionLabel(value) {
+  return statusLabel(value || 'general')
+}
+
+export function formatPercent(value) {
+  return `${Math.round((value || 0) * 100)}%`
+}
+
+export function formatWeight(value) {
+  return Number(value || 0).toFixed(2)
+}
+
+export function presetLabel(value) {
+  const preset = decisionMirrorPresets.find(item => item.value === value)
+  return preset?.label || statusLabel(value || 'balanced')
+}
+
+export function sourceTypeLabel(value) {
+  const labels = {
+    note: 'Note',
+    behavior: 'Behavior',
+    'interview-question': 'Interview Question',
+    'interview-answer': 'Interview Answer',
+    decision: 'Decision',
+    setup: 'Setup',
+    approved_record: 'Approved Record',
+    candidate_record: 'Candidate Record',
+    constitution_item: 'Constitution',
+    action_gap: 'Action Gap'
+  }
+  return labels[value] || statusLabel(value)
+}
+
+export function constitutionSourceLabel(item) {
+  if (item.source) return sourceTypeLabel(item.source)
+  const first = item.evidence_refs?.[0]
+  return sourceTypeLabel(first?.source_type || 'evidence')
+}
+
+export function constitutionEvidenceLabels(item) {
+  const labels = new Set()
+  for (const ref of item.evidence_refs || []) {
+    if (ref.source_type) labels.add(sourceTypeLabel(ref.source_type))
+    if (ref.source_label) labels.add(ref.source_label)
+  }
+  return [...labels].slice(0, 4)
+}
+
+export function constitutionRunSummary(summary = {}) {
+  const parts = [
+    `${summary.created_constitution_items || 0} items`,
+    `${summary.created_action_gaps || 0} gaps`
+  ]
+  if (summary.auto_active_items) parts.push(`${summary.auto_active_items} active`)
+  if (summary.review_candidate_items) parts.push(`${summary.review_candidate_items} review`)
+  if (summary.scanned_behavior_events) parts.push(`${summary.scanned_behavior_events} behavior events`)
+  if (summary.scanned_notes) parts.push(`${summary.scanned_notes} notes`)
+  if (summary.scanned_interviews) parts.push(`${summary.scanned_interviews} interviews`)
+  if (summary.extracted_research_findings) parts.push(`${summary.extracted_research_findings} findings`)
+  if (summary.pruned_stale_constitution_items) parts.push(`${summary.pruned_stale_constitution_items} stale items removed`)
+  if (summary.pruned_stale_records) parts.push(`${summary.pruned_stale_records} stale records removed`)
+  if (summary.updated_setup_entries) parts.push(`${summary.updated_setup_entries} setup entries`)
+  if (summary.skipped_domain_claims) parts.push(`${summary.skipped_domain_claims} skipped`)
+  return `Constitution: ${parts.join(' / ')}`
+}
+
+export function scoreRows(scores = {}) {
+  return [
+    ['Breadth', scores.breadth_score],
+    ['Depth', scores.depth_score],
+    ['Grounding', scores.evidence_grounding_score],
+    ['Blind Spot', scores.blind_spot_score],
+    ['Action', scores.actionability_score],
+    ['Counter', scores.counterargument_score],
+    ['Uncertainty', scores.uncertainty_score],
+    ['Privacy', scores.privacy_score],
+    ['Overall', scores.overall_score]
+  ].map(([label, value]) => ({
+    label,
+    value: value == null ? 'n/a' : formatPercent(value)
+  }))
+}
+
+export function feedbackEventLabel(event = {}) {
+  return statusLabel(event.payload?.feedback_type || event.event_type || 'feedback')
+}
+
+export function feedbackEventNote(event = {}) {
+  return event.payload?.rationale
+    || event.payload?.content
+    || event.payload?.response?.response_excerpt
+    || event.payload?.response?.response_content
+    || 'Feedback recorded'
+}
+
+export function formatDate(value) {
+  return value ? new Date(value).toLocaleString() : ''
+}
+
+export function eventLabel(value) {
+  return statusLabel(value)
+}

From f0448159db29ad3919abddaa551d8c5e867ada57 Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 17:24:50 +0800
Subject: [PATCH 20/30] refactor: extract twin/TwinGuideTab component

Moves the static Guide tab (walkthrough + button reference) out of
TwinReviewView.vue verbatim. No store dependency for this tab.
---
 frontend/src/components/twin/TwinGuideTab.vue | 89 +++++++++++++++++++
 frontend/src/views/TwinReviewView.vue         | 88 +-----------------
 2 files changed, 91 insertions(+), 86 deletions(-)
 create mode 100644 frontend/src/components/twin/TwinGuideTab.vue

diff --git a/frontend/src/components/twin/TwinGuideTab.vue b/frontend/src/components/twin/TwinGuideTab.vue
new file mode 100644
index 0000000..9b85c25
--- /dev/null
+++ b/frontend/src/components/twin/TwinGuideTab.vue
@@ -0,0 +1,89 @@
+<template>
+  <section class="tab-panel guide-panel">
+    <div class="panel-header">
+      <div>
+        <h2>How To Use</h2>
+        <span>Button guide and short task walkthroughs</span>
+      </div>
+    </div>
+    <section class="workspace-band guide-walkthrough">
+      <h3>Fast Decision Session</h3>
+      <ol>
+        <li>Open Canvas and click <strong>+ New</strong>.</li>
+        <li>Choose <strong>Decision</strong>, then write or paste the decision.</li>
+        <li>Add options, stakes, leaning, and follow-up only when useful.</li>
+        <li>Click <strong>Create Reflection Card</strong>.</li>
+        <li>Use one feedback button if the card is useful or wrong.</li>
+      </ol>
+    </section>
+    <section
+      v-for="group in tutorialButtonGroups"
+      :key="group.title"
+      class="workspace-band guide-group"
+    >
+      <h3>{{ group.title }}</h3>
+      <dl>
+        <template
+          v-for="item in group.items"
+          :key="item.name"
+        >
+          <dt>{{ item.name }}</dt>
+          <dd>{{ item.description }}</dd>
+        </template>
+      </dl>
+    </section>
+  </section>
+</template>
+
+<script setup>
+// Extracted verbatim from TwinReviewView.vue (Task 4.3). Pure static content —
+// no store dependency.
+const tutorialButtonGroups = [
+  {
+    title: 'Canvas Buttons',
+    items: [
+      { name: '+ New', description: 'Create a normal prompt or Decision Mirror session.' },
+      { name: 'Decision', description: 'Switches the prompt into Decision Mirror mode.' },
+      { name: 'Options', description: 'One option per line, useful for comparisons.' },
+      { name: 'Stakes', description: 'What changes if the decision goes right or wrong.' },
+      { name: 'Initial Leaning', description: 'What the user currently thinks they may choose.' },
+      { name: 'Follow-up', description: 'Optional date for outcome review.' },
+      { name: 'Create Reflection Card', description: 'Generates the Decision Mirror answer.' },
+      { name: 'Useful', description: 'Marks the reflection as useful evidence.' },
+      { name: 'Not Me', description: 'Records that the mirror misrepresented the user.' },
+      { name: 'Save Insight', description: 'Saves the reflection as a reasoning-pattern insight.' },
+      { name: 'Reject Pattern', description: 'Rejects the inferred pattern behind the reflection.' },
+      { name: 'Open in Twin', description: 'Jumps to the decision record in Twin Workspace.' }
+    ]
+  },
+  {
+    title: 'Twin Workspace Buttons',
+    items: [
+      { name: 'Run Records', description: 'Infer candidate user records from Canvas traces and feedback.' },
+      { name: 'Run Constitution', description: 'Infer Constitution items and Action Gaps from records and decisions.' },
+      { name: 'Overview', description: 'Shows health summary, recent decisions, action gaps, and pending review.' },
+      { name: 'Constitution', description: 'Review values, tastes, constraints, somatic cues, and reasoning principles.' },
+      { name: 'Action Gaps', description: 'Review gaps between stated intent and revealed behavior.' },
+      { name: 'Decisions', description: 'Review Reflection Cards and record outcomes.' },
+      { name: 'Memory Review', description: 'Review clustered memory digest items.' },
+      { name: 'Setup', description: 'Progressively seed values, tastes, constraints, somatic cues, and action tendencies.' },
+      { name: 'Keep', description: 'Approve a memory or constitution item for future context.' },
+      { name: 'Soften', description: 'Keep it as tentative or lower confidence.' },
+      { name: 'Not Me', description: 'Mark it as inaccurate.' },
+      { name: 'Private', description: 'Exclude it from live twin context.' },
+      { name: 'No Train', description: 'Preserve locally but exclude from model, training, and export use.' },
+      { name: 'Reject', description: 'Remove it from future twin context.' },
+      { name: 'Save Setup', description: 'Turns setup entries into evidence-backed Constitution seed items.' }
+    ]
+  },
+  {
+    title: 'Config Buttons',
+    items: [
+      { name: 'Preset', description: 'Choose Balanced, Stricter Evidence, Find Blind Spots, or Push Next Action.' },
+      { name: 'Advanced', description: 'Reveals scoring and retrieval sliders.' },
+      { name: 'Reset', description: 'Restores default Decision Mirror settings.' },
+      { name: 'Export Benchmark', description: 'Exports decision episodes, Reflection Cards, scores, evidence packets, and outcomes.' }
+    ]
+  }
+]
+</script>
diff --git a/frontend/src/views/TwinReviewView.vue b/frontend/src/views/TwinReviewView.vue
index 63b9870..eb2963a 100644
--- a/frontend/src/views/TwinReviewView.vue
+++ b/frontend/src/views/TwinReviewView.vue
@@ -463,43 +463,7 @@
           </div>
         </section>
 
-        <section
-          v-else-if="activeTab === 'guide'"
-          class="tab-panel guide-panel"
-        >
-          <div class="panel-header">
-            <div>
-              <h2>How To Use</h2>
-              <span>Button guide and short task walkthroughs</span>
-            </div>
-          </div>
-          <section class="workspace-band guide-walkthrough">
-            <h3>Fast Decision Session</h3>
-            <ol>
-              <li>Open Canvas and click <strong>+ New</strong>.</li>
-              <li>Choose <strong>Decision</strong>, then write or paste the decision.</li>
-              <li>Add options, stakes, leaning, and follow-up only when useful.</li>
-              <li>Click <strong>Create Reflection Card</strong>.</li>
-              <li>Use one feedback button if the card is useful or wrong.</li>
-            </ol>
-          </section>
-          <section
-            v-for="group in tutorialButtonGroups"
-            :key="group.title"
-            class="workspace-band guide-group"
-          >
-            <h3>{{ group.title }}</h3>
-            <dl>
-              <template
-                v-for="item in group.items"
-                :key="item.name"
-              >
-                <dt>{{ item.name }}</dt>
-                <dd>{{ item.description }}</dd>
-              </template>
-            </dl>
-          </section>
-        </section>
+        <TwinGuideTab v-else-if="activeTab === 'guide'" />
 
         <section
           v-else-if="activeTab === 'config'"
@@ -642,6 +606,7 @@
 import { computed, defineComponent, h, onMounted, reactive, ref } from 'vue'
 import { useRoute } from 'vue-router'
 import { twin } from '@/api/client'
+import TwinGuideTab from '@/components/twin/TwinGuideTab.vue'
 
 const navGroups = computed(() => [
   {
@@ -962,55 +927,6 @@ const configWeightRows = [
   { key: 'privacy_weight', label: 'Privacy Safety' },
   { key: 'unsupported_penalty_weight', label: 'Unsupported Claim Penalty' }
 ]
-const tutorialButtonGroups = [
-  {
-    title: 'Canvas Buttons',
-    items: [
-      { name: '+ New', description: 'Create a normal prompt or Decision Mirror session.' },
-      { name: 'Decision', description: 'Switches the prompt into Decision Mirror mode.' },
-      { name: 'Options', description: 'One option per line, useful for comparisons.' },
-      { name: 'Stakes', description: 'What changes if the decision goes right or wrong.' },
-      { name: 'Initial Leaning', description: 'What the user currently thinks they may choose.' },
-      { name: 'Follow-up', description: 'Optional date for outcome review.' },
-      { name: 'Create Reflection Card', description: 'Generates the Decision Mirror answer.' },
-      { name: 'Useful', description: 'Marks the reflection as useful evidence.' },
-      { name: 'Not Me', description: 'Records that the mirror misrepresented the user.' },
-      { name: 'Save Insight', description: 'Saves the reflection as a reasoning-pattern insight.' },
-      { name: 'Reject Pattern', description: 'Rejects the inferred pattern behind the reflection.' },
-      { name: 'Open in Twin', description: 'Jumps to the decision record in Twin Workspace.' }
-    ]
-  },
-  {
-    title: 'Twin Workspace Buttons',
-    items: [
-      { name: 'Run Records', description: 'Infer candidate user records from Canvas traces and feedback.' },
-      { name: 'Run Constitution', description: 'Infer Constitution items and Action Gaps from records and decisions.' },
-      { name: 'Overview', description: 'Shows health summary, recent decisions, action gaps, and pending review.' },
-      { name: 'Constitution', description: 'Review values, tastes, constraints, somatic cues, and reasoning principles.' },
-      { name: 'Action Gaps', description: 'Review gaps between stated intent and revealed behavior.' },
-      { name: 'Decisions', description: 'Review Reflection Cards and record outcomes.' },
-      { name: 'Memory Review', description: 'Review clustered memory digest items.' },
-      { name: 'Setup', description: 'Progressively seed values, tastes, constraints, somatic cues, and action tendencies.' },
-      { name: 'Keep', description: 'Approve a memory or constitution item for future context.' },
-      { name: 'Soften', description: 'Keep it as tentative or lower confidence.' },
-      { name: 'Not Me', description: 'Mark it as inaccurate.' },
-      { name: 'Private', description: 'Exclude it from live twin context.' },
-      { name: 'No Train', description: 'Preserve locally but exclude from model, training, and export use.' },
-      { name: 'Reject', description: 'Remove it from future twin context.' },
-      { name: 'Save Setup', description: 'Turns setup entries into evidence-backed Constitution seed items.' }
-    ]
-  },
-  {
-    title: 'Config Buttons',
-    items: [
-      { name: 'Preset', description: 'Choose Balanced, Stricter Evidence, Find Blind Spots, or Push Next Action.' },
-      { name: 'Advanced', description: 'Reveals scoring and retrieval sliders.' },
-      { name: 'Reset', description: 'Restores default Decision Mirror settings.' },
-      { name: 'Export Benchmark', description: 'Exports decision episodes, Reflection Cards, scores, evidence packets, and outcomes.' }
-    ]
-  }
-]
-
 const recordStates = ['candidate', 'auto_promoted', 'endorsed', 'private', 'no_train', 'rejected']
 const route = useRoute() || { query: {} }
 const activeTab = ref(route.query?.decision ? 'decisions' : 'overview')

From 8b031f07248ec7a44aeb8d87c04df39f38b3b2c2 Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 17:38:22 +0800
Subject: [PATCH 21/30] refactor: wire TwinReviewView onto the twin store;
 extract twin/TwinConfigTab
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

All Twin Workspace state and API calls now live in stores/twin.js — the
view's template reads/writes twinStore.* instead of local refs, and the
Config tab (presets, advanced weights, export benchmark) is extracted into
its own component that consumes the store directly. The CSS that was a
single scoped block covering all tabs moves to a shared, non-scoped
stylesheet (components/twin/twin-workspace.css) with every selector
namespaced under .twin-workspace, since Vue's scoped-style attribute only
reaches a child component's root element, not markup nested inside it —
see task-4.3-report.md for the full rationale. Existing view/component
specs updated to provide an active Pinia instance.
---
 .../components/TwinReviewDecisions.spec.js    |    6 +-
 .../unit/views/TwinReviewView.spec.js         |    3 +
 .../src/components/twin/TwinConfigTab.vue     |   89 +
 frontend/src/views/TwinReviewView.vue         | 1704 ++---------------
 4 files changed, 214 insertions(+), 1588 deletions(-)
 create mode 100644 frontend/src/components/twin/TwinConfigTab.vue

diff --git a/frontend/src/__tests__/unit/components/TwinReviewDecisions.spec.js b/frontend/src/__tests__/unit/components/TwinReviewDecisions.spec.js
index c72af68..d104aeb 100644
--- a/frontend/src/__tests__/unit/components/TwinReviewDecisions.spec.js
+++ b/frontend/src/__tests__/unit/components/TwinReviewDecisions.spec.js
@@ -1,5 +1,6 @@
 import { describe, expect, it, vi, beforeEach } from 'vitest'
 import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
 
 vi.mock('vue-router', () => ({
   useRoute: () => ({ query: {} })
@@ -50,7 +51,9 @@ function decisionItem(overrides = {}, episodeOverrides = {}) {
 
 async function mountWithDecisions(items) {
   twin.listDecisionEpisodes.mockResolvedValue(items)
-  const wrapper = mount(TwinReviewView)
+  const wrapper = mount(TwinReviewView, {
+    global: { plugins: [createPinia()] }
+  })
   await flushPromises()
   // Full decision cards live on the Decisions tab; the overview shows compact rows.
   await wrapper.findAll('.tab-button')
@@ -62,6 +65,7 @@ async function mountWithDecisions(items) {
 
 describe('TwinReviewView decision predictions', () => {
   beforeEach(() => {
+    setActivePinia(createPinia())
     vi.clearAllMocks()
     twin.getReview.mockResolvedValue([])
     twin.listMemoryDigest.mockResolvedValue([])
diff --git a/frontend/src/__tests__/unit/views/TwinReviewView.spec.js b/frontend/src/__tests__/unit/views/TwinReviewView.spec.js
index c4db565..39e37cd 100644
--- a/frontend/src/__tests__/unit/views/TwinReviewView.spec.js
+++ b/frontend/src/__tests__/unit/views/TwinReviewView.spec.js
@@ -1,5 +1,6 @@
 import { describe, expect, it, beforeEach, vi } from 'vitest'
 import { mount, flushPromises } from '@vue/test-utils'
+import { createPinia, setActivePinia } from 'pinia'
 import TwinReviewView from '@/views/TwinReviewView.vue'
 
 const api = vi.hoisted(() => ({
@@ -36,6 +37,7 @@ vi.mock('@/api/client', () => ({
 function mountView() {
   return mount(TwinReviewView, {
     global: {
+      plugins: [createPinia()],
       stubs: {
         RouterLink: {
           props: ['to'],
@@ -48,6 +50,7 @@ function mountView() {
 
 describe('TwinReviewView', () => {
   beforeEach(() => {
+    setActivePinia(createPinia())
     vi.clearAllMocks()
     routeState.query = {}
     localStorage.clear()
diff --git a/frontend/src/components/twin/TwinConfigTab.vue b/frontend/src/components/twin/TwinConfigTab.vue
new file mode 100644
index 0000000..fcc0bb8
--- /dev/null
+++ b/frontend/src/components/twin/TwinConfigTab.vue
@@ -0,0 +1,89 @@
+<template>
+  <section class="tab-panel config-panel">
+    <div class="panel-header">
+      <div>
+        <h2>Decision Mirror Config</h2>
+        <span>Presets change retrieval and scoring weights without hiding raw sub-scores.</span>
+      </div>
+      <button
+        class="btn btn-secondary btn-sm"
+        :disabled="twinStore.exportingBenchmark"
+        @click="twinStore.exportDecisionBenchmark"
+      >
+        {{ twinStore.exportingBenchmark ? 'Exporting...' : 'Export Benchmark' }}
+      </button>
+    </div>
+
+    <section class="workspace-band config-card">
+      <label class="config-row">
+        <span>Preset</span>
+        <select v-model="twinStore.configDraft.preset">
+          <option
+            v-for="preset in decisionMirrorPresets"
+            :key="preset.value"
+            :value="preset.value"
+          >
+            {{ preset.label }}
+          </option>
+        </select>
+      </label>
+      <label class="config-toggle">
+        <input
+          v-model="twinStore.configDraft.advanced_enabled"
+          type="checkbox"
+        >
+        <span>Advanced</span>
+      </label>
+      <div class="config-actions">
+        <button
+          class="btn btn-primary"
+          :disabled="twinStore.savingConfig"
+          @click="twinStore.saveDecisionMirrorConfig"
+        >
+          {{ twinStore.savingConfig ? 'Saving...' : 'Save Config' }}
+        </button>
+        <button
+          class="btn btn-secondary"
+          :disabled="twinStore.savingConfig"
+          @click="twinStore.resetDecisionMirrorConfig"
+        >
+          Reset
+        </button>
+      </div>
+    </section>
+
+    <section
+      v-if="twinStore.configDraft.advanced_enabled"
+      class="workspace-band config-card"
+    >
+      <div class="panel-header compact">
+        <div>
+          <h2>Advanced Weights</h2>
+          <span>0 ignores the signal, 3 gives it strong priority.</span>
+        </div>
+      </div>
+      <label
+        v-for="weight in configWeightRows"
+        :key="weight.key"
+        class="weight-row"
+      >
+        <span>{{ weight.label }}</span>
+        <input
+          v-model.number="twinStore.configDraft.weights[weight.key]"
+          type="range"
+          min="0"
+          max="3"
+          step="0.05"
+        >
+        <strong>{{ formatWeight(twinStore.configDraft.weights[weight.key]) }}</strong>
+      </label>
+    </section>
+  </section>
+</template>
+
+<script setup>
+import { useTwinStore } from '@/stores/twin'
+import { decisionMirrorPresets, configWeightRows, formatWeight } from '@/utils/twinFormat'
+
+const twinStore = useTwinStore()
+</script>
diff --git a/frontend/src/views/TwinReviewView.vue b/frontend/src/views/TwinReviewView.vue
index eb2963a..279d49f 100644
--- a/frontend/src/views/TwinReviewView.vue
+++ b/frontend/src/views/TwinReviewView.vue
@@ -11,22 +11,22 @@
       </div>
       <div class="header-title">
         <h1>Twin Workspace</h1>
-        <span>{{ healthSummary }}</span>
+        <span>{{ twinStore.healthSummary }}</span>
       </div>
       <div class="header-actions">
         <button
           class="btn btn-secondary"
-          :disabled="runningTwinInference"
-          @click="runTwinInference"
+          :disabled="twinStore.runningTwinInference"
+          @click="twinStore.runTwinInference"
         >
-          {{ runningTwinInference ? 'Running...' : 'Run Records' }}
+          {{ twinStore.runningTwinInference ? 'Running...' : 'Run Records' }}
         </button>
         <button
           class="btn btn-primary"
-          :disabled="runningConstitutionInference"
-          @click="runConstitutionInference"
+          :disabled="twinStore.runningConstitutionInference"
+          @click="twinStore.runConstitutionInference"
         >
-          {{ runningConstitutionInference ? 'Running...' : 'Run Constitution' }}
+          {{ twinStore.runningConstitutionInference ? 'Running...' : 'Run Constitution' }}
         </button>
       </div>
     </header>
@@ -45,8 +45,8 @@
             v-for="tab in group.tabs"
             :key="tab.id"
             class="tab-button"
-            :class="{ active: activeTab === tab.id }"
-            @click="activeTab = tab.id"
+            :class="{ active: twinStore.activeTab === tab.id }"
+            @click="twinStore.activeTab = tab.id"
           >
             <span>{{ tab.label }}</span>
             <strong v-if="tab.count !== null">{{ tab.count }}</strong>
@@ -56,46 +56,46 @@
 
       <main class="workspace-main">
         <section
-          v-if="activeTab === 'overview'"
+          v-if="twinStore.activeTab === 'overview'"
           class="tab-panel"
         >
           <div class="overview-stats">
             <button
               class="metric-tile"
-              @click="activeTab = 'constitution'"
+              @click="twinStore.activeTab = 'constitution'"
             >
               <span>Constitution</span>
-              <strong>{{ activeConstitutionCount }}</strong>
-              <small>{{ constitutionItems.length }} total items</small>
+              <strong>{{ twinStore.activeConstitutionCount }}</strong>
+              <small>{{ twinStore.constitutionItems.length }} total items</small>
             </button>
             <button
               class="metric-tile"
-              @click="activeTab = 'action_gaps'"
+              @click="twinStore.activeTab = 'action_gaps'"
             >
               <span>Action Gaps</span>
-              <strong>{{ activeActionGapCount }}</strong>
-              <small>{{ actionGaps.length }} total gaps</small>
+              <strong>{{ twinStore.activeActionGapCount }}</strong>
+              <small>{{ twinStore.actionGaps.length }} total gaps</small>
             </button>
             <button
               class="metric-tile"
-              @click="activeTab = 'decisions'"
+              @click="twinStore.activeTab = 'decisions'"
             >
               <span>Decisions</span>
-              <strong>{{ decisions.length }}</strong>
-              <small>{{ pendingOutcomeCount }} outcomes pending</small>
+              <strong>{{ twinStore.decisions.length }}</strong>
+              <small>{{ twinStore.pendingOutcomeCount }} outcomes pending</small>
             </button>
             <button
               class="metric-tile"
-              @click="activeTab = 'memory'"
+              @click="twinStore.activeTab = 'memory'"
             >
               <span>Review</span>
-              <strong>{{ pendingReviewCount }}</strong>
+              <strong>{{ twinStore.pendingReviewCount }}</strong>
               <small>digest plus candidate records</small>
             </button>
           </div>
 
           <section
-            v-if="showTutorialIntro"
+            v-if="twinStore.showTutorialIntro"
             class="workspace-band tutorial-intro"
           >
             <div class="band-header">
@@ -103,13 +103,13 @@
               <div class="header-actions compact">
                 <button
                   class="text-button"
-                  @click="activeTab = 'guide'"
+                  @click="twinStore.activeTab = 'guide'"
                 >
                   Open Guide
                 </button>
                 <button
                   class="text-button"
-                  @click="dismissTutorial"
+                  @click="twinStore.dismissTutorial"
                 >
                   Dismiss
                 </button>
@@ -126,23 +126,23 @@
               <h2>Recent Decisions</h2>
               <button
                 class="text-button"
-                @click="activeTab = 'decisions'"
+                @click="twinStore.activeTab = 'decisions'"
               >
                 View all
               </button>
             </div>
             <div
-              v-if="recentDecisions.length === 0"
+              v-if="twinStore.recentDecisions.length === 0"
               class="empty-panel"
             >
               No decision episodes yet. Start a Decision in Canvas and it will appear here.
             </div>
             <button
-              v-for="item in recentDecisions"
+              v-for="item in twinStore.recentDecisions"
               :key="item.episode.id"
               class="compact-row"
               :class="{ highlighted: item.episode.id === routeDecisionId }"
-              @click="activeTab = 'decisions'"
+              @click="twinStore.activeTab = 'decisions'"
             >
               <span
                 class="row-dot"
@@ -165,22 +165,22 @@
               <h2>Current Action Gaps</h2>
               <button
                 class="text-button"
-                @click="activeTab = 'action_gaps'"
+                @click="twinStore.activeTab = 'action_gaps'"
               >
                 Review
               </button>
             </div>
             <div
-              v-if="topActionGaps.length === 0"
+              v-if="twinStore.topActionGaps.length === 0"
               class="empty-panel"
             >
               No action gaps found.
             </div>
             <button
-              v-for="gap in topActionGaps"
+              v-for="gap in twinStore.topActionGaps"
               :key="gap.id"
               class="compact-row"
-              @click="activeTab = 'action_gaps'"
+              @click="twinStore.activeTab = 'action_gaps'"
             >
               <span class="row-dot is-pending" />
               <span class="row-title">{{ gap.decision_risk }}</span>
@@ -192,30 +192,30 @@
         </section>
 
         <section
-          v-else-if="activeTab === 'constitution'"
+          v-else-if="twinStore.activeTab === 'constitution'"
           class="tab-panel"
         >
           <div class="panel-header">
             <div>
               <h2>Constitution</h2>
-              <span>The value rules the twin reasons from — {{ groupedConstitution.length }} dimensions</span>
+              <span>The value rules the twin reasons from — {{ twinStore.groupedConstitution.length }} dimensions</span>
             </div>
             <button
               class="btn btn-secondary btn-sm"
-              @click="activeTab = 'setup'"
+              @click="twinStore.activeTab = 'setup'"
             >
               Setup
             </button>
           </div>
 
           <div
-            v-if="constitutionItems.length === 0"
+            v-if="twinStore.constitutionItems.length === 0"
             class="empty-panel"
           >
             No constitution items yet. Run Constitution to infer them from records and decisions.
           </div>
           <section
-            v-for="group in groupedConstitution"
+            v-for="group in twinStore.groupedConstitution"
             :key="group.dimension"
             class="dimension-section"
           >
@@ -251,81 +251,81 @@
                 >{{ scope }}</span>
               </div>
               <ReviewActions
-                @review="action => reviewConstitutionItem(item.id, action)"
+                @review="action => twinStore.reviewConstitutionItem(item.id, action)"
               />
             </article>
           </section>
         </section>
 
         <section
-          v-else-if="activeTab === 'action_gaps'"
+          v-else-if="twinStore.activeTab === 'action_gaps'"
           class="tab-panel"
         >
           <div class="panel-header">
             <div>
               <h2>Action Gaps</h2>
-              <span>{{ actionGaps.length }} stated versus revealed patterns</span>
+              <span>{{ twinStore.actionGaps.length }} stated versus revealed patterns</span>
             </div>
           </div>
           <div
-            v-if="actionGaps.length === 0"
+            v-if="twinStore.actionGaps.length === 0"
             class="empty-panel"
           >
             No action gaps yet.
           </div>
           <ActionGapRow
-            v-for="gap in actionGaps"
+            v-for="gap in twinStore.actionGaps"
             :key="gap.id"
             :gap="gap"
-            @review="reviewActionGap"
+            @review="twinStore.reviewActionGap"
           />
         </section>
 
         <section
-          v-else-if="activeTab === 'decisions'"
+          v-else-if="twinStore.activeTab === 'decisions'"
           class="tab-panel"
         >
           <div class="panel-header">
             <div>
               <h2>Decisions</h2>
-              <span>{{ decisions.length }} episodes — record what you actually chose to reveal each sealed twin prediction</span>
+              <span>{{ twinStore.decisions.length }} episodes — record what you actually chose to reveal each sealed twin prediction</span>
             </div>
           </div>
           <div
-            v-if="decisions.length === 0"
+            v-if="twinStore.decisions.length === 0"
             class="empty-panel"
           >
             No decision episodes yet. Start a Decision in Canvas and it will appear here.
           </div>
           <DecisionRow
-            v-for="item in decisions"
+            v-for="item in twinStore.decisions"
             :key="item.episode.id"
             :item="item"
             :highlighted="item.episode.id === routeDecisionId"
             :trace-open="item.episode.id === routeDecisionId && routeTraceRequested"
-            @update-outcome="updateDecisionOutcome"
+            @update-outcome="twinStore.updateDecisionOutcome"
           />
         </section>
 
         <section
-          v-else-if="activeTab === 'memory'"
+          v-else-if="twinStore.activeTab === 'memory'"
           class="tab-panel memory-grid"
         >
           <section class="workspace-band">
             <div class="panel-header compact">
               <div>
                 <h2>Adaptive Digest</h2>
-                <span>{{ memoryDigestItems.length }} clustered items</span>
+                <span>{{ twinStore.memoryDigestItems.length }} clustered items</span>
               </div>
             </div>
             <div
-              v-if="memoryDigestItems.length === 0"
+              v-if="twinStore.memoryDigestItems.length === 0"
               class="empty-panel"
             >
               No digest items need review.
             </div>
             <article
-              v-for="item in memoryDigestItems"
+              v-for="item in twinStore.memoryDigestItems"
               :key="item.id"
               class="digest-card"
             >
@@ -337,7 +337,7 @@
               <p>{{ item.pattern }}</p>
               <small v-if="item.latest_evidence?.summary">{{ item.latest_evidence.summary }}</small>
               <ReviewActions
-                @review="action => reviewMemoryDigestItem(item.id, action)"
+                @review="action => twinStore.reviewMemoryDigestItem(item.id, action)"
               />
             </article>
           </section>
@@ -346,9 +346,9 @@
             <div class="panel-header compact">
               <div>
                 <h2>User Records</h2>
-                <span>{{ filteredReviewRecords.length }} shown</span>
+                <span>{{ twinStore.filteredReviewRecords.length }} shown</span>
               </div>
-              <select v-model="selectedRecordState">
+              <select v-model="twinStore.selectedRecordState">
                 <option
                   v-for="state in recordStates"
                   :key="state"
@@ -359,13 +359,13 @@
               </select>
             </div>
             <div
-              v-if="filteredReviewRecords.length === 0"
+              v-if="twinStore.filteredReviewRecords.length === 0"
               class="empty-panel"
             >
               No records in this state.
             </div>
             <article
-              v-for="item in filteredReviewRecords"
+              v-for="item in twinStore.filteredReviewRecords"
               :key="item.record.id"
               class="record-card"
             >
@@ -376,19 +376,19 @@
               </div>
               <p>{{ item.record.content }}</p>
               <div class="record-actions">
-                <button @click="openEvidence(item.record.id)">
+                <button @click="twinStore.openEvidence(item.record.id)">
                   Evidence
                 </button>
-                <button @click="setPromotion(item.record.id, 'endorsed')">
+                <button @click="twinStore.setPromotion(item.record.id, 'endorsed')">
                   Endorse
                 </button>
-                <button @click="setPromotion(item.record.id, 'private')">
+                <button @click="twinStore.setPromotion(item.record.id, 'private')">
                   Private
                 </button>
-                <button @click="setPromotion(item.record.id, 'no_train')">
+                <button @click="twinStore.setPromotion(item.record.id, 'no_train')">
                   No Train
                 </button>
-                <button @click="setPromotion(item.record.id, 'rejected')">
+                <button @click="twinStore.setPromotion(item.record.id, 'rejected')">
                   Reject
                 </button>
               </div>
@@ -397,7 +397,7 @@
         </section>
 
         <section
-          v-else-if="activeTab === 'setup'"
+          v-else-if="twinStore.activeTab === 'setup'"
           class="tab-panel setup-grid"
         >
           <section class="identity-section">
@@ -408,7 +408,7 @@
             <label class="identity-field">
               <span>Name</span>
               <input
-                v-model="setupDraft.twin_name"
+                v-model="twinStore.setupDraft.twin_name"
                 aria-label="Twin name"
                 type="text"
                 placeholder="Who is this twin?"
@@ -417,14 +417,14 @@
             <label class="identity-field">
               <span>Role / context</span>
               <input
-                v-model="setupDraft.twin_role"
+                v-model="twinStore.setupDraft.twin_role"
                 aria-label="Twin role"
                 type="text"
                 placeholder="What role should this twin reason from?"
               >
             </label>
             <SetupField
-              v-model="setupDraft.source_boundaries"
+              v-model="twinStore.setupDraft.source_boundaries"
               title="Source Boundaries"
             />
           </section>
@@ -433,148 +433,66 @@
             <span>Values, taste, constraints, somatic cues, and action tendencies.</span>
           </div>
           <SetupField
-            v-model="setupDraft.values"
+            v-model="twinStore.setupDraft.values"
             title="Values"
           />
           <SetupField
-            v-model="setupDraft.tastes"
+            v-model="twinStore.setupDraft.tastes"
             title="Taste"
           />
           <SetupField
-            v-model="setupDraft.constraints"
+            v-model="twinStore.setupDraft.constraints"
             title="Constraints"
           />
           <SetupField
-            v-model="setupDraft.somatic_cues"
+            v-model="twinStore.setupDraft.somatic_cues"
             title="Somatic Cues"
           />
           <SetupField
-            v-model="setupDraft.action_tendencies"
+            v-model="twinStore.setupDraft.action_tendencies"
             title="Action Tendencies"
           />
           <div class="setup-actions">
             <button
               class="btn btn-primary"
-              :disabled="savingSetup"
-              @click="saveSetup"
+              :disabled="twinStore.savingSetup"
+              @click="twinStore.saveSetup"
             >
-              {{ savingSetup ? 'Saving...' : 'Save Setup' }}
+              {{ twinStore.savingSetup ? 'Saving...' : 'Save Setup' }}
             </button>
           </div>
         </section>
 
-        <TwinGuideTab v-else-if="activeTab === 'guide'" />
+        <TwinGuideTab v-else-if="twinStore.activeTab === 'guide'" />
 
-        <section
-          v-else-if="activeTab === 'config'"
-          class="tab-panel config-panel"
-        >
-          <div class="panel-header">
-            <div>
-              <h2>Decision Mirror Config</h2>
-              <span>Presets change retrieval and scoring weights without hiding raw sub-scores.</span>
-            </div>
-            <button
-              class="btn btn-secondary btn-sm"
-              :disabled="exportingBenchmark"
-              @click="exportDecisionBenchmark"
-            >
-              {{ exportingBenchmark ? 'Exporting...' : 'Export Benchmark' }}
-            </button>
-          </div>
-
-          <section class="workspace-band config-card">
-            <label class="config-row">
-              <span>Preset</span>
-              <select v-model="configDraft.preset">
-                <option
-                  v-for="preset in decisionMirrorPresets"
-                  :key="preset.value"
-                  :value="preset.value"
-                >
-                  {{ preset.label }}
-                </option>
-              </select>
-            </label>
-            <label class="config-toggle">
-              <input
-                v-model="configDraft.advanced_enabled"
-                type="checkbox"
-              >
-              <span>Advanced</span>
-            </label>
-            <div class="config-actions">
-              <button
-                class="btn btn-primary"
-                :disabled="savingConfig"
-                @click="saveDecisionMirrorConfig"
-              >
-                {{ savingConfig ? 'Saving...' : 'Save Config' }}
-              </button>
-              <button
-                class="btn btn-secondary"
-                :disabled="savingConfig"
-                @click="resetDecisionMirrorConfig"
-              >
-                Reset
-              </button>
-            </div>
-          </section>
-
-          <section
-            v-if="configDraft.advanced_enabled"
-            class="workspace-band config-card"
-          >
-            <div class="panel-header compact">
-              <div>
-                <h2>Advanced Weights</h2>
-                <span>0 ignores the signal, 3 gives it strong priority.</span>
-              </div>
-            </div>
-            <label
-              v-for="weight in configWeightRows"
-              :key="weight.key"
-              class="weight-row"
-            >
-              <span>{{ weight.label }}</span>
-              <input
-                v-model.number="configDraft.weights[weight.key]"
-                type="range"
-                min="0"
-                max="3"
-                step="0.05"
-              >
-              <strong>{{ formatWeight(configDraft.weights[weight.key]) }}</strong>
-            </label>
-          </section>
-        </section>
+        <TwinConfigTab v-else-if="twinStore.activeTab === 'config'" />
       </main>
     </div>
 
     <aside
-      v-if="selectedRecordId"
+      v-if="twinStore.selectedRecordId"
       class="evidence-drawer"
     >
       <div class="drawer-header">
         <h2>Evidence</h2>
-        <button @click="selectedRecordId = null">
+        <button @click="twinStore.selectedRecordId = null">
           x
         </button>
       </div>
       <div
-        v-if="evidenceLoading"
+        v-if="twinStore.evidenceLoading"
         class="empty-panel"
       >
         Loading evidence...
       </div>
       <div
-        v-else-if="selectedEvidence.length === 0"
+        v-else-if="twinStore.selectedEvidence.length === 0"
         class="empty-panel"
       >
         No evidence events found.
       </div>
       <article
-        v-for="item in selectedEvidence"
+        v-for="item in twinStore.selectedEvidence"
         :key="item.event_id"
         class="evidence-item"
       >
@@ -593,20 +511,43 @@
     </aside>
 
     <div
-      v-if="message"
+      v-if="twinStore.message"
       class="save-toast"
-      :class="message.type"
+      :class="twinStore.message.type"
     >
-      {{ message.text }}
+      {{ twinStore.message.text }}
     </div>
   </div>
 </template>
 
 <script setup>
-import { computed, defineComponent, h, onMounted, reactive, ref } from 'vue'
+import { computed, defineComponent, h, onMounted, ref } from 'vue'
 import { useRoute } from 'vue-router'
-import { twin } from '@/api/client'
+import { useTwinStore } from '@/stores/twin'
+import {
+  decisionState,
+  decisionChips,
+  actionLabel,
+  statusLabel,
+  kindLabel,
+  dimensionLabel,
+  formatPercent,
+  formatWeight,
+  presetLabel,
+  sourceTypeLabel,
+  constitutionSourceLabel,
+  constitutionEvidenceLabels,
+  scoreRows,
+  feedbackEventLabel,
+  feedbackEventNote,
+  formatDate,
+  eventLabel
+} from '@/utils/twinFormat'
 import TwinGuideTab from '@/components/twin/TwinGuideTab.vue'
+import TwinConfigTab from '@/components/twin/TwinConfigTab.vue'
+import '@/components/twin/twin-workspace.css'
+
+const twinStore = useTwinStore()
 
 const navGroups = computed(() => [
   {
@@ -617,15 +558,15 @@ const navGroups = computed(() => [
   {
     id: 'work',
     label: 'Work',
-    tabs: [{ id: 'decisions', label: 'Decisions', count: decisions.value.length }]
+    tabs: [{ id: 'decisions', label: 'Decisions', count: twinStore.decisions.length }]
   },
   {
     id: 'review',
     label: 'Review',
     tabs: [
-      { id: 'memory', label: 'Memory Review', count: pendingReviewCount.value },
-      { id: 'constitution', label: 'Constitution', count: constitutionItems.value.length },
-      { id: 'action_gaps', label: 'Action Gaps', count: actionGaps.value.length }
+      { id: 'memory', label: 'Memory Review', count: twinStore.pendingReviewCount },
+      { id: 'constitution', label: 'Constitution', count: twinStore.constitutionItems.length },
+      { id: 'action_gaps', label: 'Action Gaps', count: twinStore.actionGaps.length }
     ]
   },
   {
@@ -900,1426 +841,15 @@ const primitiveFields = [
   { key: 'action_gap_risk', label: 'Gap Risk' }
 ]
 
-const tutorialStorageKey = 'grafyn.twinWorkspaceTutorial.dismissed'
-const decisionMirrorPresets = [
-  { value: 'balanced', label: 'Balanced' },
-  { value: 'evidence_strict', label: 'Stricter Evidence' },
-  { value: 'insight_search', label: 'Find Blind Spots' },
-  { value: 'action_bias', label: 'Push Next Action' }
-]
-const configWeightRows = [
-  { key: 'notes_weight', label: 'Vault Evidence' },
-  { key: 'approved_records_weight', label: 'Trusted Self-Model' },
-  { key: 'candidate_records_weight', label: 'Tentative Patterns' },
-  { key: 'constitution_weight', label: 'Values Fit' },
-  { key: 'action_gaps_weight', label: 'Follow-Through Risk' },
-  { key: 'recency_weight', label: 'Current Self' },
-  { key: 'evidence_count_weight', label: 'Repeated Evidence' },
-  { key: 'outcome_history_weight', label: 'Past Outcomes' },
-  { key: 'contradiction_weight', label: 'Tensions' },
-  { key: 'breadth_weight', label: 'Reflection Breadth' },
-  { key: 'depth_weight', label: 'Reflection Depth' },
-  { key: 'evidence_grounding_weight', label: 'Grounded Claims' },
-  { key: 'blind_spot_weight', label: 'Blind Spots' },
-  { key: 'counter_position_weight', label: 'Counterargument' },
-  { key: 'actionability_weight', label: 'Next Step Clarity' },
-  { key: 'uncertainty_weight', label: 'Honest Uncertainty' },
-  { key: 'privacy_weight', label: 'Privacy Safety' },
-  { key: 'unsupported_penalty_weight', label: 'Unsupported Claim Penalty' }
-]
 const recordStates = ['candidate', 'auto_promoted', 'endorsed', 'private', 'no_train', 'rejected']
 const route = useRoute() || { query: {} }
-const activeTab = ref(route.query?.decision ? 'decisions' : 'overview')
-const reviewRecords = ref([])
-const memoryDigestItems = ref([])
-const constitutionItems = ref([])
-const actionGaps = ref([])
-const decisions = ref([])
-const selectedRecordState = ref('candidate')
-const selectedRecordId = ref(null)
-const selectedEvidence = ref([])
-const evidenceLoading = ref(false)
-const runningTwinInference = ref(false)
-const runningConstitutionInference = ref(false)
-const savingSetup = ref(false)
-const savingConfig = ref(false)
-const exportingBenchmark = ref(false)
-const message = ref(null)
-const showTutorialIntro = ref(localStorage.getItem(tutorialStorageKey) !== 'true')
-const setupDraft = reactive({
-  twin_name: '',
-  twin_role: '',
-  source_boundaries: '',
-  values: '',
-  tastes: '',
-  constraints: '',
-  somatic_cues: '',
-  action_tendencies: ''
-})
-const configDraft = reactive({
-  preset: 'balanced',
-  advanced_enabled: false,
-  weights: defaultDecisionMirrorWeights()
-})
+// Matches the original per-mount ref initialization: every time this view
+// mounts, the active tab is (re)computed from the current route query.
+twinStore.activeTab = route.query?.decision ? 'decisions' : 'overview'
 
 const routeDecisionId = computed(() => String(route.query?.decision || ''))
 const routeTraceRequested = computed(() => route.query?.trace === '1')
-const activeConstitutionCount = computed(() =>
-  constitutionItems.value.filter(item => ['active', 'candidate', 'softened'].includes(item.status)).length
-)
-const activeActionGapCount = computed(() =>
-  actionGaps.value.filter(gap => ['active', 'candidate', 'softened'].includes(gap.status)).length
-)
-const pendingReviewCount = computed(() =>
-  memoryDigestItems.value.length + reviewRecords.value.filter(item => item.record.promotion_state === 'candidate').length
-)
-const pendingOutcomeCount = computed(() =>
-  decisions.value.filter(item => !item.episode.outcome).length
-)
-const healthSummary = computed(() =>
-  `${constitutionItems.value.length} principles / ${actionGaps.value.length} gaps / ${decisions.value.length} decisions`
-)
-const recentDecisions = computed(() => decisions.value.slice(0, 4))
-const topActionGaps = computed(() => actionGaps.value.slice(0, 4))
-const filteredReviewRecords = computed(() =>
-  reviewRecords.value.filter(item => item.record.promotion_state === selectedRecordState.value)
-)
-const groupedConstitution = computed(() => {
-  const groups = new Map()
-  for (const item of constitutionItems.value) {
-    const key = item.dimension || 'general'
-    if (!groups.has(key)) groups.set(key, [])
-    groups.get(key).push(item)
-  }
-  return [...groups.entries()]
-    .sort(([a], [b]) => a.localeCompare(b))
-    .map(([dimension, items]) => ({ dimension, items }))
-})
-
-onMounted(loadWorkspace)
-
-async function loadWorkspace() {
-  try {
-    const [
-      review,
-      digest,
-      constitution,
-      gaps,
-      decisionRows,
-      setup,
-      mirrorConfig
-    ] = await Promise.all([
-      twin.getReview(),
-      twin.listMemoryDigest(),
-      twin.listConstitutionItems(),
-      twin.listActionGaps(),
-      twin.listDecisionEpisodes(),
-      twin.getConstitutionSetup(),
-      twin.getDecisionMirrorConfig()
-    ])
-    reviewRecords.value = review
-    memoryDigestItems.value = digest
-    constitutionItems.value = constitution
-    actionGaps.value = gaps
-    decisions.value = decisionRows
-    loadSetupDraft(setup)
-    loadConfigDraft(mirrorConfig)
-  } catch (err) {
-    showMessage('error', err.message || 'Failed to load twin workspace')
-  }
-}
-
-async function runTwinInference() {
-  runningTwinInference.value = true
-  try {
-    const summary = await twin.runInference()
-    await loadWorkspace()
-    showMessage('success', `Records: ${summary.created_records} created, ${summary.updated_records} updated`, 3500)
-  } catch (err) {
-    showMessage('error', err.message || 'Failed to run record inference')
-  } finally {
-    runningTwinInference.value = false
-  }
-}
-
-async function runConstitutionInference() {
-  runningConstitutionInference.value = true
-  try {
-    const summary = await twin.runConstitutionInference()
-    await loadWorkspace()
-    showMessage('success', constitutionRunSummary(summary), 4500)
-  } catch (err) {
-    showMessage('error', err.message || 'Failed to run constitution inference')
-  } finally {
-    runningConstitutionInference.value = false
-  }
-}
-
-async function reviewConstitutionItem(id, action) {
-  try {
-    await twin.reviewConstitutionItem(id, { action })
-    await loadWorkspace()
-    showMessage('success', 'Updated constitution item', 1800)
-  } catch (err) {
-    showMessage('error', err.message || 'Failed to update constitution item')
-  }
-}
-
-async function reviewActionGap(id, action) {
-  try {
-    await twin.reviewActionGap(id, { action })
-    await loadWorkspace()
-    showMessage('success', 'Updated action gap', 1800)
-  } catch (err) {
-    showMessage('error', err.message || 'Failed to update action gap')
-  }
-}
-
-async function reviewMemoryDigestItem(id, action) {
-  try {
-    await twin.reviewMemoryDigestItem(id, { action })
-    await loadWorkspace()
-    showMessage('success', 'Updated digest item', 1800)
-  } catch (err) {
-    showMessage('error', err.message || 'Failed to update digest item')
-  }
-}
-
-async function setPromotion(recordId, promotionState) {
-  try {
-    await twin.setPromotion(recordId, promotionState, null)
-    await loadWorkspace()
-    showMessage('success', `Set record to ${statusLabel(promotionState)}`, 1800)
-  } catch (err) {
-    showMessage('error', err.message || 'Failed to update record')
-  }
-}
 
-async function openEvidence(recordId) {
-  selectedRecordId.value = recordId
-  selectedEvidence.value = []
-  evidenceLoading.value = true
-  try {
-    selectedEvidence.value = await twin.resolveEvidence(recordId)
-  } catch (err) {
-    showMessage('error', err.message || 'Failed to load evidence')
-  } finally {
-    evidenceLoading.value = false
-  }
-}
-
-async function updateDecisionOutcome(id, update) {
-  try {
-    const payload = { ...update }
-    if (payload.regret_score == null) delete payload.regret_score
-    await twin.updateDecisionOutcome(id, payload)
-    await loadWorkspace()
-    showMessage('success', 'Updated decision outcome', 1800)
-  } catch (err) {
-    showMessage('error', err.message || 'Failed to update decision')
-  }
-}
-
-async function saveSetup() {
-  savingSetup.value = true
-  try {
-    await twin.saveConstitutionSetup({
-      twin_name: setupDraft.twin_name.trim(),
-      twin_role: setupDraft.twin_role.trim(),
-      source_boundaries: splitLines(setupDraft.source_boundaries),
-      values: splitLines(setupDraft.values),
-      tastes: splitLines(setupDraft.tastes),
-      constraints: splitLines(setupDraft.constraints),
-      somatic_cues: splitLines(setupDraft.somatic_cues),
-      action_tendencies: splitLines(setupDraft.action_tendencies)
-    })
-    await loadWorkspace()
-    showMessage('success', 'Saved setup', 2000)
-  } catch (err) {
-    showMessage('error', err.message || 'Failed to save setup')
-  } finally {
-    savingSetup.value = false
-  }
-}
-
-async function saveDecisionMirrorConfig() {
-  savingConfig.value = true
-  try {
-    const update = {
-      preset: configDraft.preset,
-      advanced_enabled: configDraft.advanced_enabled
-    }
-    if (configDraft.advanced_enabled) {
-      update.weights = { ...configDraft.weights }
-    }
-    const config = await twin.updateDecisionMirrorConfig(update)
-    loadConfigDraft(config)
-    showMessage('success', 'Saved Decision Mirror config', 2000)
-  } catch (err) {
-    showMessage('error', err.message || 'Failed to save Decision Mirror config')
-  } finally {
-    savingConfig.value = false
-  }
-}
-
-async function resetDecisionMirrorConfig() {
-  savingConfig.value = true
-  try {
-    const config = await twin.resetDecisionMirrorConfig()
-    loadConfigDraft(config)
-    showMessage('success', 'Reset Decision Mirror config', 2000)
-  } catch (err) {
-    showMessage('error', err.message || 'Failed to reset Decision Mirror config')
-  } finally {
-    savingConfig.value = false
-  }
-}
-
-async function exportDecisionBenchmark() {
-  exportingBenchmark.value = true
-  try {
-    const bundle = await twin.exportData({ bundle_name: 'decision-mirror-benchmark' })
-    showMessage(
-      'success',
-      `Exported benchmark: ${bundle.decision_mirror_benchmark?.count || 0} decisions`,
-      3500
-    )
-  } catch (err) {
-    showMessage('error', err.message || 'Failed to export benchmark')
-  } finally {
-    exportingBenchmark.value = false
-  }
-}
-
-function dismissTutorial() {
-  localStorage.setItem(tutorialStorageKey, 'true')
-  showTutorialIntro.value = false
-}
-
-function loadSetupDraft(setup) {
-  setupDraft.twin_name = setup?.twin_name || ''
-  setupDraft.twin_role = setup?.twin_role || ''
-  setupDraft.source_boundaries = (setup?.source_boundaries || []).join('\n')
-  setupDraft.values = (setup?.values || []).join('\n')
-  setupDraft.tastes = (setup?.tastes || []).join('\n')
-  setupDraft.constraints = (setup?.constraints || []).join('\n')
-  setupDraft.somatic_cues = (setup?.somatic_cues || []).join('\n')
-  setupDraft.action_tendencies = (setup?.action_tendencies || []).join('\n')
-}
-
-function loadConfigDraft(config) {
-  configDraft.preset = config?.preset || 'balanced'
-  configDraft.advanced_enabled = Boolean(config?.advanced_enabled)
-  configDraft.weights = {
-    ...defaultDecisionMirrorWeights(),
-    ...(config?.weights || {})
-  }
-}
-
-function defaultDecisionMirrorWeights() {
-  return Object.fromEntries(configWeightRows.map(row => [row.key, 1]))
-}
-
-function splitLines(value) {
-  return value
-    .split('\n')
-    .map(line => line.trim())
-    .filter(Boolean)
-}
-
-function decisionState(item) {
-  if (item.prediction_sealed) return 'is-sealed'
-  if (item.episode.agreement === true) return 'is-match'
-  if (item.episode.agreement === false) return 'is-miss'
-  if (!item.episode.outcome) return 'is-pending'
-  return ''
-}
-
-function decisionChips(item) {
-  const chips = []
-  if (item.prediction_sealed) chips.push({ id: 'sealed', label: 'Sealed', cls: 'chip-sealed' })
-  if (item.episode.agreement === true) chips.push({ id: 'match', label: 'Matched', cls: 'chip-match' })
-  if (item.episode.agreement === false) chips.push({ id: 'miss', label: 'Missed', cls: 'chip-miss' })
-  if (!item.episode.outcome) chips.push({ id: 'pending', label: 'Outcome pending', cls: 'chip-pending' })
-  return chips
-}
-
-function actionLabel(action) {
-  return {
-    keep: 'Keep',
-    soften: 'Soften',
-    not_me: 'Not Me',
-    private: 'Private',
-    no_train: 'No Train',
-    reject: 'Reject'
-  }[action] || action
-}
-
-function statusLabel(value) {
-  return String(value || 'unknown')
-    .split('_')
-    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
-    .join(' ')
-}
-
-function kindLabel(value) {
-  return statusLabel(value)
-}
-
-function dimensionLabel(value) {
-  return statusLabel(value || 'general')
-}
-
-function formatPercent(value) {
-  return `${Math.round((value || 0) * 100)}%`
-}
-
-function formatWeight(value) {
-  return Number(value || 0).toFixed(2)
-}
-
-function presetLabel(value) {
-  const preset = decisionMirrorPresets.find(item => item.value === value)
-  return preset?.label || statusLabel(value || 'balanced')
-}
-
-function sourceTypeLabel(value) {
-  const labels = {
-    note: 'Note',
-    behavior: 'Behavior',
-    'interview-question': 'Interview Question',
-    'interview-answer': 'Interview Answer',
-    decision: 'Decision',
-    setup: 'Setup',
-    approved_record: 'Approved Record',
-    candidate_record: 'Candidate Record',
-    constitution_item: 'Constitution',
-    action_gap: 'Action Gap'
-  }
-  return labels[value] || statusLabel(value)
-}
-
-function constitutionSourceLabel(item) {
-  if (item.source) return sourceTypeLabel(item.source)
-  const first = item.evidence_refs?.[0]
-  return sourceTypeLabel(first?.source_type || 'evidence')
-}
-
-function constitutionEvidenceLabels(item) {
-  const labels = new Set()
-  for (const ref of item.evidence_refs || []) {
-    if (ref.source_type) labels.add(sourceTypeLabel(ref.source_type))
-    if (ref.source_label) labels.add(ref.source_label)
-  }
-  return [...labels].slice(0, 4)
-}
-
-function constitutionRunSummary(summary = {}) {
-  const parts = [
-    `${summary.created_constitution_items || 0} items`,
-    `${summary.created_action_gaps || 0} gaps`
-  ]
-  if (summary.auto_active_items) parts.push(`${summary.auto_active_items} active`)
-  if (summary.review_candidate_items) parts.push(`${summary.review_candidate_items} review`)
-  if (summary.scanned_behavior_events) parts.push(`${summary.scanned_behavior_events} behavior events`)
-  if (summary.scanned_notes) parts.push(`${summary.scanned_notes} notes`)
-  if (summary.scanned_interviews) parts.push(`${summary.scanned_interviews} interviews`)
-  if (summary.extracted_research_findings) parts.push(`${summary.extracted_research_findings} findings`)
-  if (summary.pruned_stale_constitution_items) parts.push(`${summary.pruned_stale_constitution_items} stale items removed`)
-  if (summary.pruned_stale_records) parts.push(`${summary.pruned_stale_records} stale records removed`)
-  if (summary.updated_setup_entries) parts.push(`${summary.updated_setup_entries} setup entries`)
-  if (summary.skipped_domain_claims) parts.push(`${summary.skipped_domain_claims} skipped`)
-  return `Constitution: ${parts.join(' / ')}`
-}
-
-function scoreRows(scores = {}) {
-  return [
-    ['Breadth', scores.breadth_score],
-    ['Depth', scores.depth_score],
-    ['Grounding', scores.evidence_grounding_score],
-    ['Blind Spot', scores.blind_spot_score],
-    ['Action', scores.actionability_score],
-    ['Counter', scores.counterargument_score],
-    ['Uncertainty', scores.uncertainty_score],
-    ['Privacy', scores.privacy_score],
-    ['Overall', scores.overall_score]
-  ].map(([label, value]) => ({
-    label,
-    value: value == null ? 'n/a' : formatPercent(value)
-  }))
-}
-
-function feedbackEventLabel(event = {}) {
-  return statusLabel(event.payload?.feedback_type || event.event_type || 'feedback')
-}
-
-function feedbackEventNote(event = {}) {
-  return event.payload?.rationale
-    || event.payload?.content
-    || event.payload?.response?.response_excerpt
-    || event.payload?.response?.response_content
-    || 'Feedback recorded'
-}
-
-function formatDate(value) {
-  return value ? new Date(value).toLocaleString() : ''
-}
-
-function eventLabel(value) {
-  return statusLabel(value)
-}
-
-function showMessage(type, text, duration = 3500) {
-  message.value = { type, text }
-  setTimeout(() => {
-    if (message.value?.text === text) message.value = null
-  }, duration)
-}
+onMounted(twinStore.loadWorkspace)
 </script>
 
-<style scoped>
-.twin-workspace {
-  display: flex;
-  flex-direction: column;
-  height: 100vh;
-  overflow: hidden;
-  background: var(--bg-primary);
-  color: var(--text-primary);
-}
-
-.workspace-header {
-  flex: 0 0 auto;
-  display: grid;
-  grid-template-columns: 1fr auto 1fr;
-  align-items: center;
-  gap: var(--spacing-md);
-  padding: var(--spacing-sm) var(--spacing-lg);
-  border-bottom: 1px solid var(--border-default);
-  background: var(--bg-secondary);
-}
-
-.header-links,
-.header-actions {
-  display: flex;
-  align-items: center;
-  gap: var(--spacing-sm);
-}
-
-.header-actions {
-  justify-content: flex-end;
-}
-
-.header-actions.compact {
-  gap: 6px;
-}
-
-.header-links a {
-  color: var(--text-secondary);
-  text-decoration: none;
-}
-
-.header-links a:hover {
-  color: var(--accent-primary);
-}
-
-.header-title {
-  text-align: center;
-}
-
-.header-title h1 {
-  margin: 0;
-  font-size: 1.125rem;
-}
-
-.header-title span,
-.panel-header span,
-.card-topline,
-.metric-tile small,
-.evidence-item small,
-.digest-card small,
-.muted {
-  color: var(--text-muted);
-  font-size: 0.75rem;
-}
-
-.header-title span {
-  font-family: 'Fira Code', monospace;
-  font-size: 0.7rem;
-  letter-spacing: 0.02em;
-}
-
-/* Body: fixed rail + independently scrolling main pane.
-   #app is overflow:hidden, so this view must own its scrolling. */
-.workspace-body {
-  flex: 1;
-  display: flex;
-  min-height: 0;
-}
-
-.workspace-rail {
-  flex: 0 0 212px;
-  display: flex;
-  flex-direction: column;
-  gap: 2px;
-  padding: var(--spacing-sm) var(--spacing-sm) var(--spacing-lg) 0;
-  overflow-y: auto;
-  border-right: 1px solid var(--border-default);
-  background: var(--bg-secondary);
-}
-
-.rail-label {
-  margin: var(--spacing-md) var(--spacing-sm) 4px var(--spacing-md);
-  font-size: 0.65rem;
-  font-weight: 700;
-  letter-spacing: 0.14em;
-  text-transform: uppercase;
-  color: var(--text-muted);
-}
-
-.tab-button {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: 8px;
-  width: 100%;
-  min-height: 34px;
-  padding: 0 var(--spacing-sm) 0 13px;
-  border: none;
-  border-left: 3px solid transparent;
-  border-radius: 0 var(--radius-sm) var(--radius-sm) 0;
-  background: transparent;
-  color: var(--text-secondary);
-  font-size: 0.85rem;
-  text-align: left;
-  cursor: pointer;
-  transition: background var(--transition-fast), color var(--transition-fast);
-}
-
-.tab-button:hover {
-  background: var(--bg-hover);
-  color: var(--text-primary);
-}
-
-.tab-button.active {
-  border-left-color: var(--accent-primary);
-  background: color-mix(in srgb, var(--accent-primary) 12%, transparent);
-  color: var(--accent-primary);
-  font-weight: 600;
-}
-
-.tab-button strong {
-  min-width: 22px;
-  font-family: 'Fira Code', monospace;
-  font-size: 0.7rem;
-  font-weight: 500;
-  text-align: right;
-  color: var(--text-muted);
-}
-
-.tab-button.active strong {
-  color: var(--accent-primary);
-}
-
-.workspace-main {
-  flex: 1;
-  min-width: 0;
-  overflow-y: auto;
-  padding: var(--spacing-lg);
-}
-
-.tab-panel {
-  display: flex;
-  flex-direction: column;
-  gap: var(--spacing-md);
-  max-width: 980px;
-  margin: 0 auto;
-}
-
-.overview-stats {
-  display: grid;
-  grid-template-columns: repeat(4, minmax(0, 1fr));
-  gap: var(--spacing-md);
-}
-
-.metric-tile {
-  display: flex;
-  flex-direction: column;
-  align-items: flex-start;
-  gap: 2px;
-  padding: var(--spacing-md);
-  border: 1px solid var(--border-default);
-  border-radius: var(--radius-lg);
-  background: var(--bg-secondary);
-  color: var(--text-secondary);
-  text-align: left;
-  cursor: pointer;
-  transition: border-color var(--transition-fast), box-shadow var(--transition-fast), transform var(--transition-fast);
-}
-
-.metric-tile:hover {
-  border-color: var(--accent-primary);
-  box-shadow: var(--shadow-md);
-  transform: translateY(-1px);
-}
-
-.metric-tile strong {
-  display: block;
-  margin: 4px 0;
-  font-family: 'Fira Code', monospace;
-  font-size: 1.8rem;
-  font-weight: 600;
-  color: var(--text-primary);
-  line-height: 1.1;
-}
-
-.workspace-band,
-.constitution-card,
-.action-gap-card,
-.decision-card,
-.digest-card,
-.record-card,
-.evidence-drawer {
-  border: 1px solid var(--border-default);
-  border-radius: var(--radius-md);
-  background: var(--bg-secondary);
-}
-
-.workspace-band {
-  padding: var(--spacing-md);
-}
-
-.tutorial-intro {
-  border-left: 3px solid var(--accent-primary);
-}
-
-.band-header,
-.panel-header,
-.card-topline,
-.drawer-header {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: var(--spacing-sm);
-}
-
-.band-header {
-  margin-bottom: var(--spacing-sm);
-}
-
-.panel-header h2,
-.band-header h2,
-.drawer-header h2 {
-  margin: 0;
-  font-size: 1rem;
-}
-
-.panel-header.compact {
-  margin-bottom: var(--spacing-sm);
-}
-
-.text-button,
-.record-actions button,
-.review-actions button,
-.drawer-header button {
-  border: 1px solid var(--border-default);
-  border-radius: var(--radius-sm);
-  background: transparent;
-  color: var(--text-secondary);
-  cursor: pointer;
-}
-
-.text-button {
-  border: none;
-  color: var(--accent-primary);
-}
-
-.empty-panel {
-  padding: var(--spacing-lg);
-  border: 1px dashed var(--border-default);
-  border-radius: var(--radius-md);
-  color: var(--text-muted);
-  text-align: center;
-}
-
-/* Compact triage rows on the overview */
-.compact-row {
-  display: flex;
-  align-items: center;
-  gap: 10px;
-  width: 100%;
-  padding: 8px 10px;
-  margin-bottom: 6px;
-  border: 1px solid var(--border-subtle);
-  border-radius: var(--radius-sm);
-  background: transparent;
-  color: var(--text-primary);
-  text-align: left;
-  cursor: pointer;
-  transition: border-color var(--transition-fast), background var(--transition-fast);
-}
-
-.compact-row:hover {
-  border-color: var(--accent-primary);
-  background: var(--bg-hover);
-}
-
-.compact-row.highlighted {
-  border-color: var(--accent-cyan);
-}
-
-.row-dot {
-  flex: 0 0 8px;
-  width: 8px;
-  height: 8px;
-  border-radius: 50%;
-  background: var(--text-muted);
-}
-
-.row-dot.is-sealed {
-  background: var(--accent-primary);
-}
-
-.row-dot.is-pending {
-  background: var(--accent-warning);
-}
-
-.row-dot.is-match {
-  background: var(--accent-green);
-}
-
-.row-dot.is-miss {
-  background: var(--accent-red);
-}
-
-.row-title {
-  flex: 1;
-  min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-  font-size: 0.85rem;
-}
-
-.row-chips,
-.topline-chips {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 4px;
-}
-
-.chip {
-  display: inline-flex;
-  align-items: center;
-  padding: 1px 8px;
-  border: 1px solid var(--border-default);
-  border-radius: 999px;
-  font-size: 0.68rem;
-  font-weight: 600;
-  color: var(--text-secondary);
-  white-space: nowrap;
-}
-
-.chip-sealed {
-  border-style: dashed;
-  border-color: color-mix(in srgb, var(--accent-primary) 55%, transparent);
-  color: var(--accent-primary);
-}
-
-.chip-pending {
-  border-color: color-mix(in srgb, var(--accent-warning) 55%, transparent);
-  background: color-mix(in srgb, var(--accent-warning) 10%, transparent);
-  color: var(--accent-warning);
-}
-
-.chip-match {
-  border-color: color-mix(in srgb, var(--accent-green) 55%, transparent);
-  background: color-mix(in srgb, var(--accent-green) 10%, transparent);
-  color: var(--accent-green);
-}
-
-.chip-miss {
-  border-color: color-mix(in srgb, var(--accent-red) 55%, transparent);
-  background: color-mix(in srgb, var(--accent-red) 10%, transparent);
-  color: var(--accent-red);
-}
-
-.dimension-section h3 {
-  margin: 0 0 var(--spacing-sm);
-  font-size: 0.875rem;
-  color: var(--text-secondary);
-}
-
-.constitution-card,
-.action-gap-card,
-.decision-card,
-.digest-card,
-.record-card {
-  padding: var(--spacing-md);
-  margin-bottom: var(--spacing-sm);
-}
-
-/* Decision cards carry their state on the left edge */
-.decision-card {
-  border-left: 3px solid var(--border-strong);
-}
-
-.decision-card.is-sealed {
-  border-left-color: var(--accent-primary);
-}
-
-.decision-card.is-pending {
-  border-left-color: var(--accent-warning);
-}
-
-.decision-card.is-match {
-  border-left-color: var(--accent-green);
-}
-
-.decision-card.is-miss {
-  border-left-color: var(--accent-red);
-}
-
-.decision-card.highlighted {
-  border-color: var(--accent-cyan);
-  box-shadow: 0 0 0 2px color-mix(in srgb, var(--accent-cyan) 18%, transparent);
-}
-
-.decision-card h3 {
-  font-size: 0.95rem;
-  line-height: 1.4;
-}
-
-.constitution-card p,
-.action-gap-card p,
-.decision-card h3,
-.digest-card p,
-.record-card p,
-.evidence-item p {
-  margin: var(--spacing-sm) 0;
-}
-
-.card-topline {
-  flex-wrap: wrap;
-  justify-content: flex-start;
-}
-
-.card-topline .topline-chips {
-  margin-left: auto;
-}
-
-.status-pill,
-.tag-row span,
-.source-row span {
-  display: inline-flex;
-  align-items: center;
-  min-height: 22px;
-  padding: 0 7px;
-  border: 1px solid var(--border-default);
-  border-radius: var(--radius-sm);
-  color: var(--text-secondary);
-  font-size: 0.6875rem;
-}
-
-.tag-row,
-.source-row {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 4px;
-}
-
-.review-actions,
-.record-actions {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 6px;
-  margin-top: var(--spacing-sm);
-}
-
-.prediction-sealed-badge {
-  margin-top: var(--spacing-sm);
-  padding: 6px 10px;
-  border: 1px dashed color-mix(in srgb, var(--accent-primary) 45%, transparent);
-  border-radius: var(--radius-sm);
-  color: var(--accent-primary);
-  font-size: 0.8rem;
-}
-
-.prediction-reveal {
-  margin-top: var(--spacing-sm);
-  padding: var(--spacing-sm);
-  border: 1px solid var(--border-default);
-  border-radius: var(--radius-sm);
-  background: color-mix(in srgb, var(--bg-tertiary) 75%, transparent);
-}
-
-.prediction-headline {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  gap: 6px;
-  font-size: 0.85rem;
-}
-
-.prediction-confidence {
-  color: var(--text-secondary);
-}
-
-.prediction-rationale {
-  margin: 6px 0 0;
-  color: var(--text-secondary);
-  font-size: 0.8rem;
-}
-
-.agreement-badge {
-  padding: 2px 8px;
-  border-radius: 999px;
-  font-size: 0.72rem;
-}
-
-.agreement-badge.match {
-  background: color-mix(in srgb, var(--accent-green, #22c55e) 18%, transparent);
-  color: var(--accent-green, #22c55e);
-}
-
-.agreement-badge.miss {
-  background: color-mix(in srgb, var(--accent-red, #ef4444) 18%, transparent);
-  color: var(--accent-red, #ef4444);
-}
-
-.review-actions button,
-.record-actions button {
-  min-height: 28px;
-  padding: 4px 8px;
-}
-
-.review-actions button:hover,
-.record-actions button:hover {
-  border-color: var(--accent-primary);
-  color: var(--accent-primary);
-}
-
-.gap-columns {
-  display: grid;
-  grid-template-columns: repeat(2, minmax(0, 1fr));
-  gap: var(--spacing-md);
-}
-
-.gap-columns small {
-  color: var(--text-muted);
-}
-
-.primitive-grid {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 6px;
-  margin: var(--spacing-sm) 0;
-}
-
-.primitive-grid span {
-  padding: 4px 8px;
-  border: 1px solid var(--border-subtle);
-  border-radius: var(--radius-sm);
-  color: var(--text-secondary);
-  font-size: 0.75rem;
-}
-
-.reflection-details {
-  margin-top: var(--spacing-sm);
-}
-
-.context-trace-details {
-  margin-top: var(--spacing-sm);
-  border-top: 1px solid var(--border-subtle);
-  padding-top: var(--spacing-sm);
-}
-
-.context-trace-details summary,
-.reflection-details summary,
-.outcome-details summary {
-  cursor: pointer;
-  font-weight: 700;
-}
-
-.reflection-details pre {
-  max-height: 220px;
-  overflow: auto;
-  white-space: pre-wrap;
-  padding: var(--spacing-sm);
-  background: var(--bg-tertiary);
-  border-radius: var(--radius-sm);
-}
-
-.trace-metrics,
-.trace-score-grid {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(120px, 1fr));
-  gap: 6px;
-  margin: var(--spacing-sm) 0;
-}
-
-.trace-metrics span,
-.trace-score-grid span {
-  padding: 6px 8px;
-  border: 1px solid var(--border-subtle);
-  border-radius: var(--radius-sm);
-  color: var(--text-secondary);
-  font-size: 0.78rem;
-}
-
-.trace-warning {
-  padding: 6px 8px;
-  border: 1px solid color-mix(in srgb, var(--accent-warning) 55%, transparent);
-  border-radius: var(--radius-sm);
-  color: var(--accent-warning);
-  background: color-mix(in srgb, var(--accent-warning) 10%, transparent);
-}
-
-.trace-section {
-  margin-top: var(--spacing-sm);
-}
-
-.trace-section h4 {
-  margin: 0 0 6px;
-  font-size: 0.78rem;
-  color: var(--text-primary);
-}
-
-.trace-source-list,
-.trace-feedback-list {
-  display: grid;
-  gap: 6px;
-  margin: 0;
-  padding: 0;
-  list-style: none;
-}
-
-.trace-source-list li,
-.trace-feedback-list li {
-  display: grid;
-  gap: 2px;
-  padding: 7px 8px;
-  border: 1px solid var(--border-subtle);
-  border-radius: var(--radius-sm);
-  background: var(--bg-primary);
-}
-
-.trace-source-list li span,
-.trace-feedback-list li span {
-  color: var(--accent-cyan);
-  font-size: 0.72rem;
-  font-weight: 700;
-}
-
-.trace-source-list li small,
-.trace-feedback-list li small {
-  color: var(--text-secondary);
-}
-
-/* Outcome recording: labeled form, open until an outcome exists */
-.outcome-details {
-  margin-top: var(--spacing-sm);
-  padding-top: var(--spacing-sm);
-  border-top: 1px dashed var(--border-default);
-}
-
-.outcome-details summary {
-  font-size: 0.8rem;
-  color: var(--text-secondary);
-}
-
-.outcome-row {
-  display: grid;
-  grid-template-columns: repeat(2, minmax(0, 1fr));
-  gap: 10px;
-  align-items: end;
-  margin-top: var(--spacing-sm);
-}
-
-.outcome-field {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-}
-
-.outcome-field > span {
-  font-size: 0.68rem;
-  font-weight: 600;
-  letter-spacing: 0.06em;
-  text-transform: uppercase;
-  color: var(--text-muted);
-}
-
-.outcome-field input,
-.outcome-field select,
-.config-row select,
-.identity-field input,
-.setup-field textarea,
-.panel-header select {
-  border: 1px solid var(--border-default);
-  border-radius: var(--radius-sm);
-  background: var(--bg-primary);
-  color: var(--text-primary);
-}
-
-.outcome-field input,
-.outcome-field select {
-  min-height: 32px;
-  padding: 4px 8px;
-}
-
-.outcome-row .save-outcome {
-  grid-column: 1 / -1;
-  justify-self: start;
-}
-
-.correction-row {
-  margin-top: 10px;
-}
-
-.memory-grid {
-  display: grid;
-  grid-template-columns: repeat(2, minmax(0, 1fr));
-  align-items: start;
-}
-
-.setup-grid {
-  display: grid;
-  grid-template-columns: repeat(2, minmax(0, 1fr));
-}
-
-.guide-panel,
-.config-panel {
-  display: flex;
-  flex-direction: column;
-}
-
-.guide-walkthrough ol {
-  margin: var(--spacing-sm) 0 0;
-  padding-left: 1.2rem;
-}
-
-.guide-group dl {
-  display: grid;
-  grid-template-columns: minmax(120px, 180px) 1fr;
-  gap: 8px var(--spacing-md);
-  margin: var(--spacing-sm) 0 0;
-}
-
-.guide-group dt {
-  font-weight: 700;
-}
-
-.guide-group dd {
-  margin: 0;
-  color: var(--text-secondary);
-}
-
-.config-row,
-.config-toggle,
-.weight-row,
-.config-actions {
-  display: flex;
-  align-items: center;
-  gap: var(--spacing-sm);
-}
-
-.config-row,
-.weight-row {
-  justify-content: space-between;
-}
-
-.config-row select {
-  min-height: 32px;
-  padding: 4px 8px;
-}
-
-.config-toggle {
-  margin-top: var(--spacing-sm);
-}
-
-.config-actions {
-  margin-top: var(--spacing-sm);
-}
-
-.weight-row {
-  margin-top: var(--spacing-sm);
-}
-
-.weight-row span {
-  min-width: 160px;
-}
-
-.weight-row input {
-  flex: 1;
-}
-
-.weight-row strong {
-  min-width: 44px;
-  text-align: right;
-  font-family: 'Fira Code', monospace;
-  font-weight: 500;
-}
-
-.setup-field {
-  display: flex;
-  flex-direction: column;
-  gap: var(--spacing-xs);
-  padding: var(--spacing-md);
-  border: 1px solid var(--border-default);
-  border-radius: var(--radius-md);
-  background: var(--bg-secondary);
-}
-
-.identity-section,
-.setup-section-heading {
-  grid-column: 1 / -1;
-}
-
-.identity-section {
-  display: grid;
-  grid-template-columns: repeat(2, minmax(0, 1fr));
-  gap: var(--spacing-md);
-  padding: var(--spacing-md);
-  border: 1px solid var(--border-default);
-  border-left: 3px solid var(--accent-primary);
-  border-radius: var(--radius-md);
-  background: var(--bg-secondary);
-}
-
-.identity-section > div {
-  grid-column: 1 / -1;
-}
-
-.identity-section h2,
-.setup-section-heading h2 {
-  margin: 0;
-}
-
-.identity-section span,
-.setup-section-heading span {
-  color: var(--text-secondary);
-}
-
-.identity-field {
-  display: flex;
-  flex-direction: column;
-  gap: var(--spacing-xs);
-}
-
-.identity-field span {
-  font-weight: 600;
-  color: var(--text-primary);
-}
-
-.identity-field input {
-  min-height: 36px;
-  padding: 4px 8px;
-}
-
-.identity-section .setup-field {
-  grid-column: 1 / -1;
-  padding: 0;
-  border: none;
-  background: transparent;
-}
-
-.setup-field span {
-  font-weight: 600;
-}
-
-.setup-field textarea {
-  resize: vertical;
-  padding: var(--spacing-sm);
-}
-
-.setup-actions {
-  grid-column: 1 / -1;
-  display: flex;
-  align-items: flex-start;
-}
-
-.evidence-drawer {
-  position: fixed;
-  top: 72px;
-  right: var(--spacing-lg);
-  width: min(420px, calc(100vw - 32px));
-  max-height: calc(100vh - 104px);
-  overflow: auto;
-  padding: var(--spacing-md);
-  background: var(--bg-elevated, var(--bg-secondary));
-  box-shadow: var(--shadow-xl);
-  z-index: 40;
-}
-
-.evidence-item {
-  padding: var(--spacing-sm) 0;
-  border-top: 1px solid var(--border-subtle);
-}
-
-.save-toast {
-  position: fixed;
-  bottom: var(--spacing-lg);
-  right: var(--spacing-lg);
-  padding: var(--spacing-sm) var(--spacing-md);
-  border-radius: var(--radius-sm);
-  background: var(--bg-secondary);
-  border: 1px solid var(--border-default);
-  box-shadow: var(--shadow-lg);
-  z-index: 50;
-}
-
-.save-toast.success {
-  border-color: var(--accent-green);
-}
-
-.save-toast.error {
-  border-color: var(--accent-red);
-}
-
-@media (max-width: 980px) {
-  .workspace-header,
-  .overview-stats,
-  .identity-section,
-  .memory-grid,
-  .setup-grid,
-  .gap-columns,
-  .outcome-row {
-    grid-template-columns: 1fr;
-  }
-
-  .workspace-body {
-    flex-direction: column;
-  }
-
-  .workspace-rail {
-    flex: 0 0 auto;
-    flex-direction: row;
-    align-items: center;
-    overflow-x: auto;
-    overflow-y: hidden;
-    padding: var(--spacing-xs) var(--spacing-sm);
-    border-right: none;
-    border-bottom: 1px solid var(--border-default);
-  }
-
-  .rail-label {
-    display: none;
-  }
-
-  .tab-button {
-    width: auto;
-    flex: 0 0 auto;
-    border-left: none;
-    border-bottom: 3px solid transparent;
-    border-radius: var(--radius-sm) var(--radius-sm) 0 0;
-  }
-
-  .tab-button.active {
-    border-bottom-color: var(--accent-primary);
-  }
-
-  .header-title {
-    text-align: left;
-  }
-}
-</style>

From 471bb3c7b9c4ebcec1a059c1a9a0938a4573e06f Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 17:41:39 +0800
Subject: [PATCH 22/30] refactor: extract twin/TwinSetupTab and twin/SetupField
 components

Moves the Setup tab (twin identity + operating priors form) out of
TwinReviewView.vue verbatim, consuming the twin store directly.
---
 frontend/src/components/twin/SetupField.vue   | 24 ++++++
 frontend/src/components/twin/TwinSetupTab.vue | 72 ++++++++++++++++
 frontend/src/views/TwinReviewView.vue         | 86 +------------------
 3 files changed, 98 insertions(+), 84 deletions(-)
 create mode 100644 frontend/src/components/twin/SetupField.vue
 create mode 100644 frontend/src/components/twin/TwinSetupTab.vue

diff --git a/frontend/src/components/twin/SetupField.vue b/frontend/src/components/twin/SetupField.vue
new file mode 100644
index 0000000..07a3a92
--- /dev/null
+++ b/frontend/src/components/twin/SetupField.vue
@@ -0,0 +1,24 @@
+<script>
+// Extracted verbatim from TwinReviewView.vue (Task 4.3). Render-function
+// component — no template block needed since it's built with h().
+import { defineComponent, h } from 'vue'
+
+export default defineComponent({
+  name: 'SetupField',
+  props: {
+    modelValue: { type: String, default: '' },
+    title: { type: String, required: true }
+  },
+  emits: ['update:modelValue'],
+  setup(props, { emit }) {
+    return () => h('label', { class: 'setup-field' }, [
+      h('span', props.title),
+      h('textarea', {
+        value: props.modelValue,
+        rows: 5,
+        onInput: event => emit('update:modelValue', event.target.value)
+      })
+    ])
+  }
+})
+</script>
diff --git a/frontend/src/components/twin/TwinSetupTab.vue b/frontend/src/components/twin/TwinSetupTab.vue
new file mode 100644
index 0000000..4d63581
--- /dev/null
+++ b/frontend/src/components/twin/TwinSetupTab.vue
@@ -0,0 +1,72 @@
+<template>
+  <section class="tab-panel setup-grid">
+    <section class="identity-section">
+      <div>
+        <h2>Twin Identity</h2>
+        <span>Name and role are required before Twin Simulation can run.</span>
+      </div>
+      <label class="identity-field">
+        <span>Name</span>
+        <input
+          v-model="twinStore.setupDraft.twin_name"
+          aria-label="Twin name"
+          type="text"
+          placeholder="Who is this twin?"
+        >
+      </label>
+      <label class="identity-field">
+        <span>Role / context</span>
+        <input
+          v-model="twinStore.setupDraft.twin_role"
+          aria-label="Twin role"
+          type="text"
+          placeholder="What role should this twin reason from?"
+        >
+      </label>
+      <SetupField
+        v-model="twinStore.setupDraft.source_boundaries"
+        title="Source Boundaries"
+      />
+    </section>
+    <div class="setup-section-heading">
+      <h2>Operating Priors</h2>
+      <span>Values, taste, constraints, somatic cues, and action tendencies.</span>
+    </div>
+    <SetupField
+      v-model="twinStore.setupDraft.values"
+      title="Values"
+    />
+    <SetupField
+      v-model="twinStore.setupDraft.tastes"
+      title="Taste"
+    />
+    <SetupField
+      v-model="twinStore.setupDraft.constraints"
+      title="Constraints"
+    />
+    <SetupField
+      v-model="twinStore.setupDraft.somatic_cues"
+      title="Somatic Cues"
+    />
+    <SetupField
+      v-model="twinStore.setupDraft.action_tendencies"
+      title="Action Tendencies"
+    />
+    <div class="setup-actions">
+      <button
+        class="btn btn-primary"
+        :disabled="twinStore.savingSetup"
+        @click="twinStore.saveSetup"
+      >
+        {{ twinStore.savingSetup ? 'Saving...' : 'Save Setup' }}
+      </button>
+    </div>
+  </section>
+</template>
+
+<script setup>
+import { useTwinStore } from '@/stores/twin'
+import SetupField from './SetupField.vue'
+
+const twinStore = useTwinStore()
+</script>
diff --git a/frontend/src/views/TwinReviewView.vue b/frontend/src/views/TwinReviewView.vue
index 279d49f..1acffc1 100644
--- a/frontend/src/views/TwinReviewView.vue
+++ b/frontend/src/views/TwinReviewView.vue
@@ -396,72 +396,7 @@
           </section>
         </section>
 
-        <section
-          v-else-if="twinStore.activeTab === 'setup'"
-          class="tab-panel setup-grid"
-        >
-          <section class="identity-section">
-            <div>
-              <h2>Twin Identity</h2>
-              <span>Name and role are required before Twin Simulation can run.</span>
-            </div>
-            <label class="identity-field">
-              <span>Name</span>
-              <input
-                v-model="twinStore.setupDraft.twin_name"
-                aria-label="Twin name"
-                type="text"
-                placeholder="Who is this twin?"
-              >
-            </label>
-            <label class="identity-field">
-              <span>Role / context</span>
-              <input
-                v-model="twinStore.setupDraft.twin_role"
-                aria-label="Twin role"
-                type="text"
-                placeholder="What role should this twin reason from?"
-              >
-            </label>
-            <SetupField
-              v-model="twinStore.setupDraft.source_boundaries"
-              title="Source Boundaries"
-            />
-          </section>
-          <div class="setup-section-heading">
-            <h2>Operating Priors</h2>
-            <span>Values, taste, constraints, somatic cues, and action tendencies.</span>
-          </div>
-          <SetupField
-            v-model="twinStore.setupDraft.values"
-            title="Values"
-          />
-          <SetupField
-            v-model="twinStore.setupDraft.tastes"
-            title="Taste"
-          />
-          <SetupField
-            v-model="twinStore.setupDraft.constraints"
-            title="Constraints"
-          />
-          <SetupField
-            v-model="twinStore.setupDraft.somatic_cues"
-            title="Somatic Cues"
-          />
-          <SetupField
-            v-model="twinStore.setupDraft.action_tendencies"
-            title="Action Tendencies"
-          />
-          <div class="setup-actions">
-            <button
-              class="btn btn-primary"
-              :disabled="twinStore.savingSetup"
-              @click="twinStore.saveSetup"
-            >
-              {{ twinStore.savingSetup ? 'Saving...' : 'Save Setup' }}
-            </button>
-          </div>
-        </section>
+        <TwinSetupTab v-else-if="twinStore.activeTab === 'setup'" />
 
         <TwinGuideTab v-else-if="twinStore.activeTab === 'guide'" />
 
@@ -544,6 +479,7 @@ import {
   eventLabel
 } from '@/utils/twinFormat'
 import TwinGuideTab from '@/components/twin/TwinGuideTab.vue'
+import TwinSetupTab from '@/components/twin/TwinSetupTab.vue'
 import TwinConfigTab from '@/components/twin/TwinConfigTab.vue'
 import '@/components/twin/twin-workspace.css'
 
@@ -810,24 +746,6 @@ const DecisionRow = defineComponent({
   }
 })
 
-const SetupField = defineComponent({
-  props: {
-    modelValue: { type: String, default: '' },
-    title: { type: String, required: true }
-  },
-  emits: ['update:modelValue'],
-  setup(props, { emit }) {
-    return () => h('label', { class: 'setup-field' }, [
-      h('span', props.title),
-      h('textarea', {
-        value: props.modelValue,
-        rows: 5,
-        onInput: event => emit('update:modelValue', event.target.value)
-      })
-    ])
-  }
-})
-
 const primitiveFields = [
   { key: 'stakes', label: 'Stakes' },
   { key: 'reversibility', label: 'Reversibility' },

From b69ad25b0dd9435b04e4d9d7b5022d384194e299 Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 17:47:49 +0800
Subject: [PATCH 23/30] refactor: extract twin/TwinConstitutionTab and shared
 twin/ReviewActions

Moves the Constitution tab out of TwinReviewView.vue verbatim, and promotes
the ReviewActions render-function component to its own file since the
Constitution, Action Gaps, and Memory Review tabs all use it.
---
 .../src/components/twin/ReviewActions.vue     | 18 ++++
 .../components/twin/TwinConstitutionTab.vue   | 78 ++++++++++++++++++
 frontend/src/views/TwinReviewView.vue         | 82 +------------------
 3 files changed, 99 insertions(+), 79 deletions(-)
 create mode 100644 frontend/src/components/twin/ReviewActions.vue
 create mode 100644 frontend/src/components/twin/TwinConstitutionTab.vue

diff --git a/frontend/src/components/twin/ReviewActions.vue b/frontend/src/components/twin/ReviewActions.vue
new file mode 100644
index 0000000..7465262
--- /dev/null
+++ b/frontend/src/components/twin/ReviewActions.vue
@@ -0,0 +1,18 @@
+<script>
+// Extracted verbatim from TwinReviewView.vue (Task 4.3). Shared by the
+// Constitution, Action Gaps, and Memory Review tabs. Render-function
+// component — no template block needed since it's built with h().
+import { defineComponent, h } from 'vue'
+import { actionLabel } from '@/utils/twinFormat'
+
+export default defineComponent({
+  name: 'ReviewActions',
+  emits: ['review'],
+  setup(_, { emit }) {
+    const actions = ['keep', 'soften', 'not_me', 'private', 'no_train', 'reject']
+    return () => h('div', { class: 'review-actions' }, actions.map(action =>
+      h('button', { onClick: () => emit('review', action) }, actionLabel(action))
+    ))
+  }
+})
+</script>
diff --git a/frontend/src/components/twin/TwinConstitutionTab.vue b/frontend/src/components/twin/TwinConstitutionTab.vue
new file mode 100644
index 0000000..28a88c9
--- /dev/null
+++ b/frontend/src/components/twin/TwinConstitutionTab.vue
@@ -0,0 +1,78 @@
+<template>
+  <section class="tab-panel">
+    <div class="panel-header">
+      <div>
+        <h2>Constitution</h2>
+        <span>The value rules the twin reasons from — {{ twinStore.groupedConstitution.length }} dimensions</span>
+      </div>
+      <button
+        class="btn btn-secondary btn-sm"
+        @click="twinStore.activeTab = 'setup'"
+      >
+        Setup
+      </button>
+    </div>
+
+    <div
+      v-if="twinStore.constitutionItems.length === 0"
+      class="empty-panel"
+    >
+      No constitution items yet. Run Constitution to infer them from records and decisions.
+    </div>
+    <section
+      v-for="group in twinStore.groupedConstitution"
+      :key="group.dimension"
+      class="dimension-section"
+    >
+      <h3>{{ dimensionLabel(group.dimension) }}</h3>
+      <article
+        v-for="item in group.items"
+        :key="item.id"
+        class="constitution-card"
+      >
+        <div class="card-topline">
+          <span class="status-pill">{{ statusLabel(item.status) }}</span>
+          <span>{{ formatPercent(item.confidence) }} confidence</span>
+          <span>{{ item.evidence_refs?.length || 0 }} evidence</span>
+          <span>{{ constitutionSourceLabel(item) }}</span>
+        </div>
+        <p>{{ item.claim }}</p>
+        <div
+          v-if="constitutionEvidenceLabels(item).length"
+          class="source-row"
+        >
+          <span
+            v-for="label in constitutionEvidenceLabels(item)"
+            :key="`${item.id}-${label}`"
+          >{{ label }}</span>
+        </div>
+        <div
+          v-if="item.scope?.length"
+          class="tag-row"
+        >
+          <span
+            v-for="scope in item.scope"
+            :key="scope"
+          >{{ scope }}</span>
+        </div>
+        <ReviewActions
+          @review="action => twinStore.reviewConstitutionItem(item.id, action)"
+        />
+      </article>
+    </section>
+  </section>
+</template>
+
+<script setup>
+import { useTwinStore } from '@/stores/twin'
+import {
+  dimensionLabel,
+  statusLabel,
+  formatPercent,
+  constitutionSourceLabel,
+  constitutionEvidenceLabels
+} from '@/utils/twinFormat'
+import ReviewActions from './ReviewActions.vue'
+
+const twinStore = useTwinStore()
+</script>
diff --git a/frontend/src/views/TwinReviewView.vue b/frontend/src/views/TwinReviewView.vue
index 1acffc1..84ad9d2 100644
--- a/frontend/src/views/TwinReviewView.vue
+++ b/frontend/src/views/TwinReviewView.vue
@@ -191,71 +191,7 @@
           </section>
         </section>
 
-        <section
-          v-else-if="twinStore.activeTab === 'constitution'"
-          class="tab-panel"
-        >
-          <div class="panel-header">
-            <div>
-              <h2>Constitution</h2>
-              <span>The value rules the twin reasons from — {{ twinStore.groupedConstitution.length }} dimensions</span>
-            </div>
-            <button
-              class="btn btn-secondary btn-sm"
-              @click="twinStore.activeTab = 'setup'"
-            >
-              Setup
-            </button>
-          </div>
-
-          <div
-            v-if="twinStore.constitutionItems.length === 0"
-            class="empty-panel"
-          >
-            No constitution items yet. Run Constitution to infer them from records and decisions.
-          </div>
-          <section
-            v-for="group in twinStore.groupedConstitution"
-            :key="group.dimension"
-            class="dimension-section"
-          >
-            <h3>{{ dimensionLabel(group.dimension) }}</h3>
-            <article
-              v-for="item in group.items"
-              :key="item.id"
-              class="constitution-card"
-            >
-              <div class="card-topline">
-                <span class="status-pill">{{ statusLabel(item.status) }}</span>
-                <span>{{ formatPercent(item.confidence) }} confidence</span>
-                <span>{{ item.evidence_refs?.length || 0 }} evidence</span>
-                <span>{{ constitutionSourceLabel(item) }}</span>
-              </div>
-              <p>{{ item.claim }}</p>
-              <div
-                v-if="constitutionEvidenceLabels(item).length"
-                class="source-row"
-              >
-                <span
-                  v-for="label in constitutionEvidenceLabels(item)"
-                  :key="`${item.id}-${label}`"
-                >{{ label }}</span>
-              </div>
-              <div
-                v-if="item.scope?.length"
-                class="tag-row"
-              >
-                <span
-                  v-for="scope in item.scope"
-                  :key="scope"
-                >{{ scope }}</span>
-              </div>
-              <ReviewActions
-                @review="action => twinStore.reviewConstitutionItem(item.id, action)"
-              />
-            </article>
-          </section>
-        </section>
+        <TwinConstitutionTab v-else-if="twinStore.activeTab === 'constitution'" />
 
         <section
           v-else-if="twinStore.activeTab === 'action_gaps'"
@@ -462,22 +398,20 @@ import { useTwinStore } from '@/stores/twin'
 import {
   decisionState,
   decisionChips,
-  actionLabel,
   statusLabel,
   kindLabel,
-  dimensionLabel,
   formatPercent,
   formatWeight,
   presetLabel,
   sourceTypeLabel,
-  constitutionSourceLabel,
-  constitutionEvidenceLabels,
   scoreRows,
   feedbackEventLabel,
   feedbackEventNote,
   formatDate,
   eventLabel
 } from '@/utils/twinFormat'
+import ReviewActions from '@/components/twin/ReviewActions.vue'
+import TwinConstitutionTab from '@/components/twin/TwinConstitutionTab.vue'
 import TwinGuideTab from '@/components/twin/TwinGuideTab.vue'
 import TwinSetupTab from '@/components/twin/TwinSetupTab.vue'
 import TwinConfigTab from '@/components/twin/TwinConfigTab.vue'
@@ -520,16 +454,6 @@ const navGroups = computed(() => [
   }
 ])
 
-const ReviewActions = defineComponent({
-  emits: ['review'],
-  setup(_, { emit }) {
-    const actions = ['keep', 'soften', 'not_me', 'private', 'no_train', 'reject']
-    return () => h('div', { class: 'review-actions' }, actions.map(action =>
-      h('button', { onClick: () => emit('review', action) }, actionLabel(action))
-    ))
-  }
-})
-
 const ActionGapRow = defineComponent({
   props: {
     gap: { type: Object, required: true }

From ea217b71ee10341eb23ccb1e2ab5f9577e8b74cc Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 17:50:27 +0800
Subject: [PATCH 24/30] refactor: extract twin/TwinActionGapsTab and
 twin/ActionGapRow components

Moves the Action Gaps tab and its per-gap render-function row out of
TwinReviewView.vue verbatim.
---
 frontend/src/components/twin/ActionGapRow.vue | 31 ++++++++++++
 .../src/components/twin/TwinActionGapsTab.vue | 29 +++++++++++
 frontend/src/views/TwinReviewView.vue         | 48 +------------------
 3 files changed, 62 insertions(+), 46 deletions(-)
 create mode 100644 frontend/src/components/twin/ActionGapRow.vue
 create mode 100644 frontend/src/components/twin/TwinActionGapsTab.vue

diff --git a/frontend/src/components/twin/ActionGapRow.vue b/frontend/src/components/twin/ActionGapRow.vue
new file mode 100644
index 0000000..c737fae
--- /dev/null
+++ b/frontend/src/components/twin/ActionGapRow.vue
@@ -0,0 +1,31 @@
+<script>
+// Extracted verbatim from TwinReviewView.vue (Task 4.3). Render-function
+// component — no template block needed since it's built with h().
+import { defineComponent, h } from 'vue'
+import { statusLabel, formatPercent } from '@/utils/twinFormat'
+import ReviewActions from './ReviewActions.vue'
+
+export default defineComponent({
+  name: 'ActionGapRow',
+  props: {
+    gap: { type: Object, required: true }
+  },
+  emits: ['review'],
+  setup(props, { emit }) {
+    return () => h('article', { class: 'action-gap-card' }, [
+      h('div', { class: 'card-topline' }, [
+        h('span', { class: 'status-pill' }, statusLabel(props.gap.status)),
+        h('span', formatPercent(props.gap.confidence)),
+        h('span', `${props.gap.evidence_refs?.length || 0} evidence`)
+      ]),
+      h('div', { class: 'gap-columns' }, [
+        h('div', [h('small', 'Stated'), h('p', props.gap.stated_value)]),
+        h('div', [h('small', 'Revealed'), h('p', props.gap.revealed_behavior)])
+      ]),
+      props.gap.driver_hypothesis ? h('p', { class: 'muted' }, props.gap.driver_hypothesis) : null,
+      h('p', props.gap.decision_risk),
+      h(ReviewActions, { onReview: action => emit('review', props.gap.id, action) })
+    ])
+  }
+})
+</script>
diff --git a/frontend/src/components/twin/TwinActionGapsTab.vue b/frontend/src/components/twin/TwinActionGapsTab.vue
new file mode 100644
index 0000000..616ab50
--- /dev/null
+++ b/frontend/src/components/twin/TwinActionGapsTab.vue
@@ -0,0 +1,29 @@
+<template>
+  <section class="tab-panel">
+    <div class="panel-header">
+      <div>
+        <h2>Action Gaps</h2>
+        <span>{{ twinStore.actionGaps.length }} stated versus revealed patterns</span>
+      </div>
+    </div>
+    <div
+      v-if="twinStore.actionGaps.length === 0"
+      class="empty-panel"
+    >
+      No action gaps yet.
+    </div>
+    <ActionGapRow
+      v-for="gap in twinStore.actionGaps"
+      :key="gap.id"
+      :gap="gap"
+      @review="twinStore.reviewActionGap"
+    />
+  </section>
+</template>
+
+<script setup>
+import { useTwinStore } from '@/stores/twin'
+import ActionGapRow from './ActionGapRow.vue'
+
+const twinStore = useTwinStore()
+</script>
diff --git a/frontend/src/views/TwinReviewView.vue b/frontend/src/views/TwinReviewView.vue
index 84ad9d2..d0e3486 100644
--- a/frontend/src/views/TwinReviewView.vue
+++ b/frontend/src/views/TwinReviewView.vue
@@ -193,29 +193,7 @@
 
         <TwinConstitutionTab v-else-if="twinStore.activeTab === 'constitution'" />
 
-        <section
-          v-else-if="twinStore.activeTab === 'action_gaps'"
-          class="tab-panel"
-        >
-          <div class="panel-header">
-            <div>
-              <h2>Action Gaps</h2>
-              <span>{{ twinStore.actionGaps.length }} stated versus revealed patterns</span>
-            </div>
-          </div>
-          <div
-            v-if="twinStore.actionGaps.length === 0"
-            class="empty-panel"
-          >
-            No action gaps yet.
-          </div>
-          <ActionGapRow
-            v-for="gap in twinStore.actionGaps"
-            :key="gap.id"
-            :gap="gap"
-            @review="twinStore.reviewActionGap"
-          />
-        </section>
+        <TwinActionGapsTab v-else-if="twinStore.activeTab === 'action_gaps'" />
 
         <section
           v-else-if="twinStore.activeTab === 'decisions'"
@@ -411,6 +389,7 @@ import {
   eventLabel
 } from '@/utils/twinFormat'
 import ReviewActions from '@/components/twin/ReviewActions.vue'
+import TwinActionGapsTab from '@/components/twin/TwinActionGapsTab.vue'
 import TwinConstitutionTab from '@/components/twin/TwinConstitutionTab.vue'
 import TwinGuideTab from '@/components/twin/TwinGuideTab.vue'
 import TwinSetupTab from '@/components/twin/TwinSetupTab.vue'
@@ -454,29 +433,6 @@ const navGroups = computed(() => [
   }
 ])
 
-const ActionGapRow = defineComponent({
-  props: {
-    gap: { type: Object, required: true }
-  },
-  emits: ['review'],
-  setup(props, { emit }) {
-    return () => h('article', { class: 'action-gap-card' }, [
-      h('div', { class: 'card-topline' }, [
-        h('span', { class: 'status-pill' }, statusLabel(props.gap.status)),
-        h('span', formatPercent(props.gap.confidence)),
-        h('span', `${props.gap.evidence_refs?.length || 0} evidence`)
-      ]),
-      h('div', { class: 'gap-columns' }, [
-        h('div', [h('small', 'Stated'), h('p', props.gap.stated_value)]),
-        h('div', [h('small', 'Revealed'), h('p', props.gap.revealed_behavior)])
-      ]),
-      props.gap.driver_hypothesis ? h('p', { class: 'muted' }, props.gap.driver_hypothesis) : null,
-      h('p', props.gap.decision_risk),
-      h(ReviewActions, { onReview: action => emit('review', props.gap.id, action) })
-    ])
-  }
-})
-
 const DecisionRow = defineComponent({
   props: {
     item: { type: Object, required: true },

From 5fb84338b063b79a61bb8b2d61eabdc6310c58df Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 17:56:11 +0800
Subject: [PATCH 25/30] refactor: extract twin/TwinDecisionsTab and
 twin/DecisionRow components

Moves the Decisions tab and the decision-card render-function component
(context trace, sealed predictions, outcome recording) out of
TwinReviewView.vue verbatim. Route-derived highlight/trace-open state is
computed inside the tab from the same route query.
---
 frontend/src/components/twin/DecisionRow.vue  | 222 ++++++++++++++++
 .../src/components/twin/TwinDecisionsTab.vue  |  36 +++
 frontend/src/views/TwinReviewView.vue         | 242 +-----------------
 3 files changed, 261 insertions(+), 239 deletions(-)
 create mode 100644 frontend/src/components/twin/DecisionRow.vue
 create mode 100644 frontend/src/components/twin/TwinDecisionsTab.vue

diff --git a/frontend/src/components/twin/DecisionRow.vue b/frontend/src/components/twin/DecisionRow.vue
new file mode 100644
index 0000000..277f834
--- /dev/null
+++ b/frontend/src/components/twin/DecisionRow.vue
@@ -0,0 +1,222 @@
+<script>
+// Extracted verbatim from TwinReviewView.vue (Task 4.3). Render-function
+// component — no template block needed since it's built with h().
+import { defineComponent, h, ref } from 'vue'
+import {
+  decisionState,
+  decisionChips,
+  presetLabel,
+  sourceTypeLabel,
+  formatWeight,
+  scoreRows,
+  feedbackEventLabel,
+  feedbackEventNote
+} from '@/utils/twinFormat'
+
+const primitiveFields = [
+  { key: 'stakes', label: 'Stakes' },
+  { key: 'reversibility', label: 'Reversibility' },
+  { key: 'time_horizon', label: 'Time' },
+  { key: 'uncertainty', label: 'Uncertainty' },
+  { key: 'agency', label: 'Agency' },
+  { key: 'value_tension', label: 'Value Tension' },
+  { key: 'constraint_pressure', label: 'Constraint' },
+  { key: 'taste_aesthetic_pull', label: 'Taste' },
+  { key: 'somatic_signal', label: 'Somatic' },
+  { key: 'action_gap_risk', label: 'Gap Risk' }
+]
+
+export default defineComponent({
+  name: 'DecisionRow',
+  props: {
+    item: { type: Object, required: true },
+    highlighted: { type: Boolean, default: false },
+    traceOpen: { type: Boolean, default: false }
+  },
+  emits: ['update-outcome'],
+  setup(props, { emit }) {
+    const episodeOptions = props.item.episode.options || []
+    const savedChoice = props.item.episode.chosen_option || ''
+    const choiceInList = savedChoice && episodeOptions.includes(savedChoice)
+    const outcome = ref(props.item.episode.outcome || '')
+    const lesson = ref(props.item.episode.lesson || '')
+    const regretScore = ref(props.item.episode.regret_score ?? '')
+    const chosenSelect = ref(choiceInList ? savedChoice : (savedChoice ? '__other__' : ''))
+    const chosenOther = ref(choiceInList ? '' : savedChoice)
+    const correctionNote = ref(props.item.episode.correction_note || '')
+    const resolvedChoice = () =>
+      chosenSelect.value === '__other__' ? chosenOther.value.trim() : chosenSelect.value
+    const save = () => emit('update-outcome', props.item.episode.id, {
+      outcome: outcome.value || null,
+      lesson: lesson.value || null,
+      regret_score: regretScore.value === '' ? null : Number(regretScore.value),
+      chosen_option: resolvedChoice() || null,
+      correction_note: correctionNote.value.trim() || null
+    })
+    return () => {
+      const episode = props.item.episode
+      const latestCard = props.item.reflection_cards?.[0]
+      const trace = latestCard?.evidence_packet || {}
+      const selectedSources = trace.selected_sources || []
+      const excludedTotal = (trace.excluded_private_count || 0)
+        + (trace.excluded_rejected_count || 0)
+        + (trace.excluded_no_train_count || 0)
+      const scores = latestCard?.scores || {}
+      const feedbackEvents = props.item.feedback_events || []
+      const outcomeField = (label, node) =>
+        h('label', { class: 'outcome-field' }, [h('span', label), node])
+
+      return h('article', {
+        class: [
+          'decision-card',
+          decisionState(props.item),
+          props.highlighted ? 'highlighted' : ''
+        ]
+      }, [
+        h('div', { class: 'card-topline' }, [
+          h('span', episode.review_date || 'No follow-up'),
+          h('span', `${props.item.reflection_cards?.length || 0} cards`),
+          episode.confidence != null ? h('span', `${Math.round(episode.confidence * 100)}% confidence`) : null,
+          h('span', { class: 'topline-chips' }, decisionChips(props.item).map(chip =>
+            h('span', { key: chip.id, class: ['chip', chip.cls] }, chip.label)
+          ))
+        ]),
+        h('h3', episode.decision),
+        episode.options?.length
+          ? h('div', { class: 'tag-row' }, episode.options.map(option => h('span', option)))
+          : null,
+        h('div', { class: 'primitive-grid' }, primitiveFields.map(field =>
+          episode.primitive_assessment?.[field.key]
+            ? h('span', [h('strong', field.label), ` ${episode.primitive_assessment[field.key]}`])
+            : null
+        )),
+        props.item.reflection_cards?.[0]
+          ? h('details', { class: 'reflection-details' }, [
+              h('summary', 'Latest Reflection Card'),
+              h('pre', props.item.reflection_cards[0].content)
+            ])
+          : null,
+        latestCard
+          ? h('details', { class: 'context-trace-details', open: props.traceOpen }, [
+              h('summary', 'Context Trace'),
+              h('div', { class: 'trace-metrics' }, [
+                h('span', [h('strong', 'Preset'), ` ${presetLabel(trace.config_snapshot?.preset)}`]),
+                h('span', [h('strong', 'Sources'), ` ${selectedSources.length}`]),
+                h('span', [h('strong', 'Excluded'), ` ${excludedTotal}`]),
+                h('span', [h('strong', 'Unsupported'), ` ${scores.unsupported_claim_count || 0}`])
+              ]),
+              scores.evidence_grounding_score < 0.5
+                ? h('p', { class: 'trace-warning' }, 'Weak evidence signal: treat self-model claims as tentative.')
+                : null,
+              h('section', { class: 'trace-section' }, [
+                h('h4', 'Selected Context'),
+                selectedSources.length
+                  ? h('ul', { class: 'trace-source-list' }, selectedSources.map(source =>
+                      h('li', { key: `${source.source_type}-${source.id}` }, [
+                        h('span', sourceTypeLabel(source.source_type)),
+                        h('strong', source.label || source.id),
+                        h('small', `${source.reason || 'Selected for this decision'} · ${formatWeight(source.weight)}`)
+                      ])
+                    ))
+                  : h('p', { class: 'muted' }, 'No selected context recorded for this card.')
+              ]),
+              h('section', { class: 'trace-section' }, [
+                h('h4', 'Score Breakdown'),
+                h('div', { class: 'trace-score-grid' }, scoreRows(scores).map(row =>
+                  h('span', { key: row.label }, [h('strong', row.label), ` ${row.value}`])
+                ))
+              ]),
+              h('section', { class: 'trace-section' }, [
+                h('h4', 'Feedback Afterward'),
+                feedbackEvents.length
+                  ? h('ul', { class: 'trace-feedback-list' }, feedbackEvents.map(event =>
+                      h('li', { key: event.id }, [
+                        h('span', feedbackEventLabel(event)),
+                        h('small', feedbackEventNote(event))
+                      ])
+                    ))
+                  : h('p', { class: 'muted' }, 'No correction or one-click feedback recorded yet.')
+              ])
+            ])
+          : null,
+        props.item.prediction_sealed
+          ? h('div', { class: 'prediction-sealed-badge' },
+              'Twin sealed a prediction — record your choice to reveal it')
+          : null,
+        episode.twin_prediction
+          ? h('div', { class: 'prediction-reveal' }, [
+              h('div', { class: 'prediction-headline' }, [
+                h('strong', 'Twin predicted: '),
+                h('span', episode.twin_prediction.predicted_option),
+                episode.twin_prediction.confidence != null
+                  ? h('span', { class: 'prediction-confidence' },
+                      ` (${Math.round(episode.twin_prediction.confidence * 100)}% confident)`)
+                  : null,
+                episode.agreement === true
+                  ? h('span', { class: 'agreement-badge match' }, 'Matched my choice')
+                  : null,
+                episode.agreement === false
+                  ? h('span', { class: 'agreement-badge miss' }, 'Missed')
+                  : null
+              ]),
+              episode.twin_prediction.rationale
+                ? h('p', { class: 'prediction-rationale' }, episode.twin_prediction.rationale)
+                : null
+            ])
+          : null,
+        h('details', { class: 'outcome-details', open: !episode.outcome }, [
+          h('summary', episode.outcome ? 'Outcome recorded — edit' : 'Record outcome'),
+          h('div', { class: 'outcome-row' }, [
+            episodeOptions.length
+              ? outcomeField('Chosen option', h('select', {
+                  class: 'chosen-option-select',
+                  value: chosenSelect.value,
+                  onChange: event => { chosenSelect.value = event.target.value }
+                }, [
+                  h('option', { value: '' }, 'Chosen option…'),
+                  ...episodeOptions.map(option => h('option', { value: option }, option)),
+                  h('option', { value: '__other__' }, 'Other…')
+                ]))
+              : null,
+            (!episodeOptions.length || chosenSelect.value === '__other__')
+              ? outcomeField(episodeOptions.length ? 'Other choice' : 'Chosen option', h('input', {
+                  value: chosenOther.value,
+                  placeholder: 'Chosen option',
+                  onInput: event => { chosenOther.value = event.target.value }
+                }))
+              : null,
+            outcomeField('Outcome', h('input', {
+              value: outcome.value,
+              placeholder: 'What actually happened',
+              onInput: event => { outcome.value = event.target.value }
+            })),
+            outcomeField('Lesson', h('input', {
+              value: lesson.value,
+              placeholder: 'What it taught you',
+              onInput: event => { lesson.value = event.target.value }
+            })),
+            outcomeField('Regret (0-10)', h('input', {
+              value: regretScore.value,
+              type: 'number',
+              min: '0',
+              max: '10',
+              placeholder: '0',
+              onInput: event => { regretScore.value = event.target.value }
+            })),
+            h('button', { class: 'btn btn-primary btn-sm save-outcome', onClick: save }, 'Save Outcome')
+          ]),
+          episode.agreement === false
+            ? h('div', { class: 'correction-row' }, [
+                outcomeField('Why was the twin wrong?', h('input', {
+                  value: correctionNote.value,
+                  placeholder: 'Why was the twin wrong?',
+                  onInput: event => { correctionNote.value = event.target.value }
+                }))
+              ])
+            : null
+        ])
+      ])
+    }
+  }
+})
+</script>
diff --git a/frontend/src/components/twin/TwinDecisionsTab.vue b/frontend/src/components/twin/TwinDecisionsTab.vue
new file mode 100644
index 0000000..3e98d1a
--- /dev/null
+++ b/frontend/src/components/twin/TwinDecisionsTab.vue
@@ -0,0 +1,36 @@
+<template>
+  <section class="tab-panel">
+    <div class="panel-header">
+      <div>
+        <h2>Decisions</h2>
+        <span>{{ twinStore.decisions.length }} episodes — record what you actually chose to reveal each sealed twin prediction</span>
+      </div>
+    </div>
+    <div
+      v-if="twinStore.decisions.length === 0"
+      class="empty-panel"
+    >
+      No decision episodes yet. Start a Decision in Canvas and it will appear here.
+    </div>
+    <DecisionRow
+      v-for="item in twinStore.decisions"
+      :key="item.episode.id"
+      :item="item"
+      :highlighted="item.episode.id === routeDecisionId"
+      :trace-open="item.episode.id === routeDecisionId && routeTraceRequested"
+      @update-outcome="twinStore.updateDecisionOutcome"
+    />
+  </section>
+</template>
+
+<script setup>
+import { computed } from 'vue'
+import { useRoute } from 'vue-router'
+import { useTwinStore } from '@/stores/twin'
+import DecisionRow from './DecisionRow.vue'
+
+const twinStore = useTwinStore()
+const route = useRoute() || { query: {} }
+const routeDecisionId = computed(() => String(route.query?.decision || ''))
+const routeTraceRequested = computed(() => route.query?.trace === '1')
+</script>
diff --git a/frontend/src/views/TwinReviewView.vue b/frontend/src/views/TwinReviewView.vue
index d0e3486..7fe3ff2 100644
--- a/frontend/src/views/TwinReviewView.vue
+++ b/frontend/src/views/TwinReviewView.vue
@@ -195,31 +195,7 @@
 
         <TwinActionGapsTab v-else-if="twinStore.activeTab === 'action_gaps'" />
 
-        <section
-          v-else-if="twinStore.activeTab === 'decisions'"
-          class="tab-panel"
-        >
-          <div class="panel-header">
-            <div>
-              <h2>Decisions</h2>
-              <span>{{ twinStore.decisions.length }} episodes — record what you actually chose to reveal each sealed twin prediction</span>
-            </div>
-          </div>
-          <div
-            v-if="twinStore.decisions.length === 0"
-            class="empty-panel"
-          >
-            No decision episodes yet. Start a Decision in Canvas and it will appear here.
-          </div>
-          <DecisionRow
-            v-for="item in twinStore.decisions"
-            :key="item.episode.id"
-            :item="item"
-            :highlighted="item.episode.id === routeDecisionId"
-            :trace-open="item.episode.id === routeDecisionId && routeTraceRequested"
-            @update-outcome="twinStore.updateDecisionOutcome"
-          />
-        </section>
+        <TwinDecisionsTab v-else-if="twinStore.activeTab === 'decisions'" />
 
         <section
           v-else-if="twinStore.activeTab === 'memory'"
@@ -370,7 +346,7 @@
 </template>
 
 <script setup>
-import { computed, defineComponent, h, onMounted, ref } from 'vue'
+import { computed, onMounted } from 'vue'
 import { useRoute } from 'vue-router'
 import { useTwinStore } from '@/stores/twin'
 import {
@@ -379,18 +355,13 @@ import {
   statusLabel,
   kindLabel,
   formatPercent,
-  formatWeight,
-  presetLabel,
-  sourceTypeLabel,
-  scoreRows,
-  feedbackEventLabel,
-  feedbackEventNote,
   formatDate,
   eventLabel
 } from '@/utils/twinFormat'
 import ReviewActions from '@/components/twin/ReviewActions.vue'
 import TwinActionGapsTab from '@/components/twin/TwinActionGapsTab.vue'
 import TwinConstitutionTab from '@/components/twin/TwinConstitutionTab.vue'
+import TwinDecisionsTab from '@/components/twin/TwinDecisionsTab.vue'
 import TwinGuideTab from '@/components/twin/TwinGuideTab.vue'
 import TwinSetupTab from '@/components/twin/TwinSetupTab.vue'
 import TwinConfigTab from '@/components/twin/TwinConfigTab.vue'
@@ -433,212 +404,6 @@ const navGroups = computed(() => [
   }
 ])
 
-const DecisionRow = defineComponent({
-  props: {
-    item: { type: Object, required: true },
-    highlighted: { type: Boolean, default: false },
-    traceOpen: { type: Boolean, default: false }
-  },
-  emits: ['update-outcome'],
-  setup(props, { emit }) {
-    const episodeOptions = props.item.episode.options || []
-    const savedChoice = props.item.episode.chosen_option || ''
-    const choiceInList = savedChoice && episodeOptions.includes(savedChoice)
-    const outcome = ref(props.item.episode.outcome || '')
-    const lesson = ref(props.item.episode.lesson || '')
-    const regretScore = ref(props.item.episode.regret_score ?? '')
-    const chosenSelect = ref(choiceInList ? savedChoice : (savedChoice ? '__other__' : ''))
-    const chosenOther = ref(choiceInList ? '' : savedChoice)
-    const correctionNote = ref(props.item.episode.correction_note || '')
-    const resolvedChoice = () =>
-      chosenSelect.value === '__other__' ? chosenOther.value.trim() : chosenSelect.value
-    const save = () => emit('update-outcome', props.item.episode.id, {
-      outcome: outcome.value || null,
-      lesson: lesson.value || null,
-      regret_score: regretScore.value === '' ? null : Number(regretScore.value),
-      chosen_option: resolvedChoice() || null,
-      correction_note: correctionNote.value.trim() || null
-    })
-    return () => {
-      const episode = props.item.episode
-      const latestCard = props.item.reflection_cards?.[0]
-      const trace = latestCard?.evidence_packet || {}
-      const selectedSources = trace.selected_sources || []
-      const excludedTotal = (trace.excluded_private_count || 0)
-        + (trace.excluded_rejected_count || 0)
-        + (trace.excluded_no_train_count || 0)
-      const scores = latestCard?.scores || {}
-      const feedbackEvents = props.item.feedback_events || []
-      const outcomeField = (label, node) =>
-        h('label', { class: 'outcome-field' }, [h('span', label), node])
-
-      return h('article', {
-        class: [
-          'decision-card',
-          decisionState(props.item),
-          props.highlighted ? 'highlighted' : ''
-        ]
-      }, [
-        h('div', { class: 'card-topline' }, [
-          h('span', episode.review_date || 'No follow-up'),
-          h('span', `${props.item.reflection_cards?.length || 0} cards`),
-          episode.confidence != null ? h('span', `${Math.round(episode.confidence * 100)}% confidence`) : null,
-          h('span', { class: 'topline-chips' }, decisionChips(props.item).map(chip =>
-            h('span', { key: chip.id, class: ['chip', chip.cls] }, chip.label)
-          ))
-        ]),
-        h('h3', episode.decision),
-        episode.options?.length
-          ? h('div', { class: 'tag-row' }, episode.options.map(option => h('span', option)))
-          : null,
-        h('div', { class: 'primitive-grid' }, primitiveFields.map(field =>
-          episode.primitive_assessment?.[field.key]
-            ? h('span', [h('strong', field.label), ` ${episode.primitive_assessment[field.key]}`])
-            : null
-        )),
-        props.item.reflection_cards?.[0]
-          ? h('details', { class: 'reflection-details' }, [
-              h('summary', 'Latest Reflection Card'),
-              h('pre', props.item.reflection_cards[0].content)
-            ])
-          : null,
-        latestCard
-          ? h('details', { class: 'context-trace-details', open: props.traceOpen }, [
-              h('summary', 'Context Trace'),
-              h('div', { class: 'trace-metrics' }, [
-                h('span', [h('strong', 'Preset'), ` ${presetLabel(trace.config_snapshot?.preset)}`]),
-                h('span', [h('strong', 'Sources'), ` ${selectedSources.length}`]),
-                h('span', [h('strong', 'Excluded'), ` ${excludedTotal}`]),
-                h('span', [h('strong', 'Unsupported'), ` ${scores.unsupported_claim_count || 0}`])
-              ]),
-              scores.evidence_grounding_score < 0.5
-                ? h('p', { class: 'trace-warning' }, 'Weak evidence signal: treat self-model claims as tentative.')
-                : null,
-              h('section', { class: 'trace-section' }, [
-                h('h4', 'Selected Context'),
-                selectedSources.length
-                  ? h('ul', { class: 'trace-source-list' }, selectedSources.map(source =>
-                      h('li', { key: `${source.source_type}-${source.id}` }, [
-                        h('span', sourceTypeLabel(source.source_type)),
-                        h('strong', source.label || source.id),
-                        h('small', `${source.reason || 'Selected for this decision'} · ${formatWeight(source.weight)}`)
-                      ])
-                    ))
-                  : h('p', { class: 'muted' }, 'No selected context recorded for this card.')
-              ]),
-              h('section', { class: 'trace-section' }, [
-                h('h4', 'Score Breakdown'),
-                h('div', { class: 'trace-score-grid' }, scoreRows(scores).map(row =>
-                  h('span', { key: row.label }, [h('strong', row.label), ` ${row.value}`])
-                ))
-              ]),
-              h('section', { class: 'trace-section' }, [
-                h('h4', 'Feedback Afterward'),
-                feedbackEvents.length
-                  ? h('ul', { class: 'trace-feedback-list' }, feedbackEvents.map(event =>
-                      h('li', { key: event.id }, [
-                        h('span', feedbackEventLabel(event)),
-                        h('small', feedbackEventNote(event))
-                      ])
-                    ))
-                  : h('p', { class: 'muted' }, 'No correction or one-click feedback recorded yet.')
-              ])
-            ])
-          : null,
-        props.item.prediction_sealed
-          ? h('div', { class: 'prediction-sealed-badge' },
-              'Twin sealed a prediction — record your choice to reveal it')
-          : null,
-        episode.twin_prediction
-          ? h('div', { class: 'prediction-reveal' }, [
-              h('div', { class: 'prediction-headline' }, [
-                h('strong', 'Twin predicted: '),
-                h('span', episode.twin_prediction.predicted_option),
-                episode.twin_prediction.confidence != null
-                  ? h('span', { class: 'prediction-confidence' },
-                      ` (${Math.round(episode.twin_prediction.confidence * 100)}% confident)`)
-                  : null,
-                episode.agreement === true
-                  ? h('span', { class: 'agreement-badge match' }, 'Matched my choice')
-                  : null,
-                episode.agreement === false
-                  ? h('span', { class: 'agreement-badge miss' }, 'Missed')
-                  : null
-              ]),
-              episode.twin_prediction.rationale
-                ? h('p', { class: 'prediction-rationale' }, episode.twin_prediction.rationale)
-                : null
-            ])
-          : null,
-        h('details', { class: 'outcome-details', open: !episode.outcome }, [
-          h('summary', episode.outcome ? 'Outcome recorded — edit' : 'Record outcome'),
-          h('div', { class: 'outcome-row' }, [
-            episodeOptions.length
-              ? outcomeField('Chosen option', h('select', {
-                  class: 'chosen-option-select',
-                  value: chosenSelect.value,
-                  onChange: event => { chosenSelect.value = event.target.value }
-                }, [
-                  h('option', { value: '' }, 'Chosen option…'),
-                  ...episodeOptions.map(option => h('option', { value: option }, option)),
-                  h('option', { value: '__other__' }, 'Other…')
-                ]))
-              : null,
-            (!episodeOptions.length || chosenSelect.value === '__other__')
-              ? outcomeField(episodeOptions.length ? 'Other choice' : 'Chosen option', h('input', {
-                  value: chosenOther.value,
-                  placeholder: 'Chosen option',
-                  onInput: event => { chosenOther.value = event.target.value }
-                }))
-              : null,
-            outcomeField('Outcome', h('input', {
-              value: outcome.value,
-              placeholder: 'What actually happened',
-              onInput: event => { outcome.value = event.target.value }
-            })),
-            outcomeField('Lesson', h('input', {
-              value: lesson.value,
-              placeholder: 'What it taught you',
-              onInput: event => { lesson.value = event.target.value }
-            })),
-            outcomeField('Regret (0-10)', h('input', {
-              value: regretScore.value,
-              type: 'number',
-              min: '0',
-              max: '10',
-              placeholder: '0',
-              onInput: event => { regretScore.value = event.target.value }
-            })),
-            h('button', { class: 'btn btn-primary btn-sm save-outcome', onClick: save }, 'Save Outcome')
-          ]),
-          episode.agreement === false
-            ? h('div', { class: 'correction-row' }, [
-                outcomeField('Why was the twin wrong?', h('input', {
-                  value: correctionNote.value,
-                  placeholder: 'Why was the twin wrong?',
-                  onInput: event => { correctionNote.value = event.target.value }
-                }))
-              ])
-            : null
-        ])
-      ])
-    }
-  }
-})
-
-const primitiveFields = [
-  { key: 'stakes', label: 'Stakes' },
-  { key: 'reversibility', label: 'Reversibility' },
-  { key: 'time_horizon', label: 'Time' },
-  { key: 'uncertainty', label: 'Uncertainty' },
-  { key: 'agency', label: 'Agency' },
-  { key: 'value_tension', label: 'Value Tension' },
-  { key: 'constraint_pressure', label: 'Constraint' },
-  { key: 'taste_aesthetic_pull', label: 'Taste' },
-  { key: 'somatic_signal', label: 'Somatic' },
-  { key: 'action_gap_risk', label: 'Gap Risk' }
-]
-
 const recordStates = ['candidate', 'auto_promoted', 'endorsed', 'private', 'no_train', 'rejected']
 const route = useRoute() || { query: {} }
 // Matches the original per-mount ref initialization: every time this view
@@ -646,7 +411,6 @@ const route = useRoute() || { query: {} }
 twinStore.activeTab = route.query?.decision ? 'decisions' : 'overview'
 
 const routeDecisionId = computed(() => String(route.query?.decision || ''))
-const routeTraceRequested = computed(() => route.query?.trace === '1')
 
 onMounted(twinStore.loadWorkspace)
 </script>

From 52a64e790d1478aec4058c32a0197cab3fbc3dab Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 17:58:48 +0800
Subject: [PATCH 26/30] refactor: extract twin/TwinMemoryTab component

Moves the Memory Review tab (adaptive digest + user records with promotion
actions and evidence drawer trigger) out of TwinReviewView.vue verbatim.
---
 .../src/components/twin/TwinMemoryTab.vue     | 96 +++++++++++++++++++
 frontend/src/views/TwinReviewView.vue         | 94 +-----------------
 2 files changed, 98 insertions(+), 92 deletions(-)
 create mode 100644 frontend/src/components/twin/TwinMemoryTab.vue

diff --git a/frontend/src/components/twin/TwinMemoryTab.vue b/frontend/src/components/twin/TwinMemoryTab.vue
new file mode 100644
index 0000000..f433c40
--- /dev/null
+++ b/frontend/src/components/twin/TwinMemoryTab.vue
@@ -0,0 +1,96 @@
+<template>
+  <section class="tab-panel memory-grid">
+    <section class="workspace-band">
+      <div class="panel-header compact">
+        <div>
+          <h2>Adaptive Digest</h2>
+          <span>{{ twinStore.memoryDigestItems.length }} clustered items</span>
+        </div>
+      </div>
+      <div
+        v-if="twinStore.memoryDigestItems.length === 0"
+        class="empty-panel"
+      >
+        No digest items need review.
+      </div>
+      <article
+        v-for="item in twinStore.memoryDigestItems"
+        :key="item.id"
+        class="digest-card"
+      >
+        <div class="card-topline">
+          <span class="status-pill">{{ statusLabel(item.state) }}</span>
+          <span>{{ item.evidence_count }} evidence</span>
+          <span>{{ item.trigger_reason }}</span>
+        </div>
+        <p>{{ item.pattern }}</p>
+        <small v-if="item.latest_evidence?.summary">{{ item.latest_evidence.summary }}</small>
+        <ReviewActions
+          @review="action => twinStore.reviewMemoryDigestItem(item.id, action)"
+        />
+      </article>
+    </section>
+
+    <section class="workspace-band">
+      <div class="panel-header compact">
+        <div>
+          <h2>User Records</h2>
+          <span>{{ twinStore.filteredReviewRecords.length }} shown</span>
+        </div>
+        <select v-model="twinStore.selectedRecordState">
+          <option
+            v-for="state in recordStates"
+            :key="state"
+            :value="state"
+          >
+            {{ statusLabel(state) }}
+          </option>
+        </select>
+      </div>
+      <div
+        v-if="twinStore.filteredReviewRecords.length === 0"
+        class="empty-panel"
+      >
+        No records in this state.
+      </div>
+      <article
+        v-for="item in twinStore.filteredReviewRecords"
+        :key="item.record.id"
+        class="record-card"
+      >
+        <div class="card-topline">
+          <span class="status-pill">{{ kindLabel(item.record.kind) }}</span>
+          <span>{{ statusLabel(item.record.promotion_state) }}</span>
+          <span>{{ item.evidence_count }} evidence</span>
+        </div>
+        <p>{{ item.record.content }}</p>
+        <div class="record-actions">
+          <button @click="twinStore.openEvidence(item.record.id)">
+            Evidence
+          </button>
+          <button @click="twinStore.setPromotion(item.record.id, 'endorsed')">
+            Endorse
+          </button>
+          <button @click="twinStore.setPromotion(item.record.id, 'private')">
+            Private
+          </button>
+          <button @click="twinStore.setPromotion(item.record.id, 'no_train')">
+            No Train
+          </button>
+          <button @click="twinStore.setPromotion(item.record.id, 'rejected')">
+            Reject
+          </button>
+        </div>
+      </article>
+    </section>
+  </section>
+</template>
+
+<script setup>
+import { useTwinStore } from '@/stores/twin'
+import { statusLabel, kindLabel } from '@/utils/twinFormat'
+import ReviewActions from './ReviewActions.vue'
+
+const recordStates = ['candidate', 'auto_promoted', 'endorsed', 'private', 'no_train', 'rejected']
+const twinStore = useTwinStore()
+</script>
diff --git a/frontend/src/views/TwinReviewView.vue b/frontend/src/views/TwinReviewView.vue
index 7fe3ff2..7873e6f 100644
--- a/frontend/src/views/TwinReviewView.vue
+++ b/frontend/src/views/TwinReviewView.vue
@@ -197,94 +197,7 @@
 
         <TwinDecisionsTab v-else-if="twinStore.activeTab === 'decisions'" />
 
-        <section
-          v-else-if="twinStore.activeTab === 'memory'"
-          class="tab-panel memory-grid"
-        >
-          <section class="workspace-band">
-            <div class="panel-header compact">
-              <div>
-                <h2>Adaptive Digest</h2>
-                <span>{{ twinStore.memoryDigestItems.length }} clustered items</span>
-              </div>
-            </div>
-            <div
-              v-if="twinStore.memoryDigestItems.length === 0"
-              class="empty-panel"
-            >
-              No digest items need review.
-            </div>
-            <article
-              v-for="item in twinStore.memoryDigestItems"
-              :key="item.id"
-              class="digest-card"
-            >
-              <div class="card-topline">
-                <span class="status-pill">{{ statusLabel(item.state) }}</span>
-                <span>{{ item.evidence_count }} evidence</span>
-                <span>{{ item.trigger_reason }}</span>
-              </div>
-              <p>{{ item.pattern }}</p>
-              <small v-if="item.latest_evidence?.summary">{{ item.latest_evidence.summary }}</small>
-              <ReviewActions
-                @review="action => twinStore.reviewMemoryDigestItem(item.id, action)"
-              />
-            </article>
-          </section>
-
-          <section class="workspace-band">
-            <div class="panel-header compact">
-              <div>
-                <h2>User Records</h2>
-                <span>{{ twinStore.filteredReviewRecords.length }} shown</span>
-              </div>
-              <select v-model="twinStore.selectedRecordState">
-                <option
-                  v-for="state in recordStates"
-                  :key="state"
-                  :value="state"
-                >
-                  {{ statusLabel(state) }}
-                </option>
-              </select>
-            </div>
-            <div
-              v-if="twinStore.filteredReviewRecords.length === 0"
-              class="empty-panel"
-            >
-              No records in this state.
-            </div>
-            <article
-              v-for="item in twinStore.filteredReviewRecords"
-              :key="item.record.id"
-              class="record-card"
-            >
-              <div class="card-topline">
-                <span class="status-pill">{{ kindLabel(item.record.kind) }}</span>
-                <span>{{ statusLabel(item.record.promotion_state) }}</span>
-                <span>{{ item.evidence_count }} evidence</span>
-              </div>
-              <p>{{ item.record.content }}</p>
-              <div class="record-actions">
-                <button @click="twinStore.openEvidence(item.record.id)">
-                  Evidence
-                </button>
-                <button @click="twinStore.setPromotion(item.record.id, 'endorsed')">
-                  Endorse
-                </button>
-                <button @click="twinStore.setPromotion(item.record.id, 'private')">
-                  Private
-                </button>
-                <button @click="twinStore.setPromotion(item.record.id, 'no_train')">
-                  No Train
-                </button>
-                <button @click="twinStore.setPromotion(item.record.id, 'rejected')">
-                  Reject
-                </button>
-              </div>
-            </article>
-          </section>
-        </section>
+        <TwinMemoryTab v-else-if="twinStore.activeTab === 'memory'" />
 
         <TwinSetupTab v-else-if="twinStore.activeTab === 'setup'" />
 
@@ -352,16 +265,14 @@ import { useTwinStore } from '@/stores/twin'
 import {
   decisionState,
   decisionChips,
-  statusLabel,
-  kindLabel,
   formatPercent,
   formatDate,
   eventLabel
 } from '@/utils/twinFormat'
-import ReviewActions from '@/components/twin/ReviewActions.vue'
 import TwinActionGapsTab from '@/components/twin/TwinActionGapsTab.vue'
 import TwinConstitutionTab from '@/components/twin/TwinConstitutionTab.vue'
 import TwinDecisionsTab from '@/components/twin/TwinDecisionsTab.vue'
+import TwinMemoryTab from '@/components/twin/TwinMemoryTab.vue'
 import TwinGuideTab from '@/components/twin/TwinGuideTab.vue'
 import TwinSetupTab from '@/components/twin/TwinSetupTab.vue'
 import TwinConfigTab from '@/components/twin/TwinConfigTab.vue'
@@ -404,7 +315,6 @@ const navGroups = computed(() => [
   }
 ])
 
-const recordStates = ['candidate', 'auto_promoted', 'endorsed', 'private', 'no_train', 'rejected']
 const route = useRoute() || { query: {} }
 // Matches the original per-mount ref initialization: every time this view
 // mounts, the active tab is (re)computed from the current route query.

From f72f35eea6b99b61e3a627b29c1eff1af91c99a5 Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 18:02:10 +0800
Subject: [PATCH 27/30] refactor: extract twin/TwinOverviewTab and
 twin/EvidenceDrawer components

Moves the Overview tab (metric tiles, tutorial intro, recent decisions,
current action gaps) and the cross-tab evidence drawer overlay out of
TwinReviewView.vue verbatim. The view is now a 147-line shell: header,
grouped nav rail, tab routing, scroll ownership, and the save toast.
---
 .../src/components/twin/EvidenceDrawer.vue    |  49 +++++
 .../src/components/twin/TwinOverviewTab.vue   | 145 ++++++++++++++
 frontend/src/views/TwinReviewView.vue         | 188 +-----------------
 3 files changed, 198 insertions(+), 184 deletions(-)
 create mode 100644 frontend/src/components/twin/EvidenceDrawer.vue
 create mode 100644 frontend/src/components/twin/TwinOverviewTab.vue

diff --git a/frontend/src/components/twin/EvidenceDrawer.vue b/frontend/src/components/twin/EvidenceDrawer.vue
new file mode 100644
index 0000000..0de63dd
--- /dev/null
+++ b/frontend/src/components/twin/EvidenceDrawer.vue
@@ -0,0 +1,49 @@
+<template>
+  <aside
+    v-if="twinStore.selectedRecordId"
+    class="evidence-drawer"
+  >
+    <div class="drawer-header">
+      <h2>Evidence</h2>
+      <button @click="twinStore.selectedRecordId = null">
+        x
+      </button>
+    </div>
+    <div
+      v-if="twinStore.evidenceLoading"
+      class="empty-panel"
+    >
+      Loading evidence...
+    </div>
+    <div
+      v-else-if="twinStore.selectedEvidence.length === 0"
+      class="empty-panel"
+    >
+      No evidence events found.
+    </div>
+    <article
+      v-for="item in twinStore.selectedEvidence"
+      :key="item.event_id"
+      class="evidence-item"
+    >
+      <div class="card-topline">
+        <span>{{ eventLabel(item.event_type) }}</span>
+        <span>{{ formatDate(item.created_at) }}</span>
+      </div>
+      <p v-if="item.prompt_excerpt">
+        {{ item.prompt_excerpt }}
+      </p>
+      <p v-if="item.response_excerpt">
+        {{ item.response_excerpt }}
+      </p>
+      <small>{{ item.session_id }} <span v-if="item.model_id">/ {{ item.model_id }}</span></small>
+    </article>
+  </aside>
+</template>
+
+<script setup>
+import { useTwinStore } from '@/stores/twin'
+import { eventLabel, formatDate } from '@/utils/twinFormat'
+
+const twinStore = useTwinStore()
+</script>
diff --git a/frontend/src/components/twin/TwinOverviewTab.vue b/frontend/src/components/twin/TwinOverviewTab.vue
new file mode 100644
index 0000000..504b2bc
--- /dev/null
+++ b/frontend/src/components/twin/TwinOverviewTab.vue
@@ -0,0 +1,145 @@
+<template>
+  <section class="tab-panel">
+    <div class="overview-stats">
+      <button
+        class="metric-tile"
+        @click="twinStore.activeTab = 'constitution'"
+      >
+        <span>Constitution</span>
+        <strong>{{ twinStore.activeConstitutionCount }}</strong>
+        <small>{{ twinStore.constitutionItems.length }} total items</small>
+      </button>
+      <button
+        class="metric-tile"
+        @click="twinStore.activeTab = 'action_gaps'"
+      >
+        <span>Action Gaps</span>
+        <strong>{{ twinStore.activeActionGapCount }}</strong>
+        <small>{{ twinStore.actionGaps.length }} total gaps</small>
+      </button>
+      <button
+        class="metric-tile"
+        @click="twinStore.activeTab = 'decisions'"
+      >
+        <span>Decisions</span>
+        <strong>{{ twinStore.decisions.length }}</strong>
+        <small>{{ twinStore.pendingOutcomeCount }} outcomes pending</small>
+      </button>
+      <button
+        class="metric-tile"
+        @click="twinStore.activeTab = 'memory'"
+      >
+        <span>Review</span>
+        <strong>{{ twinStore.pendingReviewCount }}</strong>
+        <small>digest plus candidate records</small>
+      </button>
+    </div>
+
+    <section
+      v-if="twinStore.showTutorialIntro"
+      class="workspace-band tutorial-intro"
+    >
+      <div class="band-header">
+        <h2>How To Use</h2>
+        <div class="header-actions compact">
+          <button
+            class="text-button"
+            @click="twinStore.activeTab = 'guide'"
+          >
+            Open Guide
+          </button>
+          <button
+            class="text-button"
+            @click="twinStore.dismissTutorial"
+          >
+            Dismiss
+          </button>
+        </div>
+      </div>
+      <p>
+        Start decisions in Canvas, then use Twin Workspace for review, setup, outcomes,
+        configuration, and benchmark export.
+      </p>
+    </section>
+
+    <section class="workspace-band">
+      <div class="band-header">
+        <h2>Recent Decisions</h2>
+        <button
+          class="text-button"
+          @click="twinStore.activeTab = 'decisions'"
+        >
+          View all
+        </button>
+      </div>
+      <div
+        v-if="twinStore.recentDecisions.length === 0"
+        class="empty-panel"
+      >
+        No decision episodes yet. Start a Decision in Canvas and it will appear here.
+      </div>
+      <button
+        v-for="item in twinStore.recentDecisions"
+        :key="item.episode.id"
+        class="compact-row"
+        :class="{ highlighted: item.episode.id === routeDecisionId }"
+        @click="twinStore.activeTab = 'decisions'"
+      >
+        <span
+          class="row-dot"
+          :class="decisionState(item)"
+        />
+        <span class="row-title">{{ item.episode.decision }}</span>
+        <span class="row-chips">
+          <span
+            v-for="chip in decisionChips(item)"
+            :key="chip.id"
+            class="chip"
+            :class="chip.cls"
+          >{{ chip.label }}</span>
+        </span>
+      </button>
+    </section>
+
+    <section class="workspace-band">
+      <div class="band-header">
+        <h2>Current Action Gaps</h2>
+        <button
+          class="text-button"
+          @click="twinStore.activeTab = 'action_gaps'"
+        >
+          Review
+        </button>
+      </div>
+      <div
+        v-if="twinStore.topActionGaps.length === 0"
+        class="empty-panel"
+      >
+        No action gaps found.
+      </div>
+      <button
+        v-for="gap in twinStore.topActionGaps"
+        :key="gap.id"
+        class="compact-row"
+        @click="twinStore.activeTab = 'action_gaps'"
+      >
+        <span class="row-dot is-pending" />
+        <span class="row-title">{{ gap.decision_risk }}</span>
+        <span class="row-chips">
+          <span class="chip">{{ formatPercent(gap.confidence) }}</span>
+        </span>
+      </button>
+    </section>
+  </section>
+</template>
+
+<script setup>
+import { computed } from 'vue'
+import { useRoute } from 'vue-router'
+import { useTwinStore } from '@/stores/twin'
+import { decisionState, decisionChips, formatPercent } from '@/utils/twinFormat'
+
+const twinStore = useTwinStore()
+const route = useRoute() || { query: {} }
+const routeDecisionId = computed(() => String(route.query?.decision || ''))
+</script>
diff --git a/frontend/src/views/TwinReviewView.vue b/frontend/src/views/TwinReviewView.vue
index 7873e6f..b0951c3 100644
--- a/frontend/src/views/TwinReviewView.vue
+++ b/frontend/src/views/TwinReviewView.vue
@@ -55,141 +55,7 @@
       </nav>
 
       <main class="workspace-main">
-        <section
-          v-if="twinStore.activeTab === 'overview'"
-          class="tab-panel"
-        >
-          <div class="overview-stats">
-            <button
-              class="metric-tile"
-              @click="twinStore.activeTab = 'constitution'"
-            >
-              <span>Constitution</span>
-              <strong>{{ twinStore.activeConstitutionCount }}</strong>
-              <small>{{ twinStore.constitutionItems.length }} total items</small>
-            </button>
-            <button
-              class="metric-tile"
-              @click="twinStore.activeTab = 'action_gaps'"
-            >
-              <span>Action Gaps</span>
-              <strong>{{ twinStore.activeActionGapCount }}</strong>
-              <small>{{ twinStore.actionGaps.length }} total gaps</small>
-            </button>
-            <button
-              class="metric-tile"
-              @click="twinStore.activeTab = 'decisions'"
-            >
-              <span>Decisions</span>
-              <strong>{{ twinStore.decisions.length }}</strong>
-              <small>{{ twinStore.pendingOutcomeCount }} outcomes pending</small>
-            </button>
-            <button
-              class="metric-tile"
-              @click="twinStore.activeTab = 'memory'"
-            >
-              <span>Review</span>
-              <strong>{{ twinStore.pendingReviewCount }}</strong>
-              <small>digest plus candidate records</small>
-            </button>
-          </div>
-
-          <section
-            v-if="twinStore.showTutorialIntro"
-            class="workspace-band tutorial-intro"
-          >
-            <div class="band-header">
-              <h2>How To Use</h2>
-              <div class="header-actions compact">
-                <button
-                  class="text-button"
-                  @click="twinStore.activeTab = 'guide'"
-                >
-                  Open Guide
-                </button>
-                <button
-                  class="text-button"
-                  @click="twinStore.dismissTutorial"
-                >
-                  Dismiss
-                </button>
-              </div>
-            </div>
-            <p>
-              Start decisions in Canvas, then use Twin Workspace for review, setup, outcomes,
-              configuration, and benchmark export.
-            </p>
-          </section>
-
-          <section class="workspace-band">
-            <div class="band-header">
-              <h2>Recent Decisions</h2>
-              <button
-                class="text-button"
-                @click="twinStore.activeTab = 'decisions'"
-              >
-                View all
-              </button>
-            </div>
-            <div
-              v-if="twinStore.recentDecisions.length === 0"
-              class="empty-panel"
-            >
-              No decision episodes yet. Start a Decision in Canvas and it will appear here.
-            </div>
-            <button
-              v-for="item in twinStore.recentDecisions"
-              :key="item.episode.id"
-              class="compact-row"
-              :class="{ highlighted: item.episode.id === routeDecisionId }"
-              @click="twinStore.activeTab = 'decisions'"
-            >
-              <span
-                class="row-dot"
-                :class="decisionState(item)"
-              />
-              <span class="row-title">{{ item.episode.decision }}</span>
-              <span class="row-chips">
-                <span
-                  v-for="chip in decisionChips(item)"
-                  :key="chip.id"
-                  class="chip"
-                  :class="chip.cls"
-                >{{ chip.label }}</span>
-              </span>
-            </button>
-          </section>
-
-          <section class="workspace-band">
-            <div class="band-header">
-              <h2>Current Action Gaps</h2>
-              <button
-                class="text-button"
-                @click="twinStore.activeTab = 'action_gaps'"
-              >
-                Review
-              </button>
-            </div>
-            <div
-              v-if="twinStore.topActionGaps.length === 0"
-              class="empty-panel"
-            >
-              No action gaps found.
-            </div>
-            <button
-              v-for="gap in twinStore.topActionGaps"
-              :key="gap.id"
-              class="compact-row"
-              @click="twinStore.activeTab = 'action_gaps'"
-            >
-              <span class="row-dot is-pending" />
-              <span class="row-title">{{ gap.decision_risk }}</span>
-              <span class="row-chips">
-                <span class="chip">{{ formatPercent(gap.confidence) }}</span>
-              </span>
-            </button>
-          </section>
-        </section>
+        <TwinOverviewTab v-if="twinStore.activeTab === 'overview'" />
 
         <TwinConstitutionTab v-else-if="twinStore.activeTab === 'constitution'" />
 
@@ -207,46 +73,7 @@
       </main>
     </div>
 
-    <aside
-      v-if="twinStore.selectedRecordId"
-      class="evidence-drawer"
-    >
-      <div class="drawer-header">
-        <h2>Evidence</h2>
-        <button @click="twinStore.selectedRecordId = null">
-          x
-        </button>
-      </div>
-      <div
-        v-if="twinStore.evidenceLoading"
-        class="empty-panel"
-      >
-        Loading evidence...
-      </div>
-      <div
-        v-else-if="twinStore.selectedEvidence.length === 0"
-        class="empty-panel"
-      >
-        No evidence events found.
-      </div>
-      <article
-        v-for="item in twinStore.selectedEvidence"
-        :key="item.event_id"
-        class="evidence-item"
-      >
-        <div class="card-topline">
-          <span>{{ eventLabel(item.event_type) }}</span>
-          <span>{{ formatDate(item.created_at) }}</span>
-        </div>
-        <p v-if="item.prompt_excerpt">
-          {{ item.prompt_excerpt }}
-        </p>
-        <p v-if="item.response_excerpt">
-          {{ item.response_excerpt }}
-        </p>
-        <small>{{ item.session_id }} <span v-if="item.model_id">/ {{ item.model_id }}</span></small>
-      </article>
-    </aside>
+    <EvidenceDrawer />
 
     <div
       v-if="twinStore.message"
@@ -262,13 +89,8 @@
 import { computed, onMounted } from 'vue'
 import { useRoute } from 'vue-router'
 import { useTwinStore } from '@/stores/twin'
-import {
-  decisionState,
-  decisionChips,
-  formatPercent,
-  formatDate,
-  eventLabel
-} from '@/utils/twinFormat'
+import EvidenceDrawer from '@/components/twin/EvidenceDrawer.vue'
+import TwinOverviewTab from '@/components/twin/TwinOverviewTab.vue'
 import TwinActionGapsTab from '@/components/twin/TwinActionGapsTab.vue'
 import TwinConstitutionTab from '@/components/twin/TwinConstitutionTab.vue'
 import TwinDecisionsTab from '@/components/twin/TwinDecisionsTab.vue'
@@ -320,8 +142,6 @@ const route = useRoute() || { query: {} }
 // mounts, the active tab is (re)computed from the current route query.
 twinStore.activeTab = route.query?.decision ? 'decisions' : 'overview'
 
-const routeDecisionId = computed(() => String(route.query?.decision || ''))
-
 onMounted(twinStore.loadWorkspace)
 </script>
 

From edeea37365cbabbe84e1335f1dc2e54f9fa40636 Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 18:26:27 +0800
Subject: [PATCH 28/30] docs: CLAUDE.md reflects post-refactor structure and
 true optimizer behavior

Fixes the vault-optimizer "prevents runaway LLM spend" claim (it has no
LLM call path; proposals are rule-based and the caps limit disk writes,
locked in by a characterization test) and updates structure references
left stale by the module splits: commands/canvas.rs -> commands/canvas/,
services/twin_store.rs -> services/twin/, Pinia stores (3) -> (4) with
twin.js, components/twin/, and TwinReviewView.vue as a thin shell. Adds
a Note Write & Delete Chokepoints section documenting commit_note_write/
commit_note_delete, atomic_io::write_atomic, index_commit.rs, and the
canonical lock order, plus a size-convention entry under Working
conventions.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 CLAUDE.md | 30 +++++++++++++++++++++---------
 1 file changed, 21 insertions(+), 9 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 7c59d1c..25ee994 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -90,14 +90,14 @@ Grafyn is a **desktop-only** app — a single Tauri binary with a Vue frontend a
 
 ### Tauri IPC Commands
 
-16 modules in `frontend/src-tauri/src/commands/`. Enumerate exact command names with `grep -rn "#\[tauri::command\]" -A1 src/commands/` — purposes only below, to avoid drift.
+16 modules in `frontend/src-tauri/src/commands/`. `canvas` is a directory module (split — see below); every other module is a single file. Enumerate exact command names with `grep -rn "#\[tauri::command\]" -A1 src/commands/` — purposes only below, to avoid drift.
 
 | Module | Purpose |
 |--------|---------|
 | `notes.rs` | Note CRUD |
 | `search.rs` | Full-text search, find-similar, reindex |
 | `graph.rs` | Link graph: backlinks, outgoing, neighbors, unlinked, full graph, rebuild |
-| `canvas.rs` | Multi-LLM canvas (18 commands) with note context; streaming via `canvas-stream` Tauri events |
+| `canvas/` | Multi-LLM canvas (18 commands) with note context; streaming via `canvas-stream` Tauri events. Split across `session.rs` (session/tile CRUD), `streaming.rs` (`send_prompt`/`add_models_to_tile`/`regenerate_response`), `debate.rs` (`start_debate`/`continue_debate`), `context.rs` (retrieval + twin-context prompt assembly, incl. `build_twin_context_prompt()`), `shared.rs` (common helpers), and `mod.rs` (re-exports) |
 | `distill.rs` | LLM + rules-based distillation, tag normalization |
 | `settings.rs` | Settings, first-run setup, OpenRouter key validation, Ollama status/models |
 | `feedback.rs` | Feedback with offline queue |
@@ -114,8 +114,9 @@ Grafyn is a **desktop-only** app — a single Tauri binary with a Vue frontend a
 ### Frontend
 
 - `src/api/client.js` — all backend calls go through Tauri `invoke()`; exports one namespace per command module plus `optimizer` and `isDesktopApp`
-- **Pinia stores (3):** `canvas.js`, `theme.js`, `boot.js` — there is no twin store; twin UI state lives in `TwinReviewView.vue` and `stores/canvas.js`
-- **Routes:** `/` (notes), `/canvas`, `/canvas/:id`, `/import`, `/twin` (component: `TwinReviewView.vue`), plus catch-all → `NotFoundView.vue`
+- **Pinia stores (4):** `canvas.js`, `theme.js`, `boot.js`, `twin.js` — twin state (records, review, Constitution, action gaps, decisions, Decision Mirror config, setup) lives in the store; components read/act through it rather than holding local copies
+- `components/twin/` — the Twin Workspace's tab components (`TwinOverviewTab.vue`, `TwinSetupTab.vue`, `TwinConfigTab.vue`, `TwinConstitutionTab.vue`, `TwinActionGapsTab.vue`, `TwinDecisionsTab.vue`, `TwinMemoryTab.vue`, `TwinGuideTab.vue`) plus shared pieces (`ReviewActions.vue`, `SetupField.vue`, `ActionGapRow.vue`, `DecisionRow.vue`, `EvidenceDrawer.vue`) and `twin-workspace.css`. `views/TwinReviewView.vue` is now a ~150-line shell that wires the store to these tabs — do not add Twin Workspace logic directly to the view.
+- **Routes:** `/` (notes), `/canvas`, `/canvas/:id`, `/import`, `/twin` (component: `TwinReviewView.vue`, thin shell over `components/twin/`), plus catch-all → `NotFoundView.vue`
 - **Tests:** `src/__tests__/{unit,integration,fixtures}/` + `setup.js` (Vitest)
 
 ## Key Concepts
@@ -186,7 +187,9 @@ Streaming commands: `send_prompt`, `start_debate`, `continue_debate`, `add_model
 
 ### Twin Identity, Constitution, And Decision Mirror
 
-Twin context mode is a native RAG path, not model-weight training. `frontend/src-tauri/src/commands/canvas.rs` assembles the model-facing prompt through `build_twin_context_prompt()`.
+Twin context mode is a native RAG path, not model-weight training. `frontend/src-tauri/src/commands/canvas/context.rs` assembles the model-facing prompt through `build_twin_context_prompt()`.
+
+`TwinStore` itself is defined in `services/twin/mod.rs` (struct + shared state) with its methods split by concern across sibling files in `services/twin/`: `records.rs` (user records, inference, promotion), `constitution.rs` (Constitution items + review), `decisions.rs` (decision episodes, outcomes, Decision Mirror), `digest.rs` (memory digest), `traces.rs` (session traces, reflection cards), `export.rs` (JSONL export bundles), and `shared.rs` (corrupt-file quarantine + common helpers). There is no single `twin_store.rs` file — treat `services/twin/` as one logical module split across files, the same pattern as `commands/canvas/`.
 
 The prompt order is:
 
@@ -231,13 +234,21 @@ Configurable via `RetrievalConfig` (persisted in `data/retrieval_config.json`):
 
 Hub clustering rules: label-propagation over linked note groups; noise filtering suppresses model names, provider names, and transcript artifacts from becoming hubs; minor themes are grouped under a parent hub's `Subtopics` section rather than creating new hubs.
 
+### Note Write & Delete Chokepoints
+
+Any note write or delete that must stay consistent with the search index, chunk index, topic hubs, and vault-optimizer queue goes through two chokepoints in `commands/mod.rs`: **`commit_note_write`/`commit_note_writes`** (single/batch write — indexes the note, syncs the chunk index, runs `sync_topic_hubs`, enqueues the note in the vault optimizer) and **`commit_note_delete`** (the delete-side equivalent). **New cross-cutting write paths must call these** rather than writing a note and re-indexing ad hoc.
+
+Underlying atomic file I/O is `services/atomic_io.rs::write_atomic` (temp-file-then-rename, so a crash mid-write never leaves a half-written note on disk). `services/index_commit.rs` holds the shared search-index-write helpers (`index_note_for_search`, `commit_search`) used by both chokepoints and any other direct index writer.
+
+`commands/mod.rs`'s module-level doc comment documents the **canonical lock order**: `knowledge_store` must always be acquired before `vault_optimizer` (order doesn't matter between read/write, but `vault_optimizer` must come second) — reversing it risks an ABBA deadlock between the background vault-optimizer worker and any command that touches both locks.
+
 ### Background Services
 
 These services run automatically in the background and have dedicated inbox/decision/rollback APIs. Do not re-implement any of these — they already exist.
 
 **`services/link_discovery.rs`** — background link-discovery worker. Distinct from on-demand zettelkasten discovery (`discover_links` command). Uses YAKE keyword extraction (`services/yake.rs`) and TF-IDF cosine similarity (`services/similarity.rs`) to find wikilink candidates without LLM calls. Optional LLM pass controlled by `background_link_discovery_llm_enabled`. Results surface via `list_link_suggestion_queue` / `dismiss_link_suggestion` commands.
 
-**`services/vault_optimizer.rs`** — background vault optimizer. Queued via `enqueue_vault_optimizer_note()` whenever notes are created or migrated. Processes the queue and applies structural improvements in two modes: `sidecar_first` (overlay metadata) or `full_rewrite`. Budget caps and daily write limits prevent runaway LLM spend. Decisions are auditable via `list_vault_optimizer_decisions`; rollbacks are per-change via `rollback_vault_optimizer_change`.
+**`services/vault_optimizer.rs`** — background vault optimizer. Queued via `enqueue_vault_optimizer_note()` whenever notes are created or migrated. Processes the queue and applies structural improvements in two modes: `sidecar_first` (overlay metadata) or `full_rewrite`. **The proposals are rule-based, not LLM-based** — title-alias normalization and topic tagging computed directly from vault content; there is no `OpenRouterService`/network call anywhere in this file. `background_vault_optimizer_llm_enabled` is a reserved no-op today (a characterization test, `run_next_ignores_llm_enabled_because_no_llm_path_exists`, locks in that toggling it changes nothing); it exists as the gate a future LLM-backed enrichment step must check before making any network call. The budget/daily-write settings (`background_vault_optimizer_max_daily_writes`, etc.) cap **disk writes to the vault** (`daily_write_count`), not LLM spend. Decisions are auditable via `list_vault_optimizer_decisions`; rollbacks are per-change via `rollback_vault_optimizer_change`.
 
 **`services/markdown_migration.rs`** — one-shot structured vault migration. Preview → apply → rollback workflow. `apply_markdown_migration` runs `sync_topic_hubs` and rebuilds all indexes after applying, then enqueues touched notes in the vault optimizer. Rollback restores pre-migration state and rebuilds.
 
@@ -256,8 +267,8 @@ First-run setup wizard and persistent settings. Manages vault path, OpenRouter A
 - **`twin_llm_provider`** — selects the LLM runtime for twin context answers: `"openrouter"` (default) or `"ollama"`. Gates whether `OllamaService` or `OpenRouterService` is used in `build_twin_context_prompt()`.
 - **`ollama_base_url`** / **`ollama_model`** — endpoint and model for local inference. `get_ollama_status` probes the Ollama daemon; `list_ollama_models` enumerates pulled models. Synced via `ollama.set_base_url()` on settings change.
 - **`background_link_discovery_enabled`** / **`background_link_discovery_llm_enabled`** — controls the background link-discovery worker. When enabled, `LinkDiscoveryService` processes notes in the background using YAKE keyword extraction and TF-IDF similarity.
-- **`background_vault_optimizer_enabled`** — controls the `VaultOptimizerService`. When enabled, optimizer processes queued notes and applies structural improvements (sidecar overlay or full rewrite mode). Budget and max daily writes cap LLM costs.
-- **Vault optimizer sub-settings** (all on `UserSettings`): `background_vault_optimizer_llm_enabled`, `_budget_monthly`, `_max_daily_writes`, `_edit_mode`, `_program_enabled`, and `vault_optimizer_program_path` — the last two enable a **vault-local `program.md` policy file** that steers optimizer behavior per-vault.
+- **`background_vault_optimizer_enabled`** — controls the `VaultOptimizerService`. When enabled, optimizer processes queued notes and applies structural improvements (sidecar overlay or full rewrite mode) using rule-based proposals only (no LLM call today). Max daily writes cap disk writes to the vault, not LLM spend — see Background Services above.
+- **Vault optimizer sub-settings** (all on `UserSettings`): `background_vault_optimizer_llm_enabled` (reserved no-op — no LLM path exists yet), `_budget_monthly` (unused until an LLM path exists), `_max_daily_writes` (real — caps disk writes), `_edit_mode`, `_program_enabled`, and `vault_optimizer_program_path` — the last two enable a **vault-local `program.md` policy file** that steers optimizer behavior per-vault.
 - **`canvas_model_presets`** — saved canvas model combinations (`CanvasModelPreset` struct in `models/settings.rs`).
 
 **Runtime sync pattern:** When settings change via `update_settings`, dependent services are updated in-place — no restart required. The pattern (in `commands/settings.rs`): capture changed fields before moving the update, apply settings, then sync each affected service:
@@ -307,7 +318,7 @@ cargo build --release --bin grafyn-mcp --no-default-features --features mcp
 
 ### Test Pipeline
 
-`.github/workflows/test.yml` — runs on push to main and PRs. Jobs: `release-preflight` (version + Cargo.lock alignment), `rust-tests` (ubuntu-22.04), `frontend-tests` (Vitest), `lint` (eslint + `cargo clippy -D warnings`), `security` (`npm audit --audit-level=high`), `build` (Vite), `test-summary`. Clippy and npm audit **block** PRs.
+`.github/workflows/test.yml` — runs on push to main and PRs. Jobs: `release-preflight` (version + Cargo.lock alignment), `rust-tests` (ubuntu-22.04), `frontend-tests` (Vitest), `lint` (eslint + file-size tripwire + `cargo clippy -D warnings`), `security` (`npm audit --audit-level=high`), `build` (Vite), `test-summary`. npm audit **blocks** PRs; clippy currently runs with `continue-on-error: true` pending cleanup of pre-existing warnings (see the TODO in the `lint` job). The file-size tripwire (`npm run check:file-sizes`, `scripts/check-file-sizes.cjs`) blocks PRs when any non-test `.rs`/`.vue`/`.js` source file exceeds 2,500 lines.
 
 ### Release Pipeline
 
@@ -412,3 +423,4 @@ From `frontend/`:
 - **Read before editing.** Always Read a file in-session before Edit/Write; "File has not been read yet" failures were the most repeated tool error in this repo's sessions.
 - **Discussion-first.** When the user is exploring a design ("lets chat more", strategic questions), discuss — do not start implementing until explicitly told to build. Tool-use rejections are usually redirects back to discussion, not vetoes.
 - **Local models:** before benchmarking a new Ollama tag, smoke-test it first (prompt-echo check, choice-extraction check, max-token truncation check) — these three failure modes consumed entire past sessions.
+- **Source file size.** Keep new/edited source files under ~1,500 lines as an authoring target; CI hard-fails the `lint` job at 2,500 lines (`npm run check:file-sizes`, excludes `__tests__/`, `*.spec.js`, and Rust test-only files by path convention). New cross-cutting write paths must go through `commit_note_write`/`commit_note_delete` (`commands/mod.rs`) and `services/atomic_io.rs::write_atomic` — see "Note Write & Delete Chokepoints" above — not ad hoc file writes. When a file needs splitting, follow the mod-facade pattern already established by `commands/canvas/` (and `services/twin/`): one directory module, a `mod.rs` that re-exports, and sibling files split by concern (not by arbitrary line count).

From 49174067134cc46c7a4f186442f2e9cffe76ecb0 Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 18:26:51 +0800
Subject: [PATCH 29/30] ci: fail lint job when a source file exceeds 2,500
 lines

Adds a size tripwire so the module-split work in this refactor doesn't
silently regress: frontend/scripts/check-file-sizes.cjs walks
src-tauri/src/**/*.rs and src/**/*.{vue,js}, excluding test files by
path convention (__tests__/, *.spec.js, Rust test-only filenames), and
fails with a sorted list of offenders past the threshold. Wired into
the lint job via a new npm run check:file-sizes step. Current largest
file (commands/canvas/context.rs, 2280 lines) has ~220 lines of
headroom before this trips.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .github/workflows/test.yml            |   3 +
 frontend/package.json                 |   1 +
 frontend/scripts/check-file-sizes.cjs | 119 ++++++++++++++++++++++++++
 3 files changed, 123 insertions(+)
 create mode 100644 frontend/scripts/check-file-sizes.cjs

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 964cbe7..1c43b86 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -125,6 +125,9 @@ jobs:
       - name: Run frontend linting
         run: cd frontend && npm run lint
 
+      - name: Check source file sizes
+        run: cd frontend && npm run check:file-sizes
+
       - name: Run Rust clippy
         run: cd frontend/src-tauri && cargo clippy --all-targets -- -D warnings
         continue-on-error: true  # TODO: fix 26 pre-existing warnings, then remove this
diff --git a/frontend/package.json b/frontend/package.json
index f6a8b76..fe5693a 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -15,6 +15,7 @@
     "test:run": "vitest run",
     "test:coverage": "vitest run --coverage",
     "prepare:sidecar": "node scripts/prepare-sidecar.cjs",
+    "check:file-sizes": "node scripts/check-file-sizes.cjs",
     "tauri": "tauri",
     "tauri:dev": "node scripts/run-tauri.cjs dev",
     "tauri:build": "node scripts/run-tauri.cjs build",
diff --git a/frontend/scripts/check-file-sizes.cjs b/frontend/scripts/check-file-sizes.cjs
new file mode 100644
index 0000000..f26c3e5
--- /dev/null
+++ b/frontend/scripts/check-file-sizes.cjs
@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+
+// Size tripwire: fails when a source file grows past a line-count threshold.
+// Catches the "one file does everything" drift this refactor split apart
+// (commands/canvas.rs, services/twin_store.rs) before it recurs. See
+// CLAUDE.md "Working conventions" for the ~1,500-line authoring target —
+// this threshold (2,500) is a hard CI failure with headroom above that.
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const projectRoot = path.resolve(__dirname, '..')
+
+const DEFAULT_MAX_LINES = 2500
+
+const SCAN_ROOTS = [
+  { dir: path.join(projectRoot, 'src-tauri', 'src'), extensions: ['.rs'] },
+  { dir: path.join(projectRoot, 'src'), extensions: ['.vue', '.js'] },
+]
+
+// Path-convention exclusions only — we do not parse Rust to find
+// `#[cfg(test)]`-only files, and we do not parse JS to find describe/it
+// blocks. A file is excluded solely by where it lives or how it's named.
+function isExcluded(relativePath) {
+  const segments = relativePath.split('/')
+
+  if (segments.includes('__tests__')) {
+    return true
+  }
+
+  const basename = path.basename(relativePath)
+
+  if (/\.(spec|test)\.js$/.test(basename)) {
+    return true
+  }
+
+  // Rust test-only files by naming convention (e.g. test_support.rs,
+  // foo_test.rs) — not files that merely contain an inline `mod tests {}`.
+  if (relativePath.endsWith('.rs') && /(^|_)test(s)?(_|\.rs$)/.test(basename)) {
+    return true
+  }
+
+  return false
+}
+
+function walk(dir, extensions, results) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name)
+
+    if (entry.isDirectory()) {
+      walk(fullPath, extensions, results)
+      continue
+    }
+
+    if (extensions.includes(path.extname(entry.name))) {
+      results.push(fullPath)
+    }
+  }
+}
+
+function countLines(filePath) {
+  const contents = fs.readFileSync(filePath, 'utf8')
+  if (contents.length === 0) {
+    return 0
+  }
+  return contents.split('\n').length
+}
+
+function main() {
+  const maxLinesArg = process.argv.find((arg) => arg.startsWith('--max-lines='))
+  const maxLines = maxLinesArg ? Number(maxLinesArg.split('=')[1]) : DEFAULT_MAX_LINES
+
+  if (!Number.isFinite(maxLines) || maxLines <= 0) {
+    console.error(`check-file-sizes: invalid --max-lines value: ${maxLinesArg}`)
+    process.exit(1)
+  }
+
+  const files = []
+  for (const { dir, extensions } of SCAN_ROOTS) {
+    if (fs.existsSync(dir)) {
+      walk(dir, extensions, files)
+    }
+  }
+
+  const offenders = []
+
+  for (const filePath of files) {
+    const relativePath = path.relative(projectRoot, filePath).replace(/\\/g, '/')
+    if (isExcluded(relativePath)) {
+      continue
+    }
+
+    const lines = countLines(filePath)
+    if (lines > maxLines) {
+      offenders.push({ relativePath, lines })
+    }
+  }
+
+  offenders.sort((a, b) => b.lines - a.lines)
+
+  if (offenders.length > 0) {
+    console.error(`check-file-sizes: ${offenders.length} file(s) exceed ${maxLines} lines:`)
+    for (const { relativePath, lines } of offenders) {
+      console.error(`  ${lines.toString().padStart(6)}  ${relativePath}`)
+    }
+    console.error('')
+    console.error(
+      'Split oversized files using the mod-facade pattern (see commands/canvas/ for the exemplar) ' +
+        'instead of raising this threshold.',
+    )
+    process.exit(1)
+  }
+
+  console.log(`check-file-sizes: OK — no source file exceeds ${maxLines} lines.`)
+}
+
+main()

From 68a5d45081ccaa5df8f145d9d83bb79ff06b826e Mon Sep 17 00:00:00 2001
From: WKJBryan <bryanwangkangjie.03@gmail.com>
Date: Fri, 10 Jul 2026 18:50:09 +0800
Subject: [PATCH 30/30] docs: record owner-accepted 2,500-line tripwire in plan
 acceptance; clarify tripwire comment

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../plans/2026-07-09-production-readiness-refactor.md          | 2 +-
 frontend/scripts/check-file-sizes.cjs                          | 3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/superpowers/plans/2026-07-09-production-readiness-refactor.md b/docs/superpowers/plans/2026-07-09-production-readiness-refactor.md
index 99a7382..56674fb 100644
--- a/docs/superpowers/plans/2026-07-09-production-readiness-refactor.md
+++ b/docs/superpowers/plans/2026-07-09-production-readiness-refactor.md
@@ -260,7 +260,7 @@
 - [ ] Add convention to CLAUDE.md: source files should stay under ~1,500 lines; new cross-cutting write paths must go through `commit_note_write`/`write_atomic`.
 - [ ] Optional CI tripwire: a 10-line script failing the lint job when any `src-tauri/src/**/*.rs` or `src/**/*.{vue,js}` exceeds 2,000 lines (excluding tests). Decide with owner at PR time.
 
-**Phase 4 acceptance:** no public behavior change (full Rust + Vitest + e2e suites green before/after); largest source file < 2,000 lines; twin state has a real store.
+**Phase 4 acceptance:** no public behavior change (full Rust + Vitest + e2e suites green before/after); source files target ~1,500 lines with a 2,500-line CI hard-fail (owner decision 2026-07-10: `commands/canvas/context.rs` at 2,279 accepted — keeping the twin Simulation gate and its 21 tests together outweighs the original < 2,000 line goal); twin state has a real store.
 
 ---
 
diff --git a/frontend/scripts/check-file-sizes.cjs b/frontend/scripts/check-file-sizes.cjs
index f26c3e5..9f4de33 100644
--- a/frontend/scripts/check-file-sizes.cjs
+++ b/frontend/scripts/check-file-sizes.cjs
@@ -2,7 +2,8 @@
 
 // Size tripwire: fails when a source file grows past a line-count threshold.
 // Catches the "one file does everything" drift this refactor split apart
-// (commands/canvas.rs, services/twin_store.rs) before it recurs. See
+// (the old single-file commands/canvas.rs and services/twin_store.rs, now
+// the commands/canvas/ and services/twin/ module directories) before it recurs. See
 // CLAUDE.md "Working conventions" for the ~1,500-line authoring target —
 // this threshold (2,500) is a hard CI failure with headroom above that.