refactor(storage): consolidate AsyncWorkspace into Workspace

BREAKING CHANGE: Removed AsyncWorkspace in favor of unified Workspace
that provides async functionality directly.

- Replace all AsyncWorkspace references with Workspace across the codebase
- Update examples to use Workspace instead of AsyncWorkspace
- Modify client builder, engine, and workspace modules accordingly
- Update pipeline executor and persist stage to use new Workspace type
- Export Workspace instead of AsyncWorkspace in public API

This change simplifies the storage API by removing the distinction between
sync and async workspace implementations, as Workspace now provides
async capabilities natively.

Author: zTgx

.github/workflows/ci.yml

@@ -59,15 +59,29 @@ jobs:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
-      - run: cargo doc --no-deps --all-features
+      - name: Check documentation build
+        run: cargo doc --no-deps --all-features
         env:
           RUSTDOCFLAGS: -D warnings
 
+  doctest:
+    name: Doc Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Run documentation tests
+        run: cargo test --doc --all-features
+        continue-on-error: true  # Allow doctest failures initially
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+
   # Release build check
   build:
     name: Build
     runs-on: ubuntu-latest
-    needs: [check, fmt, clippy, test]
+    needs: [check, fmt, clippy, test, docs]
     steps:
       - uses: actions/checkout@v4
       - uses: dtolnay/rust-toolchain@stable

examples/storage_async.rs

@@ -17,7 +17,7 @@ use std::sync::{Arc, RwLock};
 
 use vectorless::Result;
 use vectorless::document::DocumentTree;
-use vectorless::storage::{AsyncWorkspace, DocumentMeta, PersistedDocument, StorageBackend};
+use vectorless::storage::{Workspace, DocumentMeta, PersistedDocument, StorageBackend};
 
 /// A simple in-memory backend with logging.
 ///
