Skip to main content

qualia_client_core/
chat_graph.rs

1//! Chat graph — selectable fragments and reply edges forming a DAG off the linear chat.
2
3use std::fs::{File, OpenOptions};
4use std::io::{BufRead, BufReader, Write};
5use std::path::{Path, PathBuf};
6
7use qualia_core_db::{q_hash, wal::WriteAheadLog, NQuin};
8use serde::{Deserialize, Serialize};
9
10use crate::chat_session::{ChatError, Role};
11
12const OBJECT_HASH_MASK: u64 = 0x0FFF_FFFF_FFFF_FFFF;
13const LAMPORT_SHIFT: u32 = 32;
14const LAMPORT_MASK: u64 = 0x1FFF_FFFF;
15
16#[derive(Debug, Clone, Serialize, Deserialize)]
17pub struct ChatFragment {
18    pub fragment_id: String,
19    pub message_lamport: u64,
20    pub anchor_start: u32,
21    pub anchor_end: u32,
22    pub anchor_text: String,
23    pub author_did: Option<String>,
24    pub author_name: Option<String>,
25    pub created_at: u64,
26}
27
28#[derive(Debug, Clone, Serialize, Deserialize)]
29pub struct ChatGraphEdge {
30    pub child_fragment_id: String,
31    pub parent_fragment_id: String,
32    pub reply_message_lamport: u64,
33    pub created_at: u64,
34    #[serde(default)]
35    pub branch_type_id: Option<String>,
36    #[serde(default)]
37    pub branch_label: Option<String>,
38    #[serde(default)]
39    pub branch_emoji: Option<String>,
40    #[serde(default)]
41    pub wordnet_grounding_hash: Option<String>,
42}
43
44#[derive(Debug, Clone, Serialize, Deserialize)]
45pub struct ChatGraphSnapshot {
46    pub fragments: Vec<ChatFragment>,
47    pub edges: Vec<ChatGraphEdge>,
48}
49
50fn fragments_path(storage_root: &Path, session_id: &str) -> PathBuf {
51    storage_root
52        .join("Chats")
53        .join(session_id)
54        .join("fragments.jsonl")
55}
56
57fn edges_path(storage_root: &Path, session_id: &str) -> PathBuf {
58    storage_root
59        .join("Chats")
60        .join(session_id)
61        .join("graph_edges.jsonl")
62}
63
64fn unix_now() -> u64 {
65    std::time::SystemTime::now()
66        .duration_since(std::time::UNIX_EPOCH)
67        .unwrap_or_default()
68        .as_secs()
69}
70
71/// Fragment ID for a span.
72pub fn fragment_id_for_span(session_id: &str, lamport: u64, start: u32, end: u32) -> String {
73    let raw = q_hash(&format!("frag:{session_id}:{lamport}:{start}:{end}"));
74    format!("{raw:016x}")
75}
76
77fn session_subject_hash(session_id: &str) -> u64 {
78    q_hash(&format!("chat:session:{session_id}"))
79}
80
81fn build_fragment_quin(session_id: &str, fragment_id_hex: &str, lamport: u64) -> NQuin {
82    let subject = session_subject_hash(session_id);
83    let predicate = q_hash("chat:hasFragment");
84    let object = u64::from_str_radix(fragment_id_hex, 16).unwrap_or(0) & OBJECT_HASH_MASK;
85    let context = q_hash(&format!("msg:{lamport}"));
86    let metadata = (lamport & LAMPORT_MASK) << LAMPORT_SHIFT;
87    let parity = subject ^ predicate ^ object ^ context ^ metadata;
88    NQuin {
89        subject,
90        predicate,
91        object,
92        context,
93        metadata,
94        parity,
95    }
96}
97
98fn build_reply_edge_quin(
99    session_id: &str,
100    child_fragment_id_hex: &str,
101    parent_fragment_id_hex: &str,
102    reply_lamport: u64,
103) -> NQuin {
104    let subject = u64::from_str_radix(child_fragment_id_hex, 16).unwrap_or(0) & OBJECT_HASH_MASK;
105    let predicate = q_hash("chat:repliesTo");
106    let object = u64::from_str_radix(parent_fragment_id_hex, 16).unwrap_or(0) & OBJECT_HASH_MASK;
107    let context = session_subject_hash(session_id);
108    let metadata = (reply_lamport & LAMPORT_MASK) << LAMPORT_SHIFT;
109    let parity = subject ^ predicate ^ object ^ context ^ metadata;
110    NQuin {
111        subject,
112        predicate,
113        object,
114        context,
115        metadata,
116        parity,
117    }
118}
119
120fn append_jsonl<T: Serialize>(path: &Path, row: &T) -> Result<(), ChatError> {
121    if let Some(parent) = path.parent() {
122        std::fs::create_dir_all(parent)?;
123    }
124    let mut file = OpenOptions::new().create(true).append(true).open(path)?;
125    writeln!(file, "{}", serde_json::to_string(row)?)?;
126    Ok(())
127}
128
129fn read_fragments(path: &Path) -> Result<Vec<ChatFragment>, ChatError> {
130    if !path.is_file() {
131        return Ok(Vec::new());
132    }
133    let file = File::open(path)?;
134    let reader = BufReader::new(file);
135    let mut out = Vec::new();
136    for line in reader.lines() {
137        let line = line?;
138        if line.trim().is_empty() {
139            continue;
140        }
141        out.push(serde_json::from_str(&line)?);
142    }
143    Ok(out)
144}
145
146fn read_edges(path: &Path) -> Result<Vec<ChatGraphEdge>, ChatError> {
147    if !path.is_file() {
148        return Ok(Vec::new());
149    }
150    let file = File::open(path)?;
151    let reader = BufReader::new(file);
152    let mut out = Vec::new();
153    for line in reader.lines() {
154        let line = line?;
155        if line.trim().is_empty() {
156            continue;
157        }
158        out.push(serde_json::from_str(&line)?);
159    }
160    Ok(out)
161}
162
163/// Loads graph.
164pub fn load_graph(storage_root: &Path, session_id: &str) -> Result<ChatGraphSnapshot, ChatError> {
165    Ok(ChatGraphSnapshot {
166        fragments: read_fragments(&fragments_path(storage_root, session_id))?,
167        edges: read_edges(&edges_path(storage_root, session_id))?,
168    })
169}
170
171/// Creates fragment-from-selection.
172pub fn create_fragment_from_selection(
173    storage_root: &Path,
174    session_id: &str,
175    message_lamport: u64,
176    message_content: &str,
177    anchor_start: u32,
178    anchor_end: u32,
179) -> Result<ChatFragment, ChatError> {
180    let start = anchor_start.min(message_content.len() as u32);
181    let end = anchor_end.max(start).min(message_content.len() as u32);
182    let anchor_text = message_content[start as usize..end as usize]
183        .trim()
184        .to_string();
185    if anchor_text.is_empty() {
186        return Err(ChatError::InvalidSession(
187            "Selected fragment is empty.".to_string(),
188        ));
189    }
190
191    let fragment_id = fragment_id_for_span(session_id, message_lamport, start, end);
192    let profile = crate::user_profile::load_profile();
193    let fragment = ChatFragment {
194        fragment_id: fragment_id.clone(),
195        message_lamport,
196        anchor_start: start,
197        anchor_end: end,
198        anchor_text,
199        author_did: profile
200            .sharing
201            .share_public_did
202            .then(|| profile.public_did.clone()),
203        author_name: profile
204            .sharing
205            .share_display_name
206            .then(|| profile.display_name.clone()),
207        created_at: unix_now(),
208    };
209
210    let frag_path = fragments_path(storage_root, session_id);
211    let existing = read_fragments(&frag_path)?;
212    if !existing.iter().any(|f| f.fragment_id == fragment_id) {
213        append_jsonl(&frag_path, &fragment)?;
214        let wal_path = storage_root.join("Chats").join(session_id).join("chat.wal");
215        let quin = build_fragment_quin(session_id, &fragment_id, message_lamport);
216        let mut wal = WriteAheadLog::open(&wal_path)
217            .map_err(|e| ChatError::Wal(format!("Cannot open chat.wal: {e}")))?;
218        wal.append_mutation(&quin)
219            .map_err(|e| ChatError::Wal(format!("fragment quin append failed: {e}")))?;
220    }
221
222    Ok(fragment)
223}
224
225/// Links a reply to a fragment.
226pub fn link_reply_to_fragment(
227    storage_root: &Path,
228    session_id: &str,
229    parent_fragment_id: &str,
230    reply_message_lamport: u64,
231    child_fragment_id: Option<&str>,
232    anchor_text: Option<&str>,
233    reply_text: Option<&str>,
234    branch_type_override: Option<&str>,
235) -> Result<ChatGraphEdge, ChatError> {
236    let child_id = child_fragment_id
237        .map(|s| s.to_string())
238        .unwrap_or_else(|| fragment_id_for_span(session_id, reply_message_lamport, 0, 0));
239
240    let classification = if let Some(override_id) = branch_type_override {
241        crate::chat_ontology::list_branch_types(storage_root)
242            .into_iter()
243            .find(|t| t.id == override_id)
244            .map(|t| crate::chat_ontology::BranchClassification {
245                branch_type_id: t.id,
246                label: t.label,
247                emoji: t.emoji,
248                confidence: 1.0,
249                wordnet_grounding_hash: t.wordnet_grounding_hash,
250            })
251    } else {
252        match (anchor_text, reply_text) {
253            (Some(a), Some(r)) => Some(crate::chat_ontology::classify_branch(storage_root, a, r)),
254            _ => None,
255        }
256    };
257
258    let edge = ChatGraphEdge {
259        child_fragment_id: child_id.clone(),
260        parent_fragment_id: parent_fragment_id.to_string(),
261        reply_message_lamport,
262        created_at: unix_now(),
263        branch_type_id: classification.as_ref().map(|c| c.branch_type_id.clone()),
264        branch_label: classification.as_ref().map(|c| c.label.clone()),
265        branch_emoji: classification.as_ref().map(|c| c.emoji.clone()),
266        wordnet_grounding_hash: classification.and_then(|c| c.wordnet_grounding_hash),
267    };
268
269    append_jsonl(&edges_path(storage_root, session_id), &edge)?;
270
271    let wal_path = storage_root.join("Chats").join(session_id).join("chat.wal");
272    let quin = build_reply_edge_quin(
273        session_id,
274        &child_id,
275        parent_fragment_id,
276        reply_message_lamport,
277    );
278    let mut wal = WriteAheadLog::open(&wal_path)
279        .map_err(|e| ChatError::Wal(format!("Cannot open chat.wal: {e}")))?;
280    wal.append_mutation(&quin)
281        .map_err(|e| ChatError::Wal(format!("reply edge quin append failed: {e}")))?;
282
283    Ok(edge)
284}
285
286/// Builds thread-context-block.
287pub fn build_thread_context_block(
288    storage_root: &Path,
289    session_id: &str,
290    target_fragment_id: &str,
291    max_depth: usize,
292) -> Result<String, ChatError> {
293    let graph = load_graph(storage_root, session_id)?;
294    let session = crate::chat_session::load_session(storage_root, session_id)?;
295
296    let mut lines = vec!["[Chat graph thread context]".to_string()];
297    let mut current = target_fragment_id.to_string();
298    let mut depth = 0;
299
300    while depth < max_depth {
301        let fragment = graph.fragments.iter().find(|f| f.fragment_id == current);
302        if let Some(f) = fragment {
303            lines.push(format!(
304                "fragment {} (msg #{}) anchor=\"{}\"",
305                f.fragment_id, f.message_lamport, f.anchor_text
306            ));
307            if let Some(msg) = session
308                .messages
309                .iter()
310                .find(|m| m.lamport == f.message_lamport)
311            {
312                let author = msg.author_name.as_deref().unwrap_or(match msg.role {
313                    Role::User => "user",
314                    Role::Agent => "agent",
315                });
316                lines.push(format!("  full_message[{author}]: {}", msg.content));
317            }
318        }
319
320        let parent_edge = graph.edges.iter().find(|e| e.child_fragment_id == current);
321        match parent_edge {
322            Some(e) => {
323                current = e.parent_fragment_id.clone();
324                depth += 1;
325            }
326            None => break,
327        }
328    }
329
330    let child_edges: Vec<_> = graph
331        .edges
332        .iter()
333        .filter(|e| e.parent_fragment_id == target_fragment_id)
334        .collect();
335    if !child_edges.is_empty() {
336        lines.push("direct_replies:".to_string());
337        for e in child_edges {
338            if let Some(reply_msg) = session
339                .messages
340                .iter()
341                .find(|m| m.lamport == e.reply_message_lamport)
342            {
343                let branch = e.branch_emoji.as_deref().unwrap_or("💬");
344                let label = e.branch_label.as_deref().unwrap_or("Comment");
345                lines.push(format!(
346                    "  → {branch} {label} msg #{}: {}",
347                    e.reply_message_lamport, reply_msg.content
348                ));
349            }
350        }
351    }
352
353    Ok(lines.join("\n"))
354}
355
356/// Formats a thread context block with branch taxonomy and WordNet synset info.
357///
358/// Streaming counterpart of [`build_thread_context_block`]: walks the ancestor
359/// chain of `target_fragment_id` up to `max_depth`, then the target's direct
360/// replies, writing each entry directly into `writer` as
361/// `[Branch: <label> / WordNet: 0x<hash>] anchor="<text>" author="<did>"`.
362/// The caller owns the rendered output, so the function stays caller-buffered;
363/// only the cold Tier-2 graph/session load allocates internally.
364pub fn format_thread_context_to<W: std::fmt::Write>(
365    storage_root: &Path,
366    session_id: &str,
367    target_fragment_id: &str,
368    max_depth: usize,
369    writer: &mut W,
370) -> Result<(), ChatError> {
371    let graph = load_graph(storage_root, session_id)?;
372    let session = crate::chat_session::load_session(storage_root, session_id)?;
373
374    writeln!(writer, "[Chat graph thread context]")?;
375
376    // Ancestor chain: the edge with `child_fragment_id == current` carries the
377    // dialectical branch classification that produced this fragment.
378    let mut current = target_fragment_id.to_string();
379    let mut depth = 0usize;
380    while depth < max_depth {
381        let fragment = graph.fragments.iter().find(|f| f.fragment_id == current);
382        let Some(fragment) = fragment else { break };
383        let edge = graph
384            .edges
385            .iter()
386            .find(|e| e.child_fragment_id == fragment.fragment_id);
387        let (label, wordnet) = edge
388            .map(|e| {
389                (
390                    e.branch_label.as_deref().unwrap_or("Comment"),
391                    e.wordnet_grounding_hash.as_deref().unwrap_or("none"),
392                )
393            })
394            .unwrap_or(("Root", "none"));
395        let author = fragment.author_did.as_deref().unwrap_or("unknown");
396        writeln!(
397            writer,
398            "[Branch: {label} / WordNet: {wordnet}] anchor=\"{}\" author=\"{author}\"",
399            fragment.anchor_text,
400        )?;
401        match edge {
402            Some(e) => {
403                current = e.parent_fragment_id.clone();
404                depth += 1;
405            }
406            None => break,
407        }
408    }
409
410    let child_edges: Vec<_> = graph
411        .edges
412        .iter()
413        .filter(|e| e.parent_fragment_id == target_fragment_id)
414        .collect();
415    if !child_edges.is_empty() {
416        writeln!(writer, "direct_replies:")?;
417        for e in child_edges {
418            let label = e.branch_label.as_deref().unwrap_or("Comment");
419            let wordnet = e.wordnet_grounding_hash.as_deref().unwrap_or("none");
420            if let Some(reply_msg) = session
421                .messages
422                .iter()
423                .find(|m| m.lamport == e.reply_message_lamport)
424            {
425                let author = reply_msg
426                    .author_name
427                    .as_deref()
428                    .unwrap_or(match reply_msg.role {
429                        Role::User => "user",
430                        Role::Agent => "agent",
431                    });
432                writeln!(
433                    writer,
434                    "  -> [Branch: {label} / WordNet: {wordnet}] anchor=\"{}\" author=\"{author}\"",
435                    reply_msg.content,
436                )?;
437            }
438        }
439    }
440
441    Ok(())
442}
443
444/// Appends a message with reply linkage.
445pub fn append_message_with_reply(
446    storage_root: &Path,
447    session_id: &str,
448    role: Role,
449    content: &str,
450    reply_to_fragment_id: Option<&str>,
451) -> Result<u64, ChatError> {
452    crate::chat_session::append_message_with_options(
453        storage_root,
454        session_id,
455        role,
456        content,
457        reply_to_fragment_id.map(|s| s.to_string()),
458        None,
459    )
460}
461
462#[cfg(test)]
463mod tests {
464    use super::*;
465    use std::env;
466
467    fn temp_storage() -> PathBuf {
468        let mut dir = env::temp_dir();
469        dir.push(format!("qualia-chatgraph-test-{}", rand::random::<u32>()));
470        dir
471    }
472
473    #[test]
474    fn thread_context_formats_branch_taxonomy_and_replies() {
475        let storage = temp_storage();
476        let session_id =
477            crate::chat_session::create_session(&storage, Some("Graph".into()), None).unwrap();
478        let lamport = crate::chat_session::append_message(
479            &storage,
480            &session_id,
481            Role::User,
482            "we should adopt the plan",
483        )
484        .unwrap();
485        let reply_lamport = crate::chat_session::append_message(
486            &storage,
487            &session_id,
488            Role::Agent,
489            "I disagree with that step",
490        )
491        .unwrap();
492
493        let frag = create_fragment_from_selection(
494            &storage,
495            &session_id,
496            lamport,
497            "we should adopt the plan",
498            0,
499            9,
500        )
501        .unwrap();
502        let edge = link_reply_to_fragment(
503            &storage,
504            &session_id,
505            &frag.fragment_id,
506            reply_lamport,
507            None,
508            Some("adopt the plan"),
509            Some("I disagree with that step"),
510            Some("objection"),
511        )
512        .unwrap();
513        assert_eq!(edge.branch_label.as_deref(), Some("Objection"));
514
515        let mut out = String::new();
516        format_thread_context_to(&storage, &session_id, &frag.fragment_id, 6, &mut out).unwrap();
517        assert!(out.contains("[Chat graph thread context]"));
518        assert!(out.contains("[Branch: Root / WordNet: none] anchor=\"we should\""));
519        assert!(out.contains("direct_replies:"));
520        assert!(out.contains("[Branch: Objection / WordNet:"));
521        assert!(out.contains("I disagree with that step"));
522
523        let _ = std::fs::remove_dir_all(&storage);
524    }
525
526    #[test]
527    fn thread_context_walks_ancestors_to_max_depth() {
528        let storage = temp_storage();
529        let session_id =
530            crate::chat_session::create_session(&storage, Some("Graph".into()), None).unwrap();
531        let lamport_a = crate::chat_session::append_message(
532            &storage,
533            &session_id,
534            Role::User,
535            "first proposal text",
536        )
537        .unwrap();
538        let lamport_b = crate::chat_session::append_message(
539            &storage,
540            &session_id,
541            Role::User,
542            "a clarifying follow up",
543        )
544        .unwrap();
545
546        let frag_a = create_fragment_from_selection(
547            &storage,
548            &session_id,
549            lamport_a,
550            "first proposal text",
551            0,
552            5,
553        )
554        .unwrap();
555        let frag_b = create_fragment_from_selection(
556            &storage,
557            &session_id,
558            lamport_b,
559            "a clarifying follow up",
560            0,
561            12,
562        )
563        .unwrap();
564        link_reply_to_fragment(
565            &storage,
566            &session_id,
567            &frag_a.fragment_id,
568            lamport_b,
569            Some(&frag_b.fragment_id),
570            Some("proposal"),
571            Some("a clarifying follow up"),
572            Some("clarification"),
573        )
574        .unwrap();
575
576        let mut out = String::new();
577        format_thread_context_to(&storage, &session_id, &frag_b.fragment_id, 6, &mut out).unwrap();
578        // Child fragment annotated with the Clarification branch; ancestor follows.
579        assert!(out.contains("[Branch: Clarification / WordNet:"));
580        assert!(out.contains("anchor=\"a clarifying\""));
581        assert!(out.contains("anchor=\"first\""));
582
583        // Depth 1 shows only the target fragment, not the ancestor.
584        let mut shallow = String::new();
585        format_thread_context_to(&storage, &session_id, &frag_b.fragment_id, 1, &mut shallow)
586            .unwrap();
587        assert!(shallow.contains("a clarifying"));
588        assert!(!shallow.contains("anchor=\"first\""));
589
590        let _ = std::fs::remove_dir_all(&storage);
591    }
592}