1use crate::config::{
2 EngineTuningInfo, RecallPlanningProfile, RecallPolicyProfile, RecallScorerKind,
3 RecallScoringProfile,
4};
5use crate::model::{
6 ConflictResolutionKind, ConflictReviewState, EpisodeContinuityState, MemoryQualityState,
7 MemoryRecord, MemoryRecordKind, MemoryScope, MemoryTrustLevel,
8};
9use serde::{Deserialize, Serialize};
10
11#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
12pub enum RecallTemporalOrder {
13 #[default]
14 Relevance,
15 ChronologicalAsc,
16 ChronologicalDesc,
17}
18
19#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
20pub enum RecallHistoricalMode {
21 #[default]
22 CurrentOnly,
23 IncludeHistorical,
24 HistoricalOnly,
25}
26
27#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
28#[serde(default)]
29pub struct RecallFilters {
30 pub kinds: Vec<MemoryRecordKind>,
31 pub required_labels: Vec<String>,
32 pub source: Option<String>,
33 pub from_unix_ms: Option<u64>,
34 pub to_unix_ms: Option<u64>,
35 pub min_importance_score: Option<f32>,
36 pub trust_levels: Vec<MemoryTrustLevel>,
37 pub states: Vec<MemoryQualityState>,
38 pub include_archived: bool,
39 pub episode_id: Option<String>,
40 pub continuity_states: Vec<EpisodeContinuityState>,
41 pub unresolved_only: bool,
42 pub temporal_order: RecallTemporalOrder,
43 pub historical_mode: RecallHistoricalMode,
44 pub lineage_record_id: Option<String>,
45 pub before_record_id: Option<String>,
46 pub after_record_id: Option<String>,
47 pub boundary_labels: Vec<String>,
48 pub recurrence_key: Option<String>,
49 pub conflict_states: Vec<ConflictReviewState>,
50 pub resolution_kinds: Vec<ConflictResolutionKind>,
51 pub unresolved_conflicts_only: bool,
52}
53
54#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
55pub struct RecallQuery {
56 pub scope: MemoryScope,
57 pub query_text: String,
58 pub max_items: usize,
59 pub token_budget: Option<usize>,
60 pub filters: RecallFilters,
61 pub include_explanation: bool,
62}
63
64#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
65pub struct RecallScoreBreakdown {
66 pub lexical: f32,
67 pub semantic: f32,
68 pub graph: f32,
69 pub temporal: f32,
70 pub metadata: f32,
71 pub episodic: f32,
72 pub salience: f32,
73 pub curation: f32,
74 pub policy: f32,
75 pub total: f32,
76}
77
78#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
79pub struct RecallExplanation {
80 pub selected_channels: Vec<String>,
81 pub policy_notes: Vec<String>,
82 pub trace_id: Option<String>,
83 pub planning_trace: Option<RecallPlanningTrace>,
84 pub planning_profile: Option<RecallPlanningProfile>,
85 pub policy_profile: Option<RecallPolicyProfile>,
86 pub scorer_kind: Option<RecallScorerKind>,
87 pub scoring_profile: Option<RecallScoringProfile>,
88}
89
90#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord, Default)]
91pub enum RecallPlannerStage {
92 #[default]
93 CandidateGeneration,
94 GraphExpansion,
95 Selection,
96}
97
98#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, PartialOrd, Ord)]
99pub enum RecallCandidateSource {
100 Lexical,
101 Semantic,
102 Metadata,
103 Episode,
104 Graph,
105 Temporal,
106 Provenance,
107}
108
109#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
110pub struct RecallPlanningTrace {
111 pub trace_id: String,
112 pub token_budget_applied: bool,
113 pub candidates: Vec<RecallTraceCandidate>,
114}
115
116#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
117pub struct RecallTraceCandidate {
118 pub record_id: String,
119 pub kind: MemoryRecordKind,
120 pub selected: bool,
121 pub planner_stage: RecallPlannerStage,
122 pub candidate_sources: Vec<RecallCandidateSource>,
123 pub selection_rank: Option<u32>,
124 pub matched_terms: Vec<String>,
125 pub selected_channels: Vec<String>,
126 pub filter_reasons: Vec<String>,
127 pub decision_reason: String,
128 pub breakdown: RecallScoreBreakdown,
129}
130
131#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
132pub struct RecallHit {
133 pub record: MemoryRecord,
134 pub breakdown: RecallScoreBreakdown,
135 pub explanation: Option<RecallExplanation>,
136}
137
138#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
139pub struct RecallResult {
140 pub hits: Vec<RecallHit>,
141 pub total_candidates_examined: usize,
142 pub explanation: Option<RecallExplanation>,
143}
144
145#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
146pub struct CompactionRequest {
147 pub tenant_id: String,
148 pub namespace: Option<String>,
149 pub dry_run: bool,
150 pub reason: String,
151}
152
153#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
154pub struct CompactionReport {
155 pub deduplicated_records: u64,
156 pub archived_records: u64,
157 pub summarized_clusters: u64,
158 pub pruned_graph_edges: u64,
159 pub superseded_records: u64,
160 pub lineage_links_created: u64,
161 pub dry_run: bool,
162}
163
164#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
165pub struct SnapshotManifest {
166 pub snapshot_id: String,
167 pub created_at_unix_ms: u64,
168 pub namespaces: Vec<String>,
169 pub record_count: u64,
170 pub storage_bytes: u64,
171 pub engine: EngineTuningInfo,
172}
173
174#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
175pub struct StoreStatsRequest {
176 pub tenant_id: Option<String>,
177 pub namespace: Option<String>,
178}
179
180#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
181pub struct NamespaceStats {
182 pub tenant_id: String,
183 pub namespace: String,
184 pub active_records: u64,
185 pub archived_records: u64,
186 pub deleted_records: u64,
187 pub suppressed_records: u64,
188 pub pinned_records: u64,
189}
190
191#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
192pub struct MaintenanceStats {
193 pub duplicate_candidate_groups: u64,
194 pub duplicate_candidate_records: u64,
195 pub tombstoned_records: u64,
196 pub expired_records: u64,
197 pub stale_idempotency_keys: u64,
198 pub historical_records: u64,
199 pub superseded_records: u64,
200 pub lineage_links: u64,
201}
202
203#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
204pub struct StoreStatsReport {
205 pub generated_at_unix_ms: u64,
206 pub total_records: u64,
207 pub storage_bytes: u64,
208 pub namespaces: Vec<NamespaceStats>,
209 pub maintenance: MaintenanceStats,
210 pub engine: EngineTuningInfo,
211}
212
213#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
214pub struct IntegrityCheckRequest {
215 pub tenant_id: Option<String>,
216 pub namespace: Option<String>,
217}
218
219#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
220pub struct IntegrityCheckReport {
221 pub generated_at_unix_ms: u64,
222 pub healthy: bool,
223 pub scanned_records: u64,
224 pub scanned_idempotency_keys: u64,
225 pub stale_idempotency_keys: u64,
226 pub missing_idempotency_keys: u64,
227 pub duplicate_active_records: u64,
228}
229
230#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
231pub struct RepairRequest {
232 pub tenant_id: Option<String>,
233 pub namespace: Option<String>,
234 pub dry_run: bool,
235 pub reason: String,
236 pub remove_stale_idempotency_keys: bool,
237 pub rebuild_missing_idempotency_keys: bool,
238}
239
240#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
241pub struct RepairReport {
242 pub dry_run: bool,
243 pub scanned_records: u64,
244 pub scanned_idempotency_keys: u64,
245 pub removed_stale_idempotency_keys: u64,
246 pub rebuilt_missing_idempotency_keys: u64,
247 pub healthy_after: bool,
248}
249
250#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
251pub enum TraceOperationKind {
252 Upsert,
253 BatchUpsert,
254 Recall,
255 Snapshot,
256 Stats,
257 IntegrityCheck,
258 Repair,
259 Compact,
260 Delete,
261 Archive,
262 Suppress,
263 Recover,
264 Export,
265 Import,
266}
267
268#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
269pub enum TraceStatus {
270 Ok,
271 Rejected,
272 Error,
273}
274
275#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
276pub struct OperationTraceSummary {
277 pub record_id: Option<String>,
278 pub request_count: Option<u32>,
279 pub query_text: Option<String>,
280 pub max_items: Option<u32>,
281 pub token_budget: Option<u32>,
282 pub dry_run: Option<bool>,
283}
284
285#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
286pub struct OperationTrace {
287 pub trace_id: String,
288 pub correlation_id: String,
289 pub operation: TraceOperationKind,
290 pub transport: String,
291 pub backend: Option<String>,
292 pub admission_class: Option<String>,
293 pub tenant_id: Option<String>,
294 pub namespace: Option<String>,
295 pub principal: Option<String>,
296 pub store_span_id: Option<String>,
297 pub planning_trace_id: Option<String>,
298 pub started_at_unix_ms: u64,
299 pub completed_at_unix_ms: u64,
300 pub latency_ms: u64,
301 pub status: TraceStatus,
302 pub status_message: Option<String>,
303 pub summary: OperationTraceSummary,
304 pub recall_explanation: Option<RecallExplanation>,
305}
306
307#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
308pub struct TraceListRequest {
309 pub tenant_id: Option<String>,
310 pub namespace: Option<String>,
311 pub operation: Option<TraceOperationKind>,
312 pub status: Option<TraceStatus>,
313 pub before_started_at_unix_ms: Option<u64>,
314 pub limit: Option<usize>,
315}
316
317#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
318pub struct PortableRecord {
319 pub record: MemoryRecord,
320 pub idempotency_key: Option<String>,
321}
322
323#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
324pub struct ExportRequest {
325 pub tenant_id: Option<String>,
326 pub namespace: Option<String>,
327 pub include_archived: bool,
328}
329
330#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
331pub struct PortableStorePackage {
332 pub package_version: u32,
333 pub exported_at_unix_ms: u64,
334 pub manifest: SnapshotManifest,
335 pub records: Vec<PortableRecord>,
336}
337
338#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
339pub enum ImportMode {
340 Validate,
341 Merge,
342 Replace,
343}
344
345#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
346pub struct ImportRequest {
347 pub package: PortableStorePackage,
348 pub mode: ImportMode,
349 pub dry_run: bool,
350}
351
352#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
353pub struct ImportFailure {
354 pub record_id: Option<String>,
355 pub reason: String,
356}
357
358#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
359pub struct ImportReport {
360 pub mode: ImportMode,
361 pub dry_run: bool,
362 pub applied: bool,
363 pub compatible_package: bool,
364 pub package_version: u32,
365 pub validated_records: u64,
366 pub imported_records: u64,
367 pub skipped_records: u64,
368 pub replaced_existing: bool,
369 pub snapshot_id: String,
370 pub failed_records: Vec<ImportFailure>,
371}