@@ -107,7 +107,7 @@ async fn main() -> vectorless::Result<()> {
 
     // 2. Create workspace with custom backend
     println!("2. Creating workspace with custom backend...");
-    let workspace = AsyncWorkspace::with_backend(backend).await?;
+    let workspace = Workspace::with_backend(backend).await?;
     println!("   ✓ Workspace created\n");
 
     // 3. Add a document (watch the logging)

examples/storage_backend.rs

@@ -16,7 +16,7 @@
 //! ```
 
 use vectorless::document::DocumentTree;
-use vectorless::storage::{AsyncWorkspace, DocumentMeta, PersistedDocument};
+use vectorless::storage::{Workspace, DocumentMeta, PersistedDocument};
 
 #[tokio::main]
 async fn main() -> vectorless::Result<()> {
@@ -27,7 +27,7 @@ async fn main() -> vectorless::Result<()> {
 
     // 1. Create a workspace with custom cache size
     println!("1. Creating workspace at '{}'...", workspace_path);
-    let workspace = AsyncWorkspace::with_cache_size(workspace_path, 100)
+    let workspace = Workspace::with_cache_size(workspace_path, 100)
         .await
         .map_err(|e| vectorless::Error::Workspace(e.to_string()))?;
     println!("   ✓ Workspace created\n");

examples/storage_workspace.rs

@@ -37,7 +37,7 @@ use std::path::PathBuf;
 
 use crate::config::{Config, ConfigLoader, RetrievalConfig};
 use crate::retrieval::PipelineRetriever;
-use crate::storage::AsyncWorkspace;
+use crate::storage::Workspace;
 
 use super::engine::Engine;
 use super::events::EventEmitter;
@@ -424,7 +424,7 @@ impl EngineBuilder {
             .as_ref()
             .unwrap_or(&config.storage.workspace_dir);
 
-        let workspace = AsyncWorkspace::new(workspace_path)
+        let workspace = Workspace::new(workspace_path)
             .await
             .map_err(|e| BuildError::Workspace(e.to_string()))?;
 

src/client/builder.rs

@@ -54,7 +54,7 @@ use crate::config::Config;
 use crate::error::Result;
 use crate::index::PipelineExecutor;
 use crate::retrieval::{PipelineRetriever, RetrieveOptions};
-use crate::storage::AsyncWorkspace;
+use crate::storage::Workspace;
 use crate::{DocumentTree, Error};
 
 use super::context::ClientContext;
@@ -108,7 +108,7 @@ impl Engine {
     /// Note: Prefer using [`Engine::builder()`] for more control.
     async fn new() -> Result<Self> {
         let config = Config::default();
-        let workspace = AsyncWorkspace::new("./workspace")
+        let workspace = Workspace::new("./workspace")
             .await
             .map_err(|e| Error::Workspace(e.to_string()))?;
         Self::with_components(
@@ -127,7 +127,7 @@ impl Engine {
     /// Create a new client with the given components.
     pub(crate) async fn with_components(
         config: Config,
-        workspace: AsyncWorkspace,
+        workspace: Workspace,
         retriever: PipelineRetriever,
         executor: PipelineExecutor,
     ) -> Result<Self> {
@@ -299,7 +299,7 @@ impl Engine {
             Some(ws) => ws.clone(),
             None => {
                 // Create a temporary workspace if none configured
-                let async_ws = AsyncWorkspace::new("./temp_workspace")
+                let async_ws = Workspace::new("./temp_workspace")
                     .await
                     .expect("Failed to create temp workspace");
                 WorkspaceClient::new(async_ws).await

src/client/engine.rs

@@ -28,7 +28,7 @@ use std::sync::Arc;
 use tracing::{debug, info, warn};
 
 use crate::error::Result;
-use crate::storage::{AsyncWorkspace, PersistedDocument};
+use crate::storage::{Workspace, PersistedDocument};
 
 use super::events::{EventEmitter, WorkspaceEvent};
 use super::types::DocumentInfo;
@@ -45,7 +45,7 @@ use super::types::DocumentInfo;
 #[derive(Clone)]
 pub struct WorkspaceClient {
     /// Workspace storage.
-    workspace: Arc<AsyncWorkspace>,
+    workspace: Arc<Workspace>,
 
     /// Event emitter.
     events: EventEmitter,
@@ -75,7 +75,7 @@ impl Default for WorkspaceClientConfig {
 
 impl WorkspaceClient {
     /// Create a new workspace client.
-    pub async fn new(workspace: AsyncWorkspace) -> Self {
+    pub async fn new(workspace: Workspace) -> Self {
         Self {
             workspace: Arc::new(workspace),
             events: EventEmitter::new(),
@@ -96,7 +96,7 @@ impl WorkspaceClient {
     }
 
     /// Create from an existing workspace Arc.
-    pub(crate) fn from_arc(workspace: Arc<AsyncWorkspace>, events: EventEmitter) -> Self {
+    pub(crate) fn from_arc(workspace: Arc<Workspace>, events: EventEmitter) -> Self {
         Self {
             workspace,
             events,
@@ -285,7 +285,7 @@ impl WorkspaceClient {
     }
 
     /// Get the underlying workspace Arc (for advanced use).
-    pub(crate) fn inner(&self) -> Arc<AsyncWorkspace> {
+    pub(crate) fn inner(&self) -> Arc<Workspace> {
         Arc::clone(&self.workspace)
     }
 }
@@ -306,15 +306,15 @@ mod tests {
     #[tokio::test]
     async fn test_workspace_client_creation() {
         let backend = StdArc::new(MemoryBackend::new());
-        let workspace = AsyncWorkspace::with_backend(backend).await.unwrap();
+        let workspace = Workspace::with_backend(backend).await.unwrap();
         let client = WorkspaceClient::new(workspace).await;
         assert!(client.is_empty().await);
     }
 
     #[tokio::test]
     async fn test_workspace_stats() {
         let backend = StdArc::new(MemoryBackend::new());
-        let workspace = AsyncWorkspace::with_backend(backend).await.unwrap();
+        let workspace = Workspace::with_backend(backend).await.unwrap();
         let client = WorkspaceClient::new(workspace).await;
 
         let stats = client.stats().await.unwrap();

src/client/workspace.rs

@@ -136,7 +136,7 @@ impl PipelineExecutor {
     }
 
     /// Add persistence stage with async workspace.
-    pub fn with_persistence(mut self, workspace: crate::storage::AsyncWorkspace) -> Self {
+    pub fn with_persistence(mut self, workspace: crate::storage::Workspace) -> Self {
         self.orchestrator = self
             .orchestrator
             .stage_with_priority(PersistStage::with_workspace(workspace), 80);

src/index/pipeline/executor.rs

@@ -8,15 +8,15 @@ use std::time::Instant;
 use tracing::info;
 
 use crate::error::Result;
-use crate::storage::{AsyncWorkspace, DocumentMeta as StorageMeta, PersistedDocument};
+use crate::storage::{Workspace, DocumentMeta as StorageMeta, PersistedDocument};
 
 use super::{IndexStage, StageResult};
 use crate::index::pipeline::IndexContext;
 
 /// Persist stage - saves indexed document to storage.
 pub struct PersistStage {
     /// Optional workspace for persistence.
-    workspace: Option<AsyncWorkspace>,
+    workspace: Option<Workspace>,
 }
 
 impl PersistStage {
@@ -26,7 +26,7 @@ impl PersistStage {
     }
 
     /// Create with workspace.
-    pub fn with_workspace(workspace: AsyncWorkspace) -> Self {
+    pub fn with_workspace(workspace: Workspace) -> Self {
         Self {
             workspace: Some(workspace),
         }

src/index/stages/persist.rs

@@ -167,7 +167,7 @@ pub use retrieval::{
 };
 
 // Storage
-pub use storage::{AsyncWorkspace, DocumentMeta as StorageDocumentMeta, PersistedDocument};
+pub use storage::{Workspace, DocumentMeta as StorageDocumentMeta, PersistedDocument};
 
 // Throttle
 pub use throttle::{ConcurrencyConfig, ConcurrencyController, RateLimiter};