chore: rename get_id to id, add doc comments, pre-allocate format_history

common/src/storage/db.rs

@@ -143,7 +143,7 @@ impl SurrealDbClient {
         T: StoredObject + Send + Sync + 'static,
     {
         self.client
-            .create((T::table_name(), item.get_id()))
+            .create((T::table_name(), item.id()))
             .content(item)
             .await
     }
@@ -159,7 +159,7 @@ impl SurrealDbClient {
     where
         T: StoredObject + Send + Sync + 'static,
     {
-        let id = item.get_id().to_string();
+        let id = item.id().to_string();
         self.client
             .upsert((T::table_name(), id))
             .content(item)

common/src/storage/indexes.rs

@@ -581,14 +581,22 @@ async fn poll_index_build_status(
     Ok(())
 }
 
+/// Snapshot of an index build progress as reported by SurrealDB's `INFO FOR INDEX`.
 #[derive(Debug, PartialEq)]
 struct IndexBuildSnapshot {
+    /// Current build status string (e.g., `"indexing"`, `"ready"`, `"error"`).
     status: String,
+    /// Number of rows present when the build started.
     initial: u64,
+    /// Number of rows still pending processing.
     pending: u64,
+    /// Number of rows updated since the build started.
     updated: u64,
+    /// Total rows processed so far (`initial + updated`).
     processed: u64,
+    /// Total rows expected (from `SELECT count()` before the build), if available.
     total_rows: Option<u64>,
+    /// Progress as a percentage of `processed / total_rows`, if `total_rows` is known.
     progress_pct: Option<f64>,
 }
 

common/src/storage/types/analytics.rs

@@ -16,7 +16,7 @@ impl StoredObject for Analytics {
         "analytics"
     }
 
-    fn get_id(&self) -> &str {
+    fn id(&self) -> &str {
         &self.id
     }
 }

common/src/storage/types/file_info.rs

@@ -19,26 +19,34 @@ use crate::{
     stored_object,
 };
 
+/// Errors that can occur during file storage operations.
 #[derive(Error, Debug)]
 pub enum FileError {
+    /// No file record found with the given UUID.
     #[error("file not found for uuid: {0}")]
     FileNotFound(String),
 
+    /// Underlying I/O operation failed.
     #[error("io error occurred: {0}")]
     Io(#[from] std::io::Error),
 
+    /// A file with the same SHA-256 hash already exists.
     #[error("duplicate file detected with sha256: {0}")]
     DuplicateFile(String),
 
+    /// Database operation on the file record failed.
     #[error("surrealdb error: {0}")]
     SurrealError(#[from] surrealdb::Error),
 
+    /// Failed to persist the temporary file to its final location.
     #[error("failed to persist file: {0}")]
     PersistError(#[from] tempfile::PersistError),
 
+    /// Upload metadata did not include a file name.
     #[error("file name missing in metadata")]
     MissingFileName,
 
+    /// The underlying object store operation failed.
     #[error("object store error: {0}")]
     ObjectStore(#[from] ObjectStoreError),
 }

common/src/storage/types/ingestion_task.rs

@@ -68,12 +68,16 @@ impl TaskState {
     }
 }
 
+/// Information about an error that occurred during task processing.
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq, Default)]
 pub struct TaskErrorInfo {
+    /// Machine-readable error code (e.g., `"pipeline_error"`).
     pub code: Option<String>,
+    /// Human-readable error description.
     pub message: String,
 }
 
+/// Internal events that drive the task state machine transitions.
 #[derive(Debug, Clone, Copy)]
 enum TaskTransition {
     StartProcessing,

common/src/storage/types/message.rs

@@ -60,7 +60,11 @@ impl fmt::Display for Message {
 // helper function to format a vector of messages
 #[must_use]
 pub fn format_history(history: &[Message]) -> String {
-    let mut out = String::new();
+    let estimated: usize = history
+        .iter()
+        .map(|m| m.content.len() + 10)
+        .sum();
+    let mut out = String::with_capacity(estimated);
     for (i, msg) in history.iter().enumerate() {
         if i > 0 {
             out.push('\n');

common/src/storage/types/mod.rs

@@ -20,7 +20,7 @@ pub mod user;
 
 pub trait StoredObject: Serialize + for<'de> Deserialize<'de> {
     fn table_name() -> &'static str;
-    fn get_id(&self) -> &str;
+    fn id(&self) -> &str;
 }
 
 #[macro_export]
@@ -52,7 +52,7 @@ macro_rules! stored_object {
                 $table
             }
 
-            fn get_id(&self) -> &str {
+            fn id(&self) -> &str {
                 &self.id
             }
         }

common/src/storage/types/system_settings.rs

@@ -28,7 +28,7 @@ impl StoredObject for SystemSettings {
         "system_settings"
     }
 
-    fn get_id(&self) -> &str {
+    fn id(&self) -> &str {
         &self.id
     }
 }

common/src/utils/ingest_limits.rs

@@ -1,8 +1,11 @@
 use super::config::AppConfig;
 
+/// Errors raised when validating ingestion payloads against configured limits.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum IngestValidationError {
+    /// The payload exceeds a configured size limit (content, context, or category).
     PayloadTooLarge(String),
+    /// The request violates a non-size constraint (e.g., too many files).
     BadRequest(String),
 }