Struct Journal 

pub struct Journal { /* private fields */ }

Implementations

impl Journal

pub fn open(path: &Path) -> Result<Self, JournalError>

pub fn begin_session( &self, id: &str, harness: &str, cwd: &str, ) -> Result<(), JournalError>

pub fn start_action( &self, new: &NewAction<'_>, ) -> Result<ActionId, JournalError>

Record a new action as pending. Any older still-pending action in the same session is closed as abandoned — its post event will never come (captured contract: failures emit no PostToolUse).

pub fn complete_by_tool_use( &self, session_id: &str, tool_use_id: &str, duration_ms: i64, ) -> Result<ActionId, JournalError>

Close a pending action via its pre/post correlation key. Also accepts an abandoned action: with interleaved or background tool calls a post can arrive after the next action’s start already abandoned its pre — the late post is ground truth and wins over our guess.

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

pub fn attach_manifest( &self, action: ActionId, manifest: &Manifest, role: ManifestRole, ) -> Result<(), JournalError>

pub fn manifests(&self, action: ActionId) -> Result<Vec<Manifest>, JournalError>

All manifests of an action, regardless of role.

pub fn manifests_by_role( &self, action: ActionId, role: ManifestRole, ) -> Result<Vec<Manifest>, JournalError>

Manifests of an action filtered by role (pre = undo side, post = redo side / conflict oracle).

pub fn latest_undoable(&self) -> Result<Option<ActionRecord>, JournalError>

Newest command-kind action that is plausibly undoable: completed or abandoned, with at least one pre-manifest. Searches across sessions.

pub fn recent_actions( &self, limit: i64, ) -> Result<Vec<ActionRecord>, JournalError>

Most recent actions across all sessions, newest first (for log).

pub fn latest_redoable(&self) -> Result<Option<ActionRecord>, JournalError>

Newest live undo action (redo target): kind undo, still completed.

pub fn record_undo( &self, session_id: &str, target: ActionId, ) -> Result<ActionId, JournalError>

Record an undo of target as a new journaled action. The target flips to undone, remembering its prior status on the undo row; undoing an undo restores that recorded status to the original — redo without fabricating history. The status check runs INSIDE the transaction, so racing double-undos admit exactly one winner, and an already-undone target is refused (redo targets the undo action, not the original).

Chains are bounded by design: undoable targets are command actions and first-level undos (redo). Undoing a redo is refused with a pointer to the original — the same capability with a trivially-consistent state machine instead of recursive status cascades (audit round 4). The exhaustive small-model test in T4 checks every sequence to depth 4 against a reference implementation of these rules.

pub fn add_note(&self, action: ActionId, note: &str) -> Result<(), JournalError>

Append a note line to an action (used for loud protection-gap records: truncated snapshots, per-path failures).

pub fn set_pinned( &self, action: ActionId, pinned: bool, ) -> Result<(), JournalError>

pub fn live_hashes( &self, retain_after_ms: i64, ) -> Result<BTreeSet<String>, JournalError>

Store hashes that GC must keep: referenced by a pinned action, by any action started at/after retain_after_ms, or by an action that a live (pinned/recent) undo targets — a kept chain row must keep its objects, or redo would fail on a journal entry that still exists.

pub fn action(&self, id: ActionId) -> Result<ActionRecord, JournalError>

pub fn session_actions( &self, session_id: &str, ) -> Result<Vec<ActionRecord>, JournalError>

pub fn max_started_at(&self) -> Result<Option<i64>, JournalError>

Newest action timestamp in the journal — the reference point for retention cutoffs. NEVER use the wall clock for that (CLAUDE.md: a backward NTP jump would make recent snapshots look collectable).

pub fn prune_before( &self, cutoff_ms: i64, dry_run: bool, ) -> Result<(u64, u64), JournalError>

Prune journal rows older than cutoff_ms. Never touches pinned rows, pending rows, or rows referenced as an undo target by a surviving row (chain integrity; the referencing row’s own pruning frees them for the NEXT pass — eventual cleanup). Old raw_command strings may embed secrets, which is why pruning rows (not just store objects) matters. Returns (actions_pruned, sessions_pruned); dry_run only counts.

pub fn oldest_evictable_batch_end( &self, batch: u32, before_ms: i64, ) -> Result<Option<i64>, JournalError>

The started_at_ms of the last row in the next oldest-first batch of evictable actions strictly before before_ms (size-cap eviction, D2). Evictable = the same condition prune_before deletes by: unpinned, non-pending, not referenced by an undo. None = nothing left to evict below the ceiling — the caller must stop and report, never force.

pub fn set_started_at_for_test( &self, action: ActionId, at_ms: i64, ) -> Result<(), JournalError>

Test support: rewrite an action’s timestamp so retention tests can construct explicit timelines. Not part of the product surface.

pub fn set_session_started_at_for_test( &self, session_id: &str, at_ms: i64, ) -> Result<(), JournalError>

Test support: backdate a session’s start so retention tests can build explicit timelines. Not part of the product surface.

pub fn stats(&self) -> Result<(u64, Vec<(String, u64)>), JournalError>

(sessions, per-status action counts) for status/doctor.

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