Struct ConversationManager 

pub struct ConversationManager { /* private fields */ }

Manages conversation persistence for a project

Implementations

impl ConversationManager

pub fn new(project_dir: impl AsRef<Path>) -> Result<Self>

Create a new conversation manager for a project directory

Errors

Creating .mermaid/conversations under project_dir — a read-only or unwritable project. It is created here, so the later load and list paths can treat an unreadable directory as “no conversations” rather than a failure.

pub fn append_session_events( &self, snapshot: &ConversationHistory, events: &[SessionEvent], ) -> Result<()>

Append session events for snapshot to its .jsonl log, creating the log (with a backfill from the snapshot) on first touch. Called by the persistence chain BEFORE the snapshot rewrite, so the history lands before the file it explains is overwritten.

Errors

An id that would escape the conversations dir, and the append I/O itself. The caller treats a failure as a warning: the snapshot save must still run, and the log self-heals on the next save.

pub fn event_log_path(&self, id: &str) -> PathBuf

Where a session’s event log lives. The compaction bookkeeping row records this instead of a per-compaction archive file: the dropped messages are the log’s earlier message events.

pub fn read_session_events(&self, id: &str) -> Result<Option<Vec<SessionEvent>>>

Read a session’s log as EVENTS rather than folding it into a conversation — for readers that want the history in the order it happened instead of the state it produced.

The daemon’s subscribe_task catch-up is that reader: a mid-run attach replays these onto the RunEvent wire so a subscriber joining at minute nine learns what the first nine produced. Ok(None) when there is no readable log; a torn tail yields the prefix, exactly as a fold does.

Errors

An id that would escape the conversations dir, and read I/O on the log file. A log that is absent, over the cap, or newer-format is Ok(None), not an error.

pub fn fold_conversation_from_log( &self, id: &str, ) -> Result<Option<ConversationHistory>>

Rebuild a conversation from its event log — the recovery source when the snapshot is missing or will not parse. Ok(None) when there is no (foldable) log.

Errors

An id that would escape the conversations dir, and read I/O on the log file. A log that is absent, capped, newer-format, or headerless is Ok(None), not an error.

pub fn save_conversation( &self, conversation: &ConversationHistory, ) -> Result<()>

Save a conversation to disk

Errors

An id that would escape the conversations dir, serializing the conversation, and the atomic 0600 write. Two cases that look like failures are Ok: a message-less conversation is deliberately not persisted, and a concurrent writer detected through the (mtime, len) baseline diverts this copy to a .conflict sibling and warns instead of overwriting. The .meta sidecar is best-effort and never fails the save.

pub fn load_conversation(&self, id: &str) -> Result<ConversationHistory>

Load a specific conversation by ID

Errors

An id that would escape the conversations dir, a file that is missing, unreadable, or past the size cap, JSON that does not parse, and a parsed id that would itself traverse — checked separately, because that field is on-disk state that drives later saves.

pub fn load_last_conversation(&self) -> Result<Option<ConversationHistory>>

Load the most recent valid conversation.

Iterates files newest-first by mtime and returns the first that reads, parses, and has a valid id — skipping (with a warning) any unreadable, unparseable, or traversing-id file. Mirrors list_conversations’s tolerance so one corrupt/partial file (e.g. a crash mid-write) can’t make --continue hard-fail; it falls back to the next-newest valid conversation.

Errors

In practice none: an unreadable conversations dir and every unreadable, oversized, unparseable, or traversing-id file are skipped with a warning, and running out of candidates is Ok(None). The Result is kept for callers that already handle one and so this can grow a real failure later.

pub fn list_conversations(&self) -> Result<Vec<ConversationHistory>>

List all conversations in the project

Errors

In practice none, and deliberately: an unreadable directory yields an empty list, and any file that will not read or parse is skipped, so one corrupt transcript cannot empty the picker.

pub fn list_conversation_metas(&self) -> Result<Vec<ConversationMeta>>

Fast session list: read each <id>.meta sidecar; for a session that lacks a (valid) one — older, or written by a pre-sidecar build — fall back to fully parsing its <id>.json. Message-less sessions are skipped. Newest-first. Cheaper than Self::list_conversations for display-only paths.

Errors

In practice none, matching Self::list_conversations: an unreadable directory yields an empty list, and a sidecar that will not read or parse falls through to parsing its <id>.json, which is itself skipped if that fails too.

pub fn delete_conversation(&self, id: &str) -> Result<()>

Delete a conversation (and its metadata sidecar).

Errors

An id that would escape the conversations dir, and removing the <id>.json itself. An id with no file is Ok, and the .meta sidecar and the session scratch dir are cleaned up best-effort — neither can fail the delete.

pub fn conversations_dir(&self) -> &Path

Get the conversations directory path

Trait Implementations

impl Clone for ConversationManager

fn clone(&self) -> ConversationManager

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.