Struct RunStore 

pub struct RunStore { /* private fields */ }

JSONL run-trace store rooted at <car_dir>/runs/.

Stateless across calls — each append opens, writes, and closes the run’s file. Flush points are sparse (turn granularity), so there is no long-lived file handle to manage, and a concurrently-restarting daemon always sees a consistent on-disk tail.

Implementations

impl RunStore

pub fn new(runs_root: PathBuf, retention: RetentionConfig) -> Self

Construct a store rooted at runs_root (the runs/ dir itself). Use RunStore::from_journal_dir from the daemon, which derives the root from the configured journal dir; this constructor is the test/embedder seam.

pub fn from_journal_dir(journal_dir: &Path) -> Self

Derive the store from the daemon’s journal dir. The journal lives at ~/.car/journals, so the run store is its sibling ~/.car/runs; retention is read from ~/.car/config.toml. When the journal dir has no parent (a bare relative path), the store falls back to journal_dir/../runs resolved lexically.

pub fn root(&self) -> &Path

The runs/ tree root.

pub fn append_records( &self, agent_id: &str, run_id: &str, records: &[RunRecord], ) -> Result<()>

Append one or more RunRecords to a run’s file, creating it 0600 on first write. Records are written one JSONL line each, in order.

This is the single low-level flush primitive the wiring calls at each boundary: RunStarted on runs.start, RunTurns as the recorder produces them, and the terminal RunEnded/Incomplete on runs.complete/disconnect.

pub fn write_started(&self, started: &RunStarted) -> Result<()>

Append the RunStarted line + create the run file (runs.start).

pub fn append_turns( &self, agent_id: &str, run_id: &str, turns: &[RunRecord], ) -> Result<()>

Append RunTurn records (the recorder’s per-proposal output).

pub fn write_ended(&self, ended: &RunEnded) -> Result<()>

Append the terminal RunEnded line (runs.complete or the disconnect-Incomplete path).

pub fn get_run_trace(&self, run_id: &str) -> Option<Vec<RunRecord>>

Load a run’s full ordered trace from disk by run_id — the U5 runs.get_trace read path. Works after a restart when memory is empty. Resolves run_id -> agent_id by scanning the tree, then reads the JSONL. A corrupt/partial trailing line is skipped, so the prior valid records still load (never fails the whole run). Returns None when no file exists for the run_id.

pub fn get_run_trace_for( &self, agent_id: &str, run_id: &str, ) -> Option<Vec<RunRecord>>

Load a run’s trace given both keys (cheaper — no tree scan). Used by list_runs internally and available to callers that already know the owning agent.

pub fn list_runs(&self, agent_id: &str) -> Vec<RunSummary>

List an agent’s runs newest-first — the U5 runs.list read path. Each summary is built from the run file’s records (head for RunStarted, tail for the terminal record, count of Turns). Returns an empty Vec for an agent with no runs (the empty-state).

pub fn agent_for_run(&self, run_id: &str) -> Option<String>

Resolve the owning agent_id for a run_id from disk. Mirrors Self::resolve_run_path but returns the agent dir name — U5’s authorization check (KTD10) needs run_id -> agent_id to verify ownership before serving a trace.

pub fn gc(&self) -> usize

Retention GC (R6) — call on daemon boot. Per agent: keep the most recent max_per_agent completed runs and drop any completed run older than max_age_days, whichever is more restrictive. An in-progress run (no terminal record) is NEVER evicted. Returns the number of run files removed.

pub fn adopt_orphans(&self) -> usize

Adopt crash-orphaned runs at boot (FIX 4). A daemon crash mid-run leaves an on-disk run with RunStarted (+ Turns) but no terminal RunEnded, so it reads InProgress forever and the GC — which never evicts an in-progress run — can never reclaim it. The file leaks across every crash.

This runs at store construction/boot, BEFORE gc(). At that moment the in-memory runs map is always empty, so any run that is InProgress on disk cannot have a live harness writing to it — it is necessarily a crashed prior process. We append an Incomplete terminal RunEnded marker to adopt it, making it terminal and thus age-GC-eligible (so a later gc() in the same boot can reclaim it).

Returns the number of runs adopted. Best-effort: an unwritable file is skipped rather than failing startup.

Trait Implementations

impl Clone for RunStore

fn clone(&self) -> RunStore

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for RunStore

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

Formats the value using the given formatter.