Struct JournalStore 

pub struct JournalStore { /* private fields */ }

JournalStore wraps RunStore with replay semantics.

Thread safety: All public methods take &self (interior mutability via RwLock). The underlying checkpoint data is protected by a single writer lock.

Usage lifecycle: new() → init_run() → cache_agent()* → flush() 或: open() → has_completed()/get_cached() → workflow resume logic

Implementations

impl JournalStore

pub fn new(run_dir: &Path) -> Result<Self, JournalError>

Create a new journal store at the given directory. Initializes the underlying RunStore and creates an empty cache index.

pub fn with_event_sender(self, tx: EventSender) -> Self

Attach an event sender for broadcasting journal updates.

pub fn init_run(&self, run_id: RunId, task: &str) -> Result<(), JournalError>

Initialize a new run in the journal.

pub fn init_run_with_meta( &self, run_id: RunId, task: &str, workflow_meta: Value, ) -> Result<(), JournalError>

Initialize a new run with declarative workflow metadata.

pub fn open(&self, run_id: RunId) -> Result<RunCheckpoint, JournalError>

Open an existing run and rebuild the cache index from persisted data.

This is the entry point for --resume. It:

1. Loads the checkpoint from disk
2. Rebuilds the in-memory cache_index from agent_results
3. Returns the checkpoint for the caller to inspect

pub fn cache_agent( &self, cache_key: &AgentCacheKey, agent_id: AgentId, phase_id: PhaseId, status: AgentStatus, output: Value, findings: Vec<Finding>, tokens: TokenUsage, ) -> Result<AgentCacheKey, JournalError>

Cache an agent’s result in the journal.

Called by the scheduler after an agent completes successfully or fails with a non-retryable error. The result is persisted to disk immediately (via append_event → update_from_event → write_checkpoint_to_disk).

pub fn record_result( &self, cache_key: &AgentCacheKey, agent_id: AgentId, phase_id: PhaseId, status: AgentStatus, output: Value, findings: Vec<Finding>, tokens: TokenUsage, )

Record an agent’s output for resume replay, keyed by cache_key.

Unlike [cache_agent], this does not append an AgentDone event, so it never double-counts tokens against the event-driven checkpoint totals. It only upserts the checkpoint entry (preserving cache_key_hash and the structured output) and refreshes the in-memory cache index. Called by the Lua SDK after an agent completes during a live run.

pub fn store(&self) -> Arc<RunStore>

Access the underlying run store (shared persistence engine). Allows the CLI to route the scheduler event stream through the same RunStore instance the journal uses, avoiding split-brain checkpoints.

pub fn append_event(&self, event: &AgentEvent) -> Result<(), JournalError>

Append an event to the underlying run store (event log + checkpoint).

pub fn has_completed(&self, cache_key: &AgentCacheKey) -> bool

Check if an agent with the given cache key has already completed. Used by the Lua SDK’s agent() function before submitting to the scheduler.

pub fn get_cached(&self, cache_key: &AgentCacheKey) -> Option<AgentResultCache>

Get cached result for an agent. Returns None if the agent hasn’t completed yet.

pub fn completed_keys(&self) -> Vec<AgentCacheKey>

Get list of all completed agent cache keys. Useful for debugging and progress reporting.

pub fn get_checkpoint(&self) -> Option<RunCheckpoint>

Get the underlying checkpoint (read-only snapshot).

pub fn flush(&self) -> Result<(), JournalError>

Flush all pending data to disk.

pub fn cancel(&self) -> Result<(), JournalError>

Mark the run as cancelled.

Trait Implementations

impl Debug for JournalStore

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl JournalCallback for JournalStore

fn on_agent_done<'life0, 'async_trait>( &'life0 self, agent_id: AgentId, phase_id: PhaseId, status: AgentStatus, output: Value, tokens: TokenUsage, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Called when an agent completes (success or non-retryable failure).