Skip to main content

qualia_client_core/
chat_session.rs

1//! Chat session persistence — WAL quins + JSON sidecar under `{storage}/Chats/`.
2
3use std::fs::{self, 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
10const OBJECT_HASH_MASK: u64 = 0x0FFF_FFFF_FFFF_FFFF;
11
12/// The content hash carried on a chat message: FNV-1a `q_hash` of the content, masked to the 60-bit
13/// object space. Public so interop layers (e.g. `solid_chat`) can reproduce it for imported messages.
14pub fn content_hash_u64(content: &str) -> u64 {
15    q_hash(content) & OBJECT_HASH_MASK
16}
17const LAMPORT_SHIFT: u32 = 32;
18const LAMPORT_MASK: u64 = 0x1FFF_FFFF;
19
20#[derive(Debug)]
21pub enum ChatError {
22    NotFound(String),
23    InvalidSession(String),
24    Wal(String),
25    Io(std::io::Error),
26    Json(serde_json::Error),
27    Compact(String),
28    Render(String),
29}
30
31impl std::fmt::Display for ChatError {
32    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
33        match self {
34            ChatError::NotFound(id) => write!(f, "Chat session not found: {id}"),
35            ChatError::InvalidSession(msg) => write!(f, "Invalid session: {msg}"),
36            ChatError::Wal(msg) => write!(f, "WAL error: {msg}"),
37            ChatError::Io(e) => write!(f, "IO error: {e}"),
38            ChatError::Json(e) => write!(f, "JSON error: {e}"),
39            ChatError::Compact(msg) => write!(f, "Compaction error: {msg}"),
40            ChatError::Render(msg) => write!(f, "Render error: {msg}"),
41        }
42    }
43}
44
45impl From<std::io::Error> for ChatError {
46    fn from(e: std::io::Error) -> Self {
47        ChatError::Io(e)
48    }
49}
50
51impl From<std::fmt::Error> for ChatError {
52    fn from(e: std::fmt::Error) -> Self {
53        ChatError::Render(format!("thread-context writer failed: {e}"))
54    }
55}
56
57impl From<serde_json::Error> for ChatError {
58    fn from(e: serde_json::Error) -> Self {
59        ChatError::Json(e)
60    }
61}
62
63#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
64#[serde(rename_all = "lowercase")]
65pub enum SessionKind {
66    #[default]
67    Solo,
68    Group,
69}
70
71#[derive(Debug, Clone, Serialize, Deserialize)]
72pub struct ChatParticipant {
73    pub did: String,
74    pub display_name: String,
75    pub actor_id: String,
76    pub role: String,
77    pub joined_at: u64,
78}
79
80#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
81#[serde(rename_all = "lowercase")]
82pub enum Role {
83    User,
84    Agent,
85}
86
87impl Role {
88    /// `str` form.
89    pub fn as_str(self) -> &'static str {
90        match self {
91            Role::User => "user",
92            Role::Agent => "agent",
93        }
94    }
95
96    /// Constructs from str.
97    pub fn from_str(s: &str) -> Result<Self, ChatError> {
98        match s.to_lowercase().as_str() {
99            "user" => Ok(Role::User),
100            "agent" => Ok(Role::Agent),
101            _ => Err(ChatError::InvalidSession(format!("unknown role: {s}"))),
102        }
103    }
104}
105
106/// Per-ontology scope summary compiled into the chat environment.
107#[derive(Debug, Clone, Serialize, Deserialize)]
108pub struct OntologyScopeSummary {
109    pub id: String,
110    pub name: String,
111    pub quin_count: u64,
112    pub q42_path: String,
113    #[serde(default)]
114    pub domain: Option<String>,
115    #[serde(default)]
116    pub tags: Option<Vec<String>>,
117    #[serde(default)]
118    pub source: Option<String>,
119}
120
121/// Snapshot of chat inference scope and LLM-visible capabilities.
122#[derive(Debug, Clone, Serialize, Deserialize)]
123pub struct ChatEnvironment {
124    pub session_id: String,
125    pub active_model_profile_id: u64,
126    pub ontology_ids: Vec<String>,
127    pub prior_session_ids: Vec<String>,
128    pub graph_scope_hashes: Vec<u64>,
129    #[serde(default)]
130    pub lexicon_prefixes: Vec<u64>,
131    #[serde(default)]
132    pub capability_briefing: String,
133    #[serde(default)]
134    pub model_id: Option<String>,
135    #[serde(default)]
136    pub model_modality: String,
137    #[serde(default)]
138    pub context_window: u32,
139    #[serde(default)]
140    pub engine_capabilities: Vec<String>,
141    #[serde(default)]
142    pub installed_qapps: Vec<String>,
143    #[serde(default)]
144    pub ontology_summaries: Vec<OntologyScopeSummary>,
145    #[serde(default)]
146    pub daemon_reachable: bool,
147    #[serde(default)]
148    pub session_kind: SessionKind,
149    #[serde(default)]
150    pub participants: Vec<ChatParticipant>,
151    /// When true, chat turns route through the neuro-symbolic sieve + WAL orchestrator path.
152    #[serde(default)]
153    pub graph_mutation: bool,
154    #[serde(default)]
155    pub axiom_bounds: crate::context_binding::AxiomBounds,
156}
157
158fn active_model_profile_id() -> u64 {
159    let path = crate::state::app_meta_dir().join("active_model.json");
160    if let Ok(text) = fs::read_to_string(path) {
161        if let Ok(record) = serde_json::from_str::<crate::model_lifecycle::ActiveModelRecord>(&text)
162        {
163            return record.profile_id;
164        }
165    }
166    0
167}
168
169impl ChatEnvironment {
170    /// Default options for a session.
171    pub fn default_for_session(session_id: &str, storage_root: &Path) -> Self {
172        let catalog = qualia_core_db::resource_catalog::load_default()
173            .unwrap_or_else(|_| qualia_core_db::resource_catalog::ResourceCatalog::empty());
174        crate::context_binding::compile_chat_environment(
175            storage_root,
176            &catalog,
177            &crate::context_binding::ChatEnvironmentConfig {
178                session_id: session_id.to_string(),
179                ontology_ids: Vec::new(),
180                prior_session_ids: Vec::new(),
181                session_kind: SessionKind::Solo,
182                participants: Vec::new(),
183                graph_mutation: false,
184                axiom_bounds: crate::context_binding::AxiomBounds::default(),
185            },
186        )
187        .unwrap_or_else(|_| {
188            let profile_id = active_model_profile_id();
189            let session_scope = q_hash(&format!("chat:session:{session_id}"));
190            Self {
191                session_id: session_id.to_string(),
192                active_model_profile_id: profile_id,
193                ontology_ids: Vec::new(),
194                prior_session_ids: Vec::new(),
195                graph_scope_hashes: vec![session_scope],
196                lexicon_prefixes: Vec::new(),
197                capability_briefing: String::new(),
198                model_id: None,
199                model_modality: "text".to_string(),
200                context_window: 4096,
201                engine_capabilities: Vec::new(),
202                installed_qapps: Vec::new(),
203                ontology_summaries: Vec::new(),
204                daemon_reachable: false,
205                session_kind: SessionKind::Solo,
206                participants: Vec::new(),
207                graph_mutation: false,
208                axiom_bounds: crate::context_binding::AxiomBounds::default(),
209            }
210        })
211    }
212
213    /// Saves to-session-dir.
214    pub fn save_to_session_dir(&self, storage_root: &Path) -> Result<(), ChatError> {
215        let path = session_dir(storage_root, &self.session_id).join("environment.json");
216        fs::write(path, serde_json::to_string_pretty(self)?)?;
217        Ok(())
218    }
219}
220
221#[derive(Debug, Clone, Serialize, Deserialize)]
222pub struct SessionMeta {
223    pub id: String,
224    pub title: String,
225    pub created_at: u64,
226    pub updated_at: u64,
227    pub message_count: u64,
228    pub next_lamport: u64,
229    pub environment_ref: String,
230    #[serde(default)]
231    pub session_kind: SessionKind,
232    #[serde(default)]
233    pub participants: Vec<ChatParticipant>,
234    #[serde(default)]
235    pub owner_did: String,
236    /// Stable DID for ontology / torrent sharing scoped to this chat session or group.
237    #[serde(default)]
238    pub session_did: String,
239}
240
241/// Target descriptor for ontology sharing UI (solo chats and group sessions).
242#[derive(Debug, Clone, Serialize, Deserialize)]
243pub struct ChatSessionShareTarget {
244    pub session_id: String,
245    pub session_did: String,
246    pub title: String,
247    pub session_kind: SessionKind,
248    pub participant_count: u64,
249}
250
251/// Compiles the session DID.
252pub fn compile_session_did(session_id: &str, kind: SessionKind) -> String {
253    let scope = match kind {
254        SessionKind::Solo => "solo",
255        SessionKind::Group => "group",
256    };
257    let digest = q_hash(&format!("qualia:chat:{scope}:{session_id}"));
258    format!("did:qualia:chat:{scope}:{digest:016x}")
259}
260
261fn ensure_session_did(meta: &mut SessionMeta) -> String {
262    if meta.session_did.is_empty() {
263        meta.session_did = compile_session_did(&meta.id, meta.session_kind);
264    }
265    meta.session_did.clone()
266}
267
268fn persist_session_did_if_needed(
269    storage_root: &Path,
270    meta: &mut SessionMeta,
271) -> Result<(), ChatError> {
272    let before = meta.session_did.clone();
273    let _ = ensure_session_did(meta);
274    if meta.session_did != before {
275        let path = session_meta_path(storage_root, &meta.id);
276        fs::write(path, serde_json::to_string_pretty(meta)?)?;
277    }
278    Ok(())
279}
280
281#[derive(Debug, Clone, Serialize, Deserialize)]
282pub struct ChatMessage {
283    pub lamport: u64,
284    pub role: Role,
285    pub content: String,
286    pub timestamp: u64,
287    pub content_hash: u64,
288    #[serde(default, skip_serializing_if = "Option::is_none")]
289    pub author_did: Option<String>,
290    #[serde(default, skip_serializing_if = "Option::is_none")]
291    pub author_name: Option<String>,
292    #[serde(default, skip_serializing_if = "Option::is_none")]
293    pub reply_to_fragment: Option<String>,
294    #[serde(default, skip_serializing_if = "Option::is_none")]
295    pub source: Option<String>,
296    /// Human principal DID — agent messages are sub-agents of this participant.
297    #[serde(default, skip_serializing_if = "Option::is_none")]
298    pub sub_agent_of: Option<String>,
299    #[serde(default, skip_serializing_if = "Option::is_none")]
300    pub agent_did: Option<String>,
301    #[serde(default, skip_serializing_if = "Option::is_none")]
302    pub model_id: Option<String>,
303    #[serde(default, skip_serializing_if = "Option::is_none")]
304    pub agent_backend: Option<String>,
305    #[serde(default, skip_serializing_if = "Option::is_none")]
306    pub outcome_sharing: Option<crate::chat_agents::OutcomeSharingPolicy>,
307}
308
309#[derive(Debug, Clone, Serialize, Deserialize)]
310pub struct ChatSessionSummary {
311    pub id: String,
312    pub title: String,
313    pub created_at: u64,
314    pub updated_at: u64,
315    pub message_count: u64,
316    #[serde(default)]
317    pub session_kind: SessionKind,
318    #[serde(default)]
319    pub participant_count: u64,
320    #[serde(default)]
321    pub session_did: String,
322}
323
324#[derive(Debug, Clone, Serialize, Deserialize)]
325pub struct ChatSession {
326    pub meta: SessionMeta,
327    pub environment: ChatEnvironment,
328    pub messages: Vec<ChatMessage>,
329}
330
331#[derive(Debug, Clone, Serialize, Deserialize)]
332struct LastSessionPrefs {
333    last_session_id: Option<String>,
334}
335
336/// Chats directory.
337pub fn chats_dir(storage_root: &Path) -> PathBuf {
338    storage_root.join("Chats")
339}
340
341fn session_dir(storage_root: &Path, id: &str) -> PathBuf {
342    chats_dir(storage_root).join(id)
343}
344
345fn session_meta_path(storage_root: &Path, id: &str) -> PathBuf {
346    session_dir(storage_root, id).join("session.json")
347}
348
349fn environment_path(storage_root: &Path, id: &str) -> PathBuf {
350    session_dir(storage_root, id).join("environment.json")
351}
352
353fn messages_path(storage_root: &Path, id: &str) -> PathBuf {
354    session_dir(storage_root, id).join("messages.jsonl")
355}
356
357fn wal_path(storage_root: &Path, id: &str) -> PathBuf {
358    session_dir(storage_root, id).join("chat.wal")
359}
360
361fn q42_path(storage_root: &Path, id: &str) -> PathBuf {
362    session_dir(storage_root, id).join("chat.q42")
363}
364
365fn last_session_prefs_path() -> PathBuf {
366    crate::state::app_meta_dir().join("chat_prefs.json")
367}
368
369fn unix_now() -> u64 {
370    std::time::SystemTime::now()
371        .duration_since(std::time::UNIX_EPOCH)
372        .unwrap_or_default()
373        .as_secs()
374}
375
376fn new_session_id() -> String {
377    let ts = unix_now();
378    let rnd: u64 = rand::random();
379    format!("{ts}-{rnd:016x}")
380}
381
382fn session_subject_hash(session_id: &str) -> u64 {
383    q_hash(&format!("chat:session:{session_id}"))
384}
385
386fn message_object_hash(lamport: u64) -> u64 {
387    q_hash(&format!("msg:{lamport}")) & OBJECT_HASH_MASK
388}
389
390fn role_context_hash(role: Role) -> u64 {
391    q_hash(&format!("chat:role:{}", role.as_str()))
392}
393
394fn build_message_quin(session_id: &str, role: Role, lamport: u64, content_hash: u64) -> NQuin {
395    let subject = session_subject_hash(session_id);
396    let predicate = q_hash("chat:hasMessage");
397    let object = message_object_hash(lamport);
398    let context = role_context_hash(role);
399    let metadata = (lamport & LAMPORT_MASK) << LAMPORT_SHIFT | (content_hash & 0xFFFF_FFFF);
400    let parity = subject ^ predicate ^ object ^ context ^ metadata;
401    NQuin {
402        subject,
403        predicate,
404        object,
405        context,
406        metadata,
407        parity,
408    }
409}
410
411fn write_quins_to_q42(quins: &[NQuin], out_path: &Path) -> Result<u64, ChatError> {
412    let count = qualia_core_db::q42_volume::write_sorted_quins_volume(out_path, quins)?;
413    Ok(count as u64)
414}
415
416/// Gets last-session-id.
417pub fn get_last_session_id() -> Option<String> {
418    let path = last_session_prefs_path();
419    let text = fs::read_to_string(path).ok()?;
420    let prefs: LastSessionPrefs = serde_json::from_str(&text).ok()?;
421    prefs.last_session_id
422}
423
424/// Sets last-session-id.
425pub fn set_last_session_id(id: &str) -> Result<(), ChatError> {
426    let path = last_session_prefs_path();
427    if let Some(parent) = path.parent() {
428        fs::create_dir_all(parent)?;
429    }
430    let prefs = LastSessionPrefs {
431        last_session_id: Some(id.to_string()),
432    };
433    fs::write(path, serde_json::to_string_pretty(&prefs)?)?;
434    Ok(())
435}
436
437/// Creates session.
438pub fn create_session(
439    storage_root: &Path,
440    title: Option<String>,
441    env: Option<ChatEnvironment>,
442) -> Result<String, ChatError> {
443    fs::create_dir_all(chats_dir(storage_root))?;
444    let id = new_session_id();
445    let dir = session_dir(storage_root, &id);
446    fs::create_dir_all(&dir)?;
447
448    let now = unix_now();
449    let title = title.unwrap_or_else(|| "New chat".to_string());
450    let environment =
451        env.unwrap_or_else(|| ChatEnvironment::default_for_session(&id, storage_root));
452
453    let profile = crate::user_profile::load_profile();
454    let owner_did = profile.public_did.clone();
455
456    let session_did = compile_session_did(&id, SessionKind::Solo);
457    let meta = SessionMeta {
458        id: id.clone(),
459        title: title.clone(),
460        created_at: now,
461        updated_at: now,
462        message_count: 0,
463        next_lamport: 1,
464        environment_ref: "environment.json".to_string(),
465        session_kind: SessionKind::Solo,
466        participants: Vec::new(),
467        owner_did,
468        session_did,
469    };
470
471    fs::write(
472        session_meta_path(storage_root, &id),
473        serde_json::to_string_pretty(&meta)?,
474    )?;
475    fs::write(
476        environment_path(storage_root, &id),
477        serde_json::to_string_pretty(&environment)?,
478    )?;
479    fs::File::create(messages_path(storage_root, &id))?;
480    let _ = WriteAheadLog::open(wal_path(storage_root, &id))
481        .map_err(|e| ChatError::Wal(format!("Cannot create chat.wal: {e}")))?;
482
483    set_last_session_id(&id)?;
484    let _ = crate::chat_agents::ensure_local_agent_config(storage_root, &id);
485    Ok(id)
486}
487
488/// Lists chat sessions.
489pub fn list_sessions(storage_root: &Path) -> Result<Vec<ChatSessionSummary>, ChatError> {
490    let root = chats_dir(storage_root);
491    if !root.is_dir() {
492        return Ok(Vec::new());
493    }
494
495    let mut out = Vec::new();
496    for entry in fs::read_dir(&root)?.filter_map(Result::ok) {
497        if !entry.file_type().map(|t| t.is_dir()).unwrap_or(false) {
498            continue;
499        }
500        let id = entry.file_name().to_string_lossy().into_owned();
501        let meta_path = session_meta_path(storage_root, &id);
502        if !meta_path.is_file() {
503            continue;
504        }
505        let mut meta: SessionMeta = serde_json::from_str(&fs::read_to_string(&meta_path)?)?;
506        persist_session_did_if_needed(storage_root, &mut meta)?;
507        out.push(ChatSessionSummary {
508            id: meta.id,
509            title: meta.title,
510            created_at: meta.created_at,
511            updated_at: meta.updated_at,
512            message_count: meta.message_count,
513            session_kind: meta.session_kind,
514            participant_count: meta.participants.len() as u64,
515            session_did: meta.session_did,
516        });
517    }
518
519    out.sort_by(|a, b| b.updated_at.cmp(&a.updated_at));
520    Ok(out)
521}
522
523fn read_messages_jsonl(path: &Path) -> Result<Vec<ChatMessage>, ChatError> {
524    if !path.is_file() {
525        return Ok(Vec::new());
526    }
527    let file = File::open(path)?;
528    let reader = BufReader::new(file);
529    let mut messages = Vec::new();
530    for line in reader.lines() {
531        let line = line?;
532        if line.trim().is_empty() {
533            continue;
534        }
535        messages.push(serde_json::from_str(&line)?);
536    }
537    Ok(messages)
538}
539
540fn load_environment_or_default(
541    storage_root: &Path,
542    id: &str,
543) -> Result<ChatEnvironment, ChatError> {
544    let env_path = environment_path(storage_root, id);
545    if !env_path.is_file() {
546        return Ok(ChatEnvironment::default_for_session(id, storage_root));
547    }
548
549    let text = fs::read_to_string(&env_path)?;
550    if text.trim().is_empty() {
551        log::warn!(
552            "Chat session {} had an empty environment.json; regenerating default environment",
553            id
554        );
555        let env = ChatEnvironment::default_for_session(id, storage_root);
556        let _ = env.save_to_session_dir(storage_root);
557        return Ok(env);
558    }
559
560    match serde_json::from_str(&text) {
561        Ok(env) => Ok(env),
562        Err(err) => {
563            log::warn!(
564                "Chat session {} had an invalid environment.json ({}); regenerating default environment",
565                id,
566                err
567            );
568            let env = ChatEnvironment::default_for_session(id, storage_root);
569            let _ = env.save_to_session_dir(storage_root);
570            Ok(env)
571        }
572    }
573}
574
575/// Loads session.
576pub fn load_session(storage_root: &Path, id: &str) -> Result<ChatSession, ChatError> {
577    let meta_path = session_meta_path(storage_root, id);
578    if !meta_path.is_file() {
579        return Err(ChatError::NotFound(id.to_string()));
580    }
581    let mut meta: SessionMeta = serde_json::from_str(&fs::read_to_string(&meta_path)?)?;
582    persist_session_did_if_needed(storage_root, &mut meta)?;
583    let environment = load_environment_or_default(storage_root, id)?;
584    let messages = read_messages_jsonl(&messages_path(storage_root, id))?;
585    Ok(ChatSession {
586        meta,
587        environment,
588        messages,
589    })
590}
591
592/// Appends a message.
593pub fn append_message(
594    storage_root: &Path,
595    id: &str,
596    role: Role,
597    content: &str,
598) -> Result<u64, ChatError> {
599    append_message_with_options(storage_root, id, role, content, None, None)
600}
601
602/// Appends a message with options.
603pub fn append_message_with_options(
604    storage_root: &Path,
605    id: &str,
606    role: Role,
607    content: &str,
608    reply_to_fragment: Option<String>,
609    source: Option<String>,
610) -> Result<u64, ChatError> {
611    append_message_with_author(
612        storage_root,
613        id,
614        role,
615        content,
616        reply_to_fragment,
617        source,
618        None,
619        None,
620        None,
621    )
622}
623
624/// Appends a message with an author.
625pub fn append_message_with_author(
626    storage_root: &Path,
627    id: &str,
628    role: Role,
629    content: &str,
630    reply_to_fragment: Option<String>,
631    source: Option<String>,
632    override_author_did: Option<String>,
633    override_author_name: Option<String>,
634    branch_type_override: Option<String>,
635) -> Result<u64, ChatError> {
636    let meta_path = session_meta_path(storage_root, id);
637    if !meta_path.is_file() {
638        return Err(ChatError::NotFound(id.to_string()));
639    }
640
641    let mut meta: SessionMeta = serde_json::from_str(&fs::read_to_string(&meta_path)?)?;
642    let lamport = meta.next_lamport;
643    meta.next_lamport += 1;
644    meta.message_count += 1;
645    meta.updated_at = unix_now();
646
647    let content_hash = content_hash_u64(content);
648    let quin = build_message_quin(id, role, lamport, content_hash);
649
650    let mut wal = WriteAheadLog::open(wal_path(storage_root, id))
651        .map_err(|e| ChatError::Wal(format!("Cannot open chat.wal: {e}")))?;
652    wal.append_mutation(&quin)
653        .map_err(|e| ChatError::Wal(format!("append failed: {e}")))?;
654
655    let (author_did, author_name) =
656        if override_author_did.is_some() || override_author_name.is_some() {
657            (override_author_did, override_author_name)
658        } else if meta.session_kind == SessionKind::Group && role == Role::User {
659            let profile = crate::user_profile::load_profile();
660            (
661                Some(profile.public_did),
662                profile
663                    .sharing
664                    .share_display_name
665                    .then(|| profile.display_name),
666            )
667        } else {
668            (None, None)
669        };
670
671    let relay_ingest = source.as_ref().is_some_and(|s| s.starts_with("relay:"));
672
673    let mut msg = ChatMessage {
674        lamport,
675        role,
676        content: content.to_string(),
677        timestamp: meta.updated_at,
678        content_hash,
679        author_did,
680        author_name,
681        reply_to_fragment: reply_to_fragment.clone(),
682        source,
683        sub_agent_of: None,
684        agent_did: None,
685        model_id: None,
686        agent_backend: None,
687        outcome_sharing: None,
688    };
689
690    if role == Role::Agent && !relay_ingest {
691        let _ = crate::chat_agents::decorate_local_agent_message(storage_root, id, &mut msg);
692    }
693
694    let mut jsonl = OpenOptions::new()
695        .create(true)
696        .append(true)
697        .open(messages_path(storage_root, id))?;
698    writeln!(jsonl, "{}", serde_json::to_string(&msg)?)?;
699
700    fs::write(meta_path, serde_json::to_string_pretty(&meta)?)?;
701
702    if let Some(parent_id) = reply_to_fragment.as_deref() {
703        let graph = crate::chat_graph::load_graph(storage_root, id).ok();
704        let anchor = graph
705            .as_ref()
706            .and_then(|g| g.fragments.iter().find(|f| f.fragment_id == parent_id))
707            .map(|f| f.anchor_text.as_str());
708        let _ = crate::chat_graph::link_reply_to_fragment(
709            storage_root,
710            id,
711            parent_id,
712            lamport,
713            None,
714            anchor,
715            Some(content),
716            branch_type_override.as_deref(),
717        );
718    }
719
720    if meta.session_kind == SessionKind::Group && !relay_ingest {
721        if role != Role::Agent
722            || crate::chat_agents::can_relay_agent_outcome(&msg, &meta.participants)
723        {
724            let _ = crate::chat_relay::publish_session_message(storage_root, id, lamport);
725        }
726    }
727
728    set_last_session_id(id)?;
729    Ok(lamport)
730}
731
732/// Ingest a relayed message with pre-set sub-agent metadata (skips local decoration / re-publish).
733pub fn append_relay_message_with_agent_meta(
734    storage_root: &Path,
735    id: &str,
736    role: Role,
737    content: &str,
738    reply_to_fragment: Option<String>,
739    source: Option<String>,
740    author_did: Option<String>,
741    author_name: Option<String>,
742    sub_agent_of: Option<String>,
743    agent_did: Option<String>,
744    model_id: Option<String>,
745    agent_backend: Option<String>,
746    outcome_sharing: Option<crate::chat_agents::OutcomeSharingPolicy>,
747) -> Result<u64, ChatError> {
748    let meta_path = session_meta_path(storage_root, id);
749    if !meta_path.is_file() {
750        return Err(ChatError::NotFound(id.to_string()));
751    }
752
753    let mut meta: SessionMeta = serde_json::from_str(&fs::read_to_string(&meta_path)?)?;
754    let lamport = meta.next_lamport;
755    meta.next_lamport += 1;
756    meta.message_count += 1;
757    meta.updated_at = unix_now();
758
759    let content_hash = content_hash_u64(content);
760    let quin = build_message_quin(id, role, lamport, content_hash);
761
762    let mut wal = WriteAheadLog::open(wal_path(storage_root, id))
763        .map_err(|e| ChatError::Wal(format!("Cannot open chat.wal: {e}")))?;
764    wal.append_mutation(&quin)
765        .map_err(|e| ChatError::Wal(format!("append failed: {e}")))?;
766
767    let msg = ChatMessage {
768        lamport,
769        role,
770        content: content.to_string(),
771        timestamp: meta.updated_at,
772        content_hash,
773        author_did,
774        author_name,
775        reply_to_fragment,
776        source,
777        sub_agent_of,
778        agent_did,
779        model_id,
780        agent_backend,
781        outcome_sharing,
782    };
783
784    let mut jsonl = OpenOptions::new()
785        .create(true)
786        .append(true)
787        .open(messages_path(storage_root, id))?;
788    writeln!(jsonl, "{}", serde_json::to_string(&msg)?)?;
789    fs::write(meta_path, serde_json::to_string_pretty(&meta)?)?;
790    set_last_session_id(id)?;
791    Ok(lamport)
792}
793
794/// Compacts a session to q42.
795pub fn compact_session_to_q42(storage_root: &Path, id: &str) -> Result<PathBuf, ChatError> {
796    let dir = session_dir(storage_root, id);
797    if !dir.is_dir() {
798        return Err(ChatError::NotFound(id.to_string()));
799    }
800
801    let wal_file = wal_path(storage_root, id);
802    let mut wal = WriteAheadLog::open(&wal_file)
803        .map_err(|e| ChatError::Wal(format!("Cannot open chat.wal: {e}")))?;
804    let quins = wal
805        .recover()
806        .map_err(|e| ChatError::Compact(format!("WAL recover failed: {e}")))?;
807
808    if quins.is_empty() {
809        return Err(ChatError::Compact("No quins in session WAL".to_string()));
810    }
811
812    let out = q42_path(storage_root, id);
813    let count = write_quins_to_q42(&quins, &out)?;
814    if count == 0 {
815        return Err(ChatError::Compact("Wrote zero quins".to_string()));
816    }
817    Ok(out)
818}
819
820/// Deletes a session.
821pub fn delete_session(storage_root: &Path, id: &str) -> Result<(), ChatError> {
822    let dir = session_dir(storage_root, id);
823    if !dir.is_dir() {
824        return Err(ChatError::NotFound(id.to_string()));
825    }
826    fs::remove_dir_all(&dir)?;
827
828    if get_last_session_id().as_deref() == Some(id) {
829        let path = last_session_prefs_path();
830        let prefs = LastSessionPrefs {
831            last_session_id: None,
832        };
833        let _ = fs::write(path, serde_json::to_string_pretty(&prefs)?);
834    }
835    Ok(())
836}
837
838fn owner_participant(profile: &crate::user_profile::UserProfile) -> ChatParticipant {
839    ChatParticipant {
840        did: profile.public_did.clone(),
841        display_name: profile.display_name.clone(),
842        actor_id: "self".to_string(),
843        role: "owner".to_string(),
844        joined_at: unix_now(),
845    }
846}
847
848fn contacts_for_dids(dids: &[String]) -> Vec<ChatParticipant> {
849    let contacts = crate::social_connect::list_chat_contacts();
850    let now = unix_now();
851    dids.iter()
852        .filter_map(|did| {
853            contacts
854                .iter()
855                .find(|c| c.did == *did)
856                .map(|c| ChatParticipant {
857                    did: c.did.clone(),
858                    display_name: c.display_name.clone(),
859                    actor_id: c.actor_id.clone(),
860                    role: "member".to_string(),
861                    joined_at: now,
862                })
863        })
864        .collect()
865}
866
867fn sync_participants_to_environment(
868    storage_root: &Path,
869    id: &str,
870    meta: &SessionMeta,
871) -> Result<(), ChatError> {
872    let env_path = environment_path(storage_root, id);
873    let mut environment = load_environment_or_default(storage_root, id)?;
874    environment.session_kind = meta.session_kind;
875    environment.participants = meta.participants.clone();
876    fs::write(env_path, serde_json::to_string_pretty(&environment)?)?;
877    Ok(())
878}
879
880/// Creates group-session.
881pub fn create_group_session(
882    storage_root: &Path,
883    title: Option<String>,
884    participant_dids: &[String],
885) -> Result<String, ChatError> {
886    let profile = crate::user_profile::load_profile();
887    if !profile.sharing.allow_group_chat_invites {
888        return Err(ChatError::InvalidSession(
889            "Group chat invites are disabled in your profile.".to_string(),
890        ));
891    }
892
893    let mut participants = vec![owner_participant(&profile)];
894    participants.extend(contacts_for_dids(participant_dids));
895
896    if participants.len() < 2 {
897        return Err(ChatError::InvalidSession(
898            "Select at least one friend to start a group chat.".to_string(),
899        ));
900    }
901
902    fs::create_dir_all(chats_dir(storage_root))?;
903    let id = new_session_id();
904    let dir = session_dir(storage_root, &id);
905    fs::create_dir_all(&dir)?;
906
907    let now = unix_now();
908    let title = title.unwrap_or_else(|| {
909        let names: Vec<_> = participants
910            .iter()
911            .filter(|p| p.role != "owner")
912            .map(|p| p.display_name.as_str())
913            .take(3)
914            .collect();
915        if names.is_empty() {
916            "Group chat".to_string()
917        } else {
918            format!("Group: {}", names.join(", "))
919        }
920    });
921
922    let mut environment = ChatEnvironment::default_for_session(&id, storage_root);
923    environment.session_kind = SessionKind::Group;
924    environment.participants = participants.clone();
925
926    let session_did = compile_session_did(&id, SessionKind::Group);
927    let meta = SessionMeta {
928        id: id.clone(),
929        title: title.clone(),
930        created_at: now,
931        updated_at: now,
932        message_count: 0,
933        next_lamport: 1,
934        environment_ref: "environment.json".to_string(),
935        session_kind: SessionKind::Group,
936        participants,
937        owner_did: profile.public_did,
938        session_did,
939    };
940
941    fs::write(
942        session_meta_path(storage_root, &id),
943        serde_json::to_string_pretty(&meta)?,
944    )?;
945    fs::write(
946        environment_path(storage_root, &id),
947        serde_json::to_string_pretty(&environment)?,
948    )?;
949    fs::File::create(messages_path(storage_root, &id))?;
950    let _ = WriteAheadLog::open(wal_path(storage_root, &id))
951        .map_err(|e| ChatError::Wal(format!("Cannot create chat.wal: {e}")))?;
952
953    set_last_session_id(&id)?;
954    let _ = crate::chat_agents::ensure_local_agent_config(storage_root, &id);
955    Ok(id)
956}
957
958/// Adds participant.
959pub fn add_participant(
960    storage_root: &Path,
961    id: &str,
962    participant_did: &str,
963) -> Result<Vec<ChatParticipant>, ChatError> {
964    let meta_path = session_meta_path(storage_root, id);
965    if !meta_path.is_file() {
966        return Err(ChatError::NotFound(id.to_string()));
967    }
968    let mut meta: SessionMeta = serde_json::from_str(&fs::read_to_string(&meta_path)?)?;
969    if meta.session_kind != SessionKind::Group {
970        meta.session_kind = SessionKind::Group;
971    }
972    if meta.participants.iter().any(|p| p.did == participant_did) {
973        return Ok(meta.participants.clone());
974    }
975
976    let added = contacts_for_dids(&[participant_did.to_string()]);
977    let Some(participant) = added.into_iter().next() else {
978        return Err(ChatError::InvalidSession(format!(
979            "No contact found for DID {participant_did}. Add them via Profile → Add Friend first."
980        )));
981    };
982
983    meta.participants.push(participant);
984    meta.updated_at = unix_now();
985    fs::write(&meta_path, serde_json::to_string_pretty(&meta)?)?;
986    sync_participants_to_environment(storage_root, id, &meta)?;
987    Ok(meta.participants.clone())
988}
989
990/// Removes participant.
991pub fn remove_participant(
992    storage_root: &Path,
993    id: &str,
994    participant_did: &str,
995) -> Result<Vec<ChatParticipant>, ChatError> {
996    let meta_path = session_meta_path(storage_root, id);
997    if !meta_path.is_file() {
998        return Err(ChatError::NotFound(id.to_string()));
999    }
1000    let mut meta: SessionMeta = serde_json::from_str(&fs::read_to_string(&meta_path)?)?;
1001    if meta.owner_did == participant_did {
1002        return Err(ChatError::InvalidSession(
1003            "Cannot remove the session owner.".to_string(),
1004        ));
1005    }
1006    meta.participants.retain(|p| p.did != participant_did);
1007    meta.updated_at = unix_now();
1008    fs::write(&meta_path, serde_json::to_string_pretty(&meta)?)?;
1009    sync_participants_to_environment(storage_root, id, &meta)?;
1010    Ok(meta.participants.clone())
1011}
1012
1013/// Gets participants.
1014pub fn get_participants(storage_root: &Path, id: &str) -> Result<Vec<ChatParticipant>, ChatError> {
1015    let meta_path = session_meta_path(storage_root, id);
1016    if !meta_path.is_file() {
1017        return Err(ChatError::NotFound(id.to_string()));
1018    }
1019    let meta: SessionMeta = serde_json::from_str(&fs::read_to_string(&meta_path)?)?;
1020    Ok(meta.participants.clone())
1021}
1022
1023/// Sessions and groups that can be selected as share targets (each has a stable `session_did`).
1024pub fn list_session_share_targets(
1025    storage_root: &Path,
1026) -> Result<Vec<ChatSessionShareTarget>, ChatError> {
1027    let summaries = list_sessions(storage_root)?;
1028    Ok(summaries
1029        .into_iter()
1030        .map(|s| ChatSessionShareTarget {
1031            session_id: s.id,
1032            session_did: s.session_did,
1033            title: s.title,
1034            session_kind: s.session_kind,
1035            participant_count: s.participant_count,
1036        })
1037        .collect())
1038}
1039
1040/// Gets session-did.
1041pub fn get_session_did(storage_root: &Path, session_id: &str) -> Result<String, ChatError> {
1042    let meta_path = session_meta_path(storage_root, session_id);
1043    if !meta_path.is_file() {
1044        return Err(ChatError::NotFound(session_id.to_string()));
1045    }
1046    let mut meta: SessionMeta = serde_json::from_str(&fs::read_to_string(&meta_path)?)?;
1047    persist_session_did_if_needed(storage_root, &mut meta)?;
1048    Ok(meta.session_did)
1049}
1050
1051/// Renames a session.
1052pub fn rename_session(storage_root: &Path, id: &str, title: &str) -> Result<(), ChatError> {
1053    let meta_path = session_meta_path(storage_root, id);
1054    if !meta_path.is_file() {
1055        return Err(ChatError::NotFound(id.to_string()));
1056    }
1057    let mut meta: SessionMeta = serde_json::from_str(&fs::read_to_string(&meta_path)?)?;
1058    meta.title = title.trim().to_string();
1059    meta.updated_at = unix_now();
1060    fs::write(meta_path, serde_json::to_string_pretty(&meta)?)?;
1061    Ok(())
1062}
1063
1064#[cfg(test)]
1065mod tests {
1066    use super::*;
1067    use std::env;
1068
1069    fn temp_storage() -> PathBuf {
1070        let mut dir = env::temp_dir();
1071        dir.push(format!("qualia-chat-test-{}", rand::random::<u32>()));
1072        dir
1073    }
1074
1075    #[test]
1076    fn create_list_append_load_delete_roundtrip() {
1077        let storage = temp_storage();
1078        let id = create_session(&storage, Some("Test".into()), None).unwrap();
1079        assert_eq!(get_last_session_id().as_deref(), Some(id.as_str()));
1080        let sessions = list_sessions(&storage).unwrap();
1081        assert_eq!(sessions.len(), 1);
1082        assert_eq!(sessions[0].id, id);
1083
1084        let lamport = append_message(&storage, &id, Role::User, "hello").unwrap();
1085        assert_eq!(lamport, 1);
1086        append_message(&storage, &id, Role::Agent, "hi there").unwrap();
1087
1088        let session = load_session(&storage, &id).unwrap();
1089        assert_eq!(session.messages.len(), 2);
1090        assert_eq!(session.messages[0].content, "hello");
1091
1092        let q42 = compact_session_to_q42(&storage, &id).unwrap();
1093        assert!(q42.is_file());
1094        let bytes = fs::read(&q42).unwrap();
1095        assert!(
1096            bytes.starts_with(&qualia_core_db::q42_volume::Q42_MAGIC),
1097            "chat.q42 must be a unified v3 volume"
1098        );
1099        let volume = qualia_core_db::q42_volume::Q42Volume::open(&q42).unwrap();
1100        volume.verify_all_blocks().expect("chat.q42 ECC");
1101        assert_eq!(volume.read_all_quins().unwrap().len(), 2);
1102
1103        delete_session(&storage, &id).unwrap();
1104        assert!(load_session(&storage, &id).is_err());
1105        let _ = fs::remove_dir_all(&storage);
1106    }
1107}