mj_core/
storage.rs

1//! Data exchanged with the controller store, independent of its SQLite implementation.
2use crate::elicitation::ElicitationRequest;
3use crate::state::*;
4use crate::usage::ProviderCost;
5use serde::{Deserialize, Serialize};
6use std::collections::BTreeMap;
7use std::sync::Arc;
8/// A deterministic projection integrity violation. Retrying cannot fix it, so
9/// callers must report it separately from transport failures.
10#[derive(Debug)]
11pub struct ProjectionIntegrityError(pub String);
12
13impl std::fmt::Display for ProjectionIntegrityError {
14    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
15        formatter.write_str(&self.0)
16    }
17}
18
19impl std::error::Error for ProjectionIntegrityError {}
20
21/// A store this build cannot safely read and write.
22///
23/// Carried as a typed cause rather than a message so the daemon can tell a
24/// store that moved underneath it from a transport failure. It survives every
25/// `anyhow` hop to the caller, which finds it with `error.chain()`.
26#[derive(Debug, Clone, Copy, PartialEq, Eq)]
27pub struct StoreSchemaMismatch {
28    pub found: i64,
29    pub supported: i64,
30    pub reason: StoreSchemaMismatchReason,
31}
32
33#[derive(Debug, Clone, Copy, PartialEq, Eq)]
34pub enum StoreSchemaMismatchReason {
35    NeedsMigration,
36    Incompatible { minimum_compatible: i64 },
37    InvalidCompatibilityMetadata,
38    Rollback { previous: i64 },
39}
40
41impl std::fmt::Display for StoreSchemaMismatch {
42    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
43        let Self {
44            found,
45            supported,
46            reason,
47        } = self;
48        match reason {
49            StoreSchemaMismatchReason::Incompatible { minimum_compatible } => write!(
50                formatter,
51                "Mjolnir database schema {found} requires at least build schema {minimum_compatible} for reads and writes; this build supports {supported}; upgrade Mjolnir, run this build with an isolated data directory (--instance NAME or MJ_DATA_DIR), or restore a backup made by the older build"
52            ),
53            StoreSchemaMismatchReason::NeedsMigration => write!(
54                formatter,
55                "Mjolnir database schema {found} is not the supported schema {supported}; start the Mjolnir daemon to migrate it"
56            ),
57            StoreSchemaMismatchReason::InvalidCompatibilityMetadata => write!(
58                formatter,
59                "Mjolnir database schema {found} has missing or invalid compatibility metadata; refusing access from build schema {supported}"
60            ),
61            StoreSchemaMismatchReason::Rollback { previous } => write!(
62                formatter,
63                "Mjolnir database schema rolled back from {previous} to {found} underneath this writer; refusing writes from build schema {supported}"
64            ),
65        }
66    }
67}
68
69impl std::error::Error for StoreSchemaMismatch {}
70
71#[derive(Debug, Clone, Copy, PartialEq, Eq)]
72pub enum HistoryScope {
73    Project,
74    Session,
75    All,
76}
77
78#[derive(Debug, Clone, PartialEq, Eq)]
79pub struct PromptHistoryEntry {
80    pub id: i64,
81    pub session_id: String,
82    pub text: String,
83}
84
85#[derive(Debug, Clone, Copy, PartialEq, Eq)]
86pub enum ProjectionApplyOutcome {
87    Applied,
88    AlreadyApplied,
89}
90
91#[derive(Debug, Clone, PartialEq)]
92pub enum TranscriptMutation {
93    Upsert(TranscriptItem),
94    Remove { stable_id: String },
95}
96
97/// Changes derived from one relay event. `None` leaves a scalar untouched;
98/// the nested option on `session_title` permits explicitly clearing it.
99#[derive(Debug, Clone, PartialEq, Default)]
100pub struct MaterializedSessionMutation {
101    pub native_agent: Option<crate::relay::RelayEvent>,
102    /// Relay receipt time for this event. Persistence and the actor cache both
103    /// take a monotonic maximum so removing detail rows cannot move activity
104    /// backwards.
105    pub last_activity_at_ms: Option<i64>,
106    pub execution: Option<MaterializedExecutionState>,
107    pub session_title: Option<Option<String>>,
108    pub configuration: Option<BTreeMap<String, serde_json::Value>>,
109    pub transcript: Vec<TranscriptMutation>,
110    pub queued_prompts: Option<Vec<MaterializedQueuedPrompt>>,
111    pub pending_elicitations: Option<Vec<crate::elicitation::ElicitationRequest>>,
112    /// The nested option distinguishes "unchanged" from "cleared", which is
113    /// how a completed turn removes the running turn.
114    pub active_turn: Option<Option<MaterializedTurn>>,
115    /// Explicit context resets retire the last turn without deleting its history.
116    pub clear_turn_outcome: bool,
117    pub last_turn_outcome: Option<MaterializedTurnOutcome>,
118    pub config_results: Vec<(String, Option<String>)>,
119    pub provider_cost: Option<crate::usage::ProviderCost>,
120    pub api_events: Vec<ApiEventData>,
121}
122
123/// One viewer's stored state for one session.
124#[derive(Debug, Clone, Default, PartialEq, Eq)]
125pub struct ClientSessionState {
126    pub draft: String,
127    pub through_event_ordinal: u64,
128}
129
130/// A terminal's current composer and the shared value it originally inherited.
131/// The inherited value is retired on detach, never replaced by client-local text.
132#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
133pub struct DetachedSessionDraft {
134    pub text: String,
135    pub inherited_input: Option<String>,
136}
137
138/// What one turn produced, without loading the transcript around it.
139#[derive(Debug, Clone, PartialEq, Eq)]
140pub struct TurnSummary {
141    /// One-based count of turn starts up to and including this one, which is
142    /// what a caller means by "turn 3 of this session".
143    pub turn_number: u64,
144    pub turn_started_at_ms: i64,
145    /// Newest change at or after the turn start, so the caller can measure how
146    /// long the turn took.
147    pub last_changed_at_ms: i64,
148    /// The last nonempty agent message the turn produced, flattened to text.
149    pub final_message: Option<String>,
150}
151
152/// One page of a session's transcript, ordered by the sequence a reader pages
153/// by rather than by creation order.
154#[derive(Debug, Clone)]
155pub struct TranscriptPage {
156    pub items: Vec<Arc<TranscriptItem>>,
157    /// The newest sequence in the whole transcript, so a caller can tell
158    /// whether this page reached the end without asking for another one.
159    pub latest_seq: u64,
160    pub next_after_seq: u64,
161    pub execution: MaterializedExecutionState,
162}
163
164/// What one retention pass reclaimed.
165#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
166pub struct TranscriptRetention {
167    pub items: usize,
168    pub bytes: usize,
169    /// Rows this pass left for the next one, because of
170    /// `RETENTION_BATCH_ITEMS`.
171    pub remaining: bool,
172}
173
174/// A second-opinion review that was still open when the UI last stopped.
175#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
176pub struct StoredReview {
177    pub workflow: crate::second_opinion::ReviewWorkflow,
178    /// Reviewer lifetime this review belongs to. It is bumped when native
179    /// continuity is lost, so a resumed session starts a new conversation
180    /// rather than pretending to reload one that is gone.
181    pub generation: u64,
182    /// The primary's transcript frontier when the context request went out.
183    pub context_baseline: u64,
184    /// Whether the reviewer's native session is known to be gone.
185    pub native_lost: bool,
186    /// What the controller has read of the reviewer's conversation. The
187    /// reviewer's own journal is the source, but it dies with the target, so
188    /// this copy is what keeps a finished review readable afterwards.
189    pub reviewer_transcript: Vec<std::sync::Arc<crate::state::TranscriptItem>>,
190}
191
192/// How far this session has been reviewed.
193///
194/// `baselines` are Git tree ids by repository root: the working tree as of the
195/// last completed review. They advance only when a review resolves, which is
196/// what makes a cancelled review lossless -- the next one covers both turns.
197#[derive(Debug, Clone, Default, PartialEq, serde::Serialize, serde::Deserialize)]
198pub struct TurnReviewState {
199    pub baselines: std::collections::BTreeMap<std::path::PathBuf, String>,
200    pub reviewed_through_ordinal: u64,
201    /// The last forwarded verdict, which turns the next review into a
202    /// verification pass. Cleared once that pass consumes it.
203    pub prior_review: Option<crate::review::lanes::PriorReviewContext>,
204    /// A review that was running when the daemon stopped. On recovery it is
205    /// cleared without advancing the baseline.
206    pub active: Option<String>,
207    /// A corrective prompt that was submitted while its relay acceptance was
208    /// still ambiguous. It survives a daemon restart so the exact command can
209    /// be retried and reconciled without losing the findings.
210    #[serde(default)]
211    pub pending_forward: Option<crate::review::driver::PendingForward>,
212}
213
214/// What a bounded prompt search found, and whether it stopped early.
215///
216/// The flag is not decoration. Without it a caller cannot tell twenty matches
217/// from the first twenty of many, and will present a partial answer as a whole
218/// one.
219#[derive(Debug, Clone, PartialEq, Eq)]
220pub struct BoundedPromptHistory {
221    pub entries: Vec<PromptHistoryEntry>,
222    pub truncated: bool,
223}
224
225#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
226pub struct UsageCoverage {
227    pub recorded_turns: u64,
228    pub full_turn_reports: u64,
229    pub last_request_reports: u64,
230    pub unspecified_reports: u64,
231    pub missing_reports: u64,
232}
233
234#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
235pub struct UsageCounterTotal {
236    pub tokens: u64,
237    /// Number of full-turn reports supplying this particular counter.
238    pub reported_turns: u64,
239}
240
241#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
242pub struct UsagePage {
243    pub session_id: String,
244    pub turns: Vec<MaterializedTurnOutcome>,
245    pub next_after_seq: u64,
246    pub latest_seq: u64,
247    /// Totals include only reports whose scope is known to be a whole turn.
248    pub totals: BTreeMap<String, UsageCounterTotal>,
249    pub coverage: UsageCoverage,
250    #[serde(default, skip_serializing_if = "Option::is_none")]
251    pub provider_session_cost: Option<ProviderCost>,
252}
253
254#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
255pub struct ApiEvent {
256    pub seq: u64,
257    pub session_id: String,
258    pub recorded_at_ms: i64,
259    #[serde(flatten)]
260    pub event: ApiEventData,
261}
262
263#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
264#[serde(tag = "type", content = "data", rename_all = "snake_case")]
265pub enum ApiEventData {
266    TurnStarted {
267        turn: MaterializedTurn,
268    },
269    TurnEnded {
270        turn: MaterializedTurnOutcome,
271    },
272    Error {
273        message: String,
274        command_id: Option<String>,
275    },
276    InputRequired {
277        /// Absent when a completed turn asks for unstructured user input.
278        #[serde(default, skip_serializing_if = "Option::is_none")]
279        request: Option<ElicitationRequest>,
280        turn_id: Option<u64>,
281    },
282    InputResolved {
283        elicitation_id: String,
284        turn_id: Option<u64>,
285        action: String,
286    },
287    ActivityChanged {
288        activity: ApiActivityState,
289    },
290}
291
292impl ApiEventData {
293    pub fn kind(&self) -> &'static str {
294        match self {
295            Self::TurnStarted { .. } => "turn_started",
296            Self::TurnEnded { .. } => "turn_ended",
297            Self::Error { .. } => "error",
298            Self::InputRequired { .. } => "input_required",
299            Self::InputResolved { .. } => "input_resolved",
300            Self::ActivityChanged { .. } => "activity_changed",
301        }
302    }
303}
304
305/// These are the same structured facts rendered by the web and terminal UIs.
306#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
307pub struct ApiActivityState {
308    pub state: String,
309    pub details: Option<ApiActivityDetails>,
310    pub is_idle: bool,
311    pub waiting_for_input: bool,
312    pub capacity_retry: bool,
313}
314
315#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
316#[serde(deny_unknown_fields)]
317pub struct ApiActivityDetails {
318    pub kind: ApiActivityKind,
319    #[serde(default, skip_serializing_if = "Option::is_none")]
320    pub turn_started_at_ms: Option<i64>,
321    #[serde(default, skip_serializing_if = "Option::is_none")]
322    pub step_started_at_ms: Option<i64>,
323    #[serde(default, skip_serializing_if = "Option::is_none")]
324    pub background_started_at_ms: Option<i64>,
325    #[serde(default, skip_serializing_if = "Option::is_none")]
326    pub idle_since_ms: Option<i64>,
327    /// When anything last arrived from the harness, while a turn or a tool is
328    /// in flight. A surface subtracts it from the current time to show how
329    /// long a running session has been quiet. Mjolnir never ends a turn for
330    /// this on its own; see `mj_core::activity::silence_note`.
331    #[serde(default, skip_serializing_if = "Option::is_none")]
332    pub last_activity_at_ms: Option<i64>,
333    #[serde(default, skip_serializing_if = "Option::is_none")]
334    pub label: Option<String>,
335}
336
337#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
338#[serde(rename_all = "lowercase")]
339pub enum ApiActivityKind {
340    Turn,
341    Step,
342    Background,
343    Idle,
344    Lifecycle,
345}
346
347#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
348pub struct ApiEventFilter {
349    pub session_id: Option<String>,
350    pub workspace_id: Option<String>,
351}
352
353#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
354pub struct ApiEventPage {
355    pub events: Vec<ApiEvent>,
356    pub next_after_seq: u64,
357    pub latest_seq: u64,
358}
mj_core/storage.rs

mj_core/
storage.rs
