feature: add generic SQLite queue adapter with JSON serialization

docs/configuration-reference.md

···
 **Required**: No  
 **Type**: String  
 **Default**: `mpsc`  
-**Values**: `mpsc`, `redis`, `noop`, `none`  
+**Values**: `mpsc`, `redis`, `sqlite`, `noop`, `none`  
 
 The type of queue adapter for background handle resolution.
 
 **Options**:
 - `mpsc`: In-memory multi-producer single-consumer queue (default)
 - `redis`: Redis-backed distributed queue
+- `sqlite`: SQLite-backed persistent queue
 - `noop`: Disable queue processing (testing only)
 - `none`: Alias for `noop`
 
···
 
 # Multi-instance or high availability
 QUEUE_ADAPTER=redis
+
+# Single instance with persistence
+QUEUE_ADAPTER=sqlite
 
 # Testing without background processing
 QUEUE_ADAPTER=noop
···
 QUEUE_BUFFER_SIZE=10000   # Very high traffic
 ```
 
+### `QUEUE_SQLITE_MAX_SIZE`
+
+**Required**: No  
+**Type**: Integer  
+**Default**: `10000`  
+**Range**: 100-1000000 (recommended)  
+**Constraints**: Must be >= 0  
+
+Maximum queue size for SQLite adapter work shedding. When the queue exceeds this limit, the oldest entries are automatically deleted to maintain the specified size limit, preserving the most recently queued work items.
+
+**Work Shedding Behavior**:
+- New work items are always accepted
+- When queue size exceeds `QUEUE_SQLITE_MAX_SIZE`, oldest entries are deleted
+- Deletion happens atomically with insertion in a single transaction
+- Essential for long-running deployments to prevent unbounded disk growth
+- Set to `0` to disable work shedding (unlimited queue size)
+
+**Examples**:
+```bash
+QUEUE_SQLITE_MAX_SIZE=0        # Unlimited (disable work shedding)
+QUEUE_SQLITE_MAX_SIZE=1000     # Small deployment, frequent processing
+QUEUE_SQLITE_MAX_SIZE=10000    # Default, balanced for most deployments
+QUEUE_SQLITE_MAX_SIZE=100000   # High-traffic deployment with slower processing
+QUEUE_SQLITE_MAX_SIZE=1000000  # Very high-traffic, maximum recommended
+```
+
+**Recommendations**:
+- **Small deployments**: 1000-5000 entries
+- **Production deployments**: 10000-50000 entries
+- **High-traffic deployments**: 50000-1000000 entries
+- **Development/testing**: 100-1000 entries
+- **Disk space concerns**: Lower values (1000-5000)
+- **High ingestion rate**: Higher values (50000-1000000)
+
 ## Configuration Examples
 
 ### Minimal Development Configuration
···
 CACHE_TTL_MEMORY=600
 CACHE_TTL_SQLITE=86400  # 1 day
 
-# Queue (MPSC for single instance)
-QUEUE_ADAPTER=mpsc
+# Queue (SQLite for single instance with persistence)
+QUEUE_ADAPTER=sqlite
 QUEUE_BUFFER_SIZE=5000
+QUEUE_SQLITE_MAX_SIZE=10000
 
 # Logging
 RUST_LOG=info
···
       SQLITE_URL: sqlite:/data/quickdid.db
       CACHE_TTL_MEMORY: 600
       CACHE_TTL_SQLITE: 86400
-      QUEUE_ADAPTER: mpsc
+      QUEUE_ADAPTER: sqlite
       QUEUE_BUFFER_SIZE: 5000
+      QUEUE_SQLITE_MAX_SIZE: 10000
       RUST_LOG: info
     ports:
       - "8080:8080"
···
    - Recommended range: 1-60 seconds
 
 3. **Queue Adapter** (`QUEUE_ADAPTER`):
-   - Must be one of: `mpsc`, `redis`, `noop`, `none`
+   - Must be one of: `mpsc`, `redis`, `sqlite`, `noop`, `none`
    - Case-sensitive
 
 4. **Port** (`HTTP_PORT`):
···
 4. **High traffic**: Increase QUEUE_BUFFER_SIZE (5000-10000)
 5. **Multi-region**: Use region-specific QUEUE_WORKER_ID
 
-### Caching Strategy
+### Caching and Queue Strategy
 
-1. **Multi-instance/HA deployments**: Use Redis for distributed caching
-2. **Single-instance deployments**: Use SQLite for persistent caching
-3. **Development/testing**: Use memory-only caching
+1. **Multi-instance/HA deployments**: Use Redis for distributed caching and queuing
+2. **Single-instance deployments**: Use SQLite for persistent caching and queuing
+3. **Development/testing**: Use memory-only caching with MPSC queuing
 4. **Hybrid setups**: Configure both Redis and SQLite for redundancy
-5. **Cache TTL guidelines**:
+5. **Queue adapter guidelines**:
+   - Redis: Best for multi-instance deployments with distributed processing
+   - SQLite: Best for single-instance deployments needing persistence
+   - MPSC: Best for single-instance deployments without persistence needs
+6. **Cache TTL guidelines**:
    - Redis: Shorter TTLs (1-7 days) for frequently updated handles
    - SQLite: Longer TTLs (7-90 days) for stable single-instance caching
    - Memory: Short TTLs (5-30 minutes) as fallback

docs/production-deployment.md

···
 # QUEUE CONFIGURATION
 # ----------------------------------------------------------------------------
 
-# Queue adapter type: 'mpsc', 'redis', 'noop', or 'none' (default: mpsc)
+# Queue adapter type: 'mpsc', 'redis', 'sqlite', 'noop', or 'none' (default: mpsc)
 # - 'mpsc': In-memory queue for single-instance deployments
 # - 'redis': Distributed queue for multi-instance or HA deployments
+# - 'sqlite': Persistent queue for single-instance deployments
 # - 'noop': Disable queue processing (testing only)
 # - 'none': Alias for 'noop'
 QUEUE_ADAPTER=redis
···
 # Range: 100-100000
 # Increase for high-traffic deployments using MPSC adapter
 QUEUE_BUFFER_SIZE=5000
+
+# Maximum queue size for SQLite adapter work shedding (default: 10000)
+# Range: 100-1000000 (recommended)
+# When exceeded, oldest entries are deleted to maintain this limit
+# Set to 0 to disable work shedding (unlimited queue size)
+# Benefits: Prevents unbounded disk usage, maintains recent work items
+QUEUE_SQLITE_MAX_SIZE=10000
 
 # ----------------------------------------------------------------------------
 # HTTP CLIENT CONFIGURATION
···
       SQLITE_URL: sqlite:/data/quickdid.db
       CACHE_TTL_MEMORY: 600
       CACHE_TTL_SQLITE: 86400
-      QUEUE_ADAPTER: mpsc
+      QUEUE_ADAPTER: sqlite
       QUEUE_BUFFER_SIZE: 5000
+      QUEUE_SQLITE_MAX_SIZE: 10000
       RUST_LOG: info
     ports:
       - "8080:8080"
···
 
 # Check SQLite cache entries (if using SQLite)
 docker exec quickdid sqlite3 /data/quickdid.db "SELECT COUNT(*) as total_entries, MIN(updated) as oldest, MAX(updated) as newest FROM handle_resolution_cache;"
+
+# Check SQLite queue entries (if using SQLite queue adapter)
+docker exec quickdid sqlite3 /data/quickdid.db "SELECT COUNT(*) as queue_entries, MIN(queued_at) as oldest, MAX(queued_at) as newest FROM handle_resolution_queue;"
 
 # Monitor real-time logs
 docker-compose logs -f quickdid | grep -E "ERROR|WARN"
···
 3. **Memory** (fast, but lost on restart)
 
 **Recommendations by Deployment Type**:
-- **Single instance, persistent**: Use SQLite (`SQLITE_URL=sqlite:./quickdid.db`)
-- **Multi-instance, HA**: Use Redis (`REDIS_URL=redis://redis:6379/0`)
-- **Testing/development**: Use memory only (no Redis/SQLite URLs)
+- **Single instance, persistent**: Use SQLite for both caching and queuing (`SQLITE_URL=sqlite:./quickdid.db`, `QUEUE_ADAPTER=sqlite`)
+- **Multi-instance, HA**: Use Redis for both caching and queuing (`REDIS_URL=redis://redis:6379/0`, `QUEUE_ADAPTER=redis`)
+- **Testing/development**: Use memory-only caching with MPSC queuing (`QUEUE_ADAPTER=mpsc`)
 - **Hybrid**: Configure both Redis and SQLite for redundancy
+
+### Queue Strategy Selection
+
+**Queue Adapter Options**:
+1. **Redis** (`QUEUE_ADAPTER=redis`) - Distributed queuing, best for multi-instance deployments
+2. **SQLite** (`QUEUE_ADAPTER=sqlite`) - Persistent queuing, best for single-instance deployments
+3. **MPSC** (`QUEUE_ADAPTER=mpsc`) - In-memory queuing, lightweight for single-instance without persistence needs
+4. **No-op** (`QUEUE_ADAPTER=noop`) - Disable queuing entirely (testing only)
 
 ### Redis Optimization
 
···
    - Recommended range: 1-60 seconds
 
 3. **Queue Adapter** (`QUEUE_ADAPTER`):
-   - Must be one of: `mpsc`, `redis`, `noop`, `none`
+   - Must be one of: `mpsc`, `redis`, `sqlite`, `noop`, `none`
    - Case-sensitive
 
 ### Validation Errors

src/bin/quickdid.rs

···
     http::{AppContext, create_router},
     queue_adapter::{
         HandleResolutionWork, QueueAdapter, create_mpsc_queue_from_channel, create_noop_queue,
-        create_redis_queue,
+        create_redis_queue, create_sqlite_queue, create_sqlite_queue_with_max_size,
     },
     task_manager::spawn_cancellable_task,
 };
···
                 } else {
                     tracing::warn!(
                         "Redis queue adapter requested but no Redis URL configured, using no-op adapter"
+                    );
+                    create_noop_queue::<HandleResolutionWork>()
+                }
+            }
+            "sqlite" => {
+                // Use SQLite adapter
+                if let Some(url) = config.sqlite_url.as_ref() {
+                    if let Some(pool) = try_create_sqlite_pool(url, "queue adapter").await {
+                        if config.queue_sqlite_max_size > 0 {
+                            tracing::info!(
+                                "Creating SQLite queue adapter with work shedding (max_size: {})",
+                                config.queue_sqlite_max_size
+                            );
+                            create_sqlite_queue_with_max_size::<HandleResolutionWork>(
+                                pool,
+                                config.queue_sqlite_max_size,
+                            )
+                        } else {
+                            tracing::info!("Creating SQLite queue adapter (unlimited size)");
+                            create_sqlite_queue::<HandleResolutionWork>(pool)
+                        }
+                    } else {
+                        tracing::warn!("Failed to create SQLite pool for queue, falling back to MPSC queue adapter");
+                        // Fall back to MPSC if SQLite fails
+                        let (handle_sender, handle_receiver) =
+                            tokio::sync::mpsc::channel::<HandleResolutionWork>(
+                                config.queue_buffer_size,
+                            );
+                        create_mpsc_queue_from_channel(handle_sender, handle_receiver)
+                    }
+                } else {
+                    tracing::warn!(
+                        "SQLite queue adapter requested but no SQLite URL configured, using no-op adapter"
                     );
                     create_noop_queue::<HandleResolutionWork>()
                 }

src/config.rs

···
   CACHE_TTL_SQLITE    TTL for SQLite cache in seconds (default: 7776000 = 90 days)
   
   QUEUE CONFIGURATION:
-  QUEUE_ADAPTER       Queue adapter: 'mpsc', 'redis', 'noop', 'none' (default: mpsc)
+  QUEUE_ADAPTER       Queue adapter: 'mpsc', 'redis', 'sqlite', 'noop', 'none' (default: mpsc)
   QUEUE_REDIS_URL     Redis URL for queue adapter (uses REDIS_URL if not set)
   QUEUE_REDIS_PREFIX  Redis key prefix for queues (default: queue:handleresolver:)
   QUEUE_REDIS_TIMEOUT Queue blocking timeout in seconds (default: 5)
   QUEUE_WORKER_ID     Worker ID for Redis queue (default: worker1)
   QUEUE_BUFFER_SIZE   Buffer size for MPSC queue (default: 1000)
+  QUEUE_SQLITE_MAX_SIZE Maximum SQLite queue size for work shedding (default: 10000, 0=unlimited)
 "
 )]
 /// Command-line arguments and environment variables configuration
···
     /// Values:
     /// - "mpsc": In-memory multi-producer single-consumer queue
     /// - "redis": Redis-backed distributed queue
+    /// - "sqlite": SQLite-backed persistent queue
     /// - "noop": Disable queue processing (for testing)
     /// - "none": Alias for "noop"
     ///
···
     /// Higher values = less Redis polling overhead
     #[arg(long, env = "QUEUE_REDIS_TIMEOUT", default_value = "5")]
     pub queue_redis_timeout: u64,
+
+    /// Maximum queue size for SQLite adapter (work shedding)
+    ///
+    /// Range: 100-1000000 (recommended)
+    /// Default: 10000
+    ///
+    /// When the SQLite queue exceeds this limit, the oldest entries are deleted
+    /// to maintain the queue size. This prevents unbounded queue growth while
+    /// preserving the most recently queued work items.
+    ///
+    /// Set to 0 to disable work shedding (unlimited queue size)
+    #[arg(long, env = "QUEUE_SQLITE_MAX_SIZE", default_value = "10000")]
+    pub queue_sqlite_max_size: u64,
 }
 
 /// Validated configuration for QuickDID service
···
     /// SQLite database URL for caching (e.g., "sqlite:./quickdid.db")
     pub sqlite_url: Option<String>,
 
-    /// Queue adapter type: "mpsc", "redis", or "noop"
+    /// Queue adapter type: "mpsc", "redis", "sqlite", or "noop"
     pub queue_adapter: String,
 
     /// Redis URL for queue operations (falls back to redis_url)
···
 
     /// Redis blocking timeout for queue operations in seconds (e.g., 5)
     pub queue_redis_timeout: u64,
+
+    /// Maximum queue size for SQLite adapter work shedding (e.g., 10000)
+    /// When exceeded, oldest entries are deleted to maintain this limit.
+    /// Set to 0 to disable work shedding (unlimited queue size).
+    pub queue_sqlite_max_size: u64,
 }
 
 impl Config {
···
             cache_ttl_redis: args.cache_ttl_redis,
             cache_ttl_sqlite: args.cache_ttl_sqlite,
             queue_redis_timeout: args.queue_redis_timeout,
+            queue_sqlite_max_size: args.queue_sqlite_max_size,
         })
     }
 
···
             ));
         }
         match self.queue_adapter.as_str() {
-            "mpsc" | "redis" | "noop" | "none" => {}
+            "mpsc" | "redis" | "sqlite" | "noop" | "none" => {}
             _ => {
                 return Err(ConfigError::InvalidValue(format!(
-                    "Invalid QUEUE_ADAPTER '{}', must be 'mpsc', 'redis', or 'noop'",
+                    "Invalid QUEUE_ADAPTER '{}', must be 'mpsc', 'redis', 'sqlite', or 'noop'",
                     self.queue_adapter
                 )));
             }

src/queue_adapter.rs

···
 use async_trait::async_trait;
 use deadpool_redis::{Pool as RedisPool, redis::AsyncCommands};
 use serde::{Deserialize, Serialize};
+use sqlx::{self, Row};
 use std::sync::Arc;
 use thiserror::Error;
 use tokio::sync::{Mutex, mpsc};
···
     }
 }
 
+/// SQLite-backed queue adapter implementation.
+///
+/// This adapter uses SQLite database for persistent queuing of work items.
+/// It's suitable for single-instance deployments that need persistence
+/// across service restarts while remaining lightweight.
+///
+/// # Features
+///
+/// - Persistent queuing across service restarts
+/// - Simple FIFO ordering based on insertion time
+/// - Single consumer design (no complex locking needed)
+/// - Simple pull-and-delete semantics
+/// - Work shedding to prevent unbounded queue growth
+///
+/// # Work Shedding
+///
+/// When `max_size` is configured (> 0), the adapter implements work shedding:
+/// - New work items are always accepted
+/// - When the queue exceeds `max_size`, oldest entries are automatically deleted
+/// - This maintains the most recent work items while preventing unbounded growth
+/// - Essential for long-running deployments to avoid disk space issues
+pub(crate) struct SqliteQueueAdapter<T>
+where
+    T: Send + Sync + Serialize + for<'de> Deserialize<'de> + 'static,
+{
+    /// SQLite connection pool
+    pool: sqlx::SqlitePool,
+    /// Maximum queue size (0 = unlimited)
+    /// When exceeded, oldest entries are deleted to maintain this limit
+    max_size: u64,
+    /// Type marker for generic parameter
+    _phantom: std::marker::PhantomData<T>,
+}
+
+impl<T> SqliteQueueAdapter<T>
+where
+    T: Send + Sync + Serialize + for<'de> Deserialize<'de> + 'static,
+{
+    /// Create a new SQLite queue adapter with unlimited queue size.
+    pub(crate) fn new(pool: sqlx::SqlitePool) -> Self {
+        Self::with_max_size(pool, 0)
+    }
+
+    /// Create a new SQLite queue adapter with specified maximum queue size.
+    ///
+    /// # Arguments
+    ///
+    /// * `pool` - SQLite connection pool
+    /// * `max_size` - Maximum number of entries in queue (0 = unlimited)
+    ///
+    /// # Work Shedding Behavior
+    ///
+    /// When `max_size` > 0:
+    /// - New work items are always accepted
+    /// - If queue size exceeds `max_size` after insertion, oldest entries are deleted
+    /// - This preserves the most recent work while preventing unbounded growth
+    pub(crate) fn with_max_size(pool: sqlx::SqlitePool, max_size: u64) -> Self {
+        Self {
+            pool,
+            max_size,
+            _phantom: std::marker::PhantomData,
+        }
+    }
+}
+
+#[async_trait]
+impl<T> QueueAdapter<T> for SqliteQueueAdapter<T>
+where
+    T: Send + Sync + Serialize + for<'de> Deserialize<'de> + 'static,
+{
+    async fn pull(&self) -> Option<T> {
+        // Get the oldest queued item and delete it in a transaction
+        let mut transaction = match self.pool.begin().await {
+            Ok(tx) => tx,
+            Err(e) => {
+                error!("Failed to start SQLite transaction: {}", e);
+                return None;
+            }
+        };
+
+        // Select the oldest queued item
+        let record = match sqlx::query(
+            "SELECT id, work FROM handle_resolution_queue 
+             ORDER BY queued_at ASC 
+             LIMIT 1"
+        )
+        .fetch_optional(&mut *transaction)
+        .await
+        {
+            Ok(Some(row)) => row,
+            Ok(None) => {
+                // No queued items available
+                debug!("No queued items available in SQLite queue");
+                return None;
+            }
+            Err(e) => {
+                error!("Failed to query SQLite queue: {}", e);
+                return None;
+            }
+        };
+
+        let item_id: i64 = record.get("id");
+        let work_json: String = record.get("work");
+
+        // Delete the item from the queue
+        if let Err(e) = sqlx::query("DELETE FROM handle_resolution_queue WHERE id = ?1")
+            .bind(item_id)
+            .execute(&mut *transaction)
+            .await
+        {
+            error!("Failed to delete item from queue: {}", e);
+            return None;
+        }
+
+        // Commit the transaction
+        if let Err(e) = transaction.commit().await {
+            error!("Failed to commit SQLite transaction: {}", e);
+            return None;
+        }
+
+        // Deserialize the work item from JSON
+        match serde_json::from_str(&work_json) {
+            Ok(work) => {
+                debug!("Pulled work item from SQLite queue");
+                Some(work)
+            }
+            Err(e) => {
+                error!("Failed to deserialize work item: {}", e);
+                None
+            }
+        }
+    }
+
+    async fn push(&self, work: T) -> Result<()> {
+        // Serialize the entire work item as JSON
+        let work_json = serde_json::to_string(&work)
+            .map_err(|e| QueueError::SerializationFailed(e.to_string()))?;
+
+        let current_timestamp = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_secs() as i64;
+
+        // Optimized approach: Insert first, then check if cleanup needed
+        // This avoids counting on every insert
+        sqlx::query(
+            "INSERT INTO handle_resolution_queue (work, queued_at) VALUES (?1, ?2)"
+        )
+        .bind(&work_json)
+        .bind(current_timestamp)
+        .execute(&self.pool)
+        .await
+        .map_err(|e| QueueError::PushFailed(format!("Failed to insert work item: {}", e)))?;
+
+        // Implement optimized work shedding if max_size is configured
+        if self.max_size > 0 {
+            // Optimized approach: Only check and clean periodically or when likely over limit
+            // Use a limited count to avoid full table scan
+            let check_limit = self.max_size as i64 + (self.max_size as i64 / 10).max(1); // Check 10% over limit
+            let approx_count: Option<i64> = sqlx::query_scalar(
+                "SELECT COUNT(*) FROM (
+                    SELECT 1 FROM handle_resolution_queue LIMIT ?1
+                ) AS limited_count"
+            )
+            .bind(check_limit)
+            .fetch_one(&self.pool)
+            .await
+            .map_err(|e| QueueError::PushFailed(format!("Failed to check queue size: {}", e)))?;
+
+            // Only perform cleanup if we're definitely over the limit
+            if let Some(count) = approx_count && count >= check_limit {
+                // Perform batch cleanup - delete more than just the excess to reduce frequency
+                // Delete 20% more than needed to avoid frequent shedding
+                let target_size = (self.max_size as f64 * 0.8) as i64; // Keep 80% of max_size
+                let to_delete = count - target_size;
+                
+                if to_delete > 0 {
+                    // Optimized deletion: First get the cutoff id and timestamp
+                    // This avoids the expensive subquery in the DELETE statement
+                    let cutoff: Option<(i64, i64)> = sqlx::query_as(
+                        "SELECT id, queued_at FROM handle_resolution_queue 
+                         ORDER BY queued_at ASC, id ASC 
+                         LIMIT 1 OFFSET ?1"
+                    )
+                    .bind(to_delete - 1)
+                    .fetch_optional(&self.pool)
+                    .await
+                    .map_err(|e| QueueError::PushFailed(format!("Failed to find cutoff: {}", e)))?;
+
+                    if let Some((cutoff_id, cutoff_timestamp)) = cutoff {
+                        // Delete entries older than cutoff, or equal timestamp with lower id
+                        // This handles the case where multiple entries have the same timestamp
+                        let deleted_result = sqlx::query(
+                            "DELETE FROM handle_resolution_queue 
+                             WHERE queued_at < ?1 
+                                OR (queued_at = ?1 AND id <= ?2)"
+                        )
+                        .bind(cutoff_timestamp)
+                        .bind(cutoff_id)
+                        .execute(&self.pool)
+                        .await
+                        .map_err(|e| QueueError::PushFailed(format!("Failed to delete excess entries: {}", e)))?;
+
+                        let deleted_count = deleted_result.rows_affected();
+                        if deleted_count > 0 {
+                            tracing::info!(
+                                "Work shedding: deleted {} oldest entries (target size: {}, max: {})",
+                                deleted_count,
+                                target_size,
+                                self.max_size
+                            );
+                        }
+                    }
+                }
+            }
+        }
+
+        debug!("Pushed work item to SQLite queue (max_size: {})", self.max_size);
+        Ok(())
+    }
+
+    async fn ack(&self, _item: &T) -> Result<()> {
+        // With the simplified SQLite queue design, items are deleted when pulled,
+        // so acknowledgment is a no-op (item is already processed and removed)
+        debug!("Acknowledged work item in SQLite queue (no-op)");
+        Ok(())
+    }
+
+    async fn depth(&self) -> Option<usize> {
+        match sqlx::query_scalar::<_, i64>(
+            "SELECT COUNT(*) FROM handle_resolution_queue"
+        )
+        .fetch_one(&self.pool)
+        .await
+        {
+            Ok(count) => Some(count as usize),
+            Err(e) => {
+                warn!("Failed to get SQLite queue depth: {}", e);
+                None
+            }
+        }
+    }
+
+    async fn is_healthy(&self) -> bool {
+        // Test the connection by running a simple query
+        sqlx::query_scalar::<_, i64>("SELECT 1")
+            .fetch_one(&self.pool)
+            .await
+            .map(|_| true)
+            .unwrap_or(false)
+    }
+}
+
 // ========= Factory Functions for Queue Adapters =========
 
 /// Create a new MPSC queue adapter with the specified buffer size.
···
     Arc::new(NoopQueueAdapter::new())
 }
 
+/// Create a new SQLite queue adapter with unlimited queue size.
+///
+/// This creates a persistent queue backed by SQLite database suitable
+/// for single-instance deployments that need persistence across restarts.
+/// The queue has no size limit and may grow unbounded.
+///
+/// # Arguments
+///
+/// * `pool` - SQLite connection pool
+///
+/// # Example
+///
+/// ```no_run
+/// use quickdid::queue_adapter::{create_sqlite_queue, HandleResolutionWork};
+/// use quickdid::sqlite_schema::create_sqlite_pool;
+/// use std::sync::Arc;
+///
+/// # async fn example() -> anyhow::Result<()> {
+/// let pool = create_sqlite_pool("sqlite:./quickdid.db").await?;
+/// let queue = create_sqlite_queue::<HandleResolutionWork>(pool);
+/// # Ok(())
+/// # }
+/// ```
+pub fn create_sqlite_queue<T>(pool: sqlx::SqlitePool) -> Arc<dyn QueueAdapter<T>>
+where
+    T: Send + Sync + Serialize + for<'de> Deserialize<'de> + 'static,
+{
+    Arc::new(SqliteQueueAdapter::new(pool))
+}
+
+/// Create a new SQLite queue adapter with work shedding.
+///
+/// This creates a persistent queue with configurable maximum size.
+/// When the queue exceeds `max_size`, the oldest entries are automatically
+/// deleted to maintain the limit, preserving the most recent work items.
+///
+/// # Arguments
+///
+/// * `pool` - SQLite connection pool
+/// * `max_size` - Maximum number of entries (0 = unlimited)
+///
+/// # Work Shedding Behavior
+///
+/// - New work items are always accepted
+/// - When queue size exceeds `max_size`, oldest entries are deleted
+/// - Deletion happens atomically with insertion in a single transaction
+/// - Essential for long-running deployments to prevent disk space issues
+///
+/// # Example
+///
+/// ```no_run
+/// use quickdid::queue_adapter::{create_sqlite_queue_with_max_size, HandleResolutionWork};
+/// use quickdid::sqlite_schema::create_sqlite_pool;
+/// use std::sync::Arc;
+///
+/// # async fn example() -> anyhow::Result<()> {
+/// let pool = create_sqlite_pool("sqlite:./quickdid.db").await?;
+/// // Limit queue to 10,000 entries with automatic work shedding
+/// let queue = create_sqlite_queue_with_max_size::<HandleResolutionWork>(pool, 10000);
+/// # Ok(())
+/// # }
+/// ```
+pub fn create_sqlite_queue_with_max_size<T>(
+    pool: sqlx::SqlitePool,
+    max_size: u64,
+) -> Arc<dyn QueueAdapter<T>>
+where
+    T: Send + Sync + Serialize + for<'de> Deserialize<'de> + 'static,
+{
+    Arc::new(SqliteQueueAdapter::with_max_size(pool, max_size))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
···
 
         // Should be healthy if Redis is running
         assert!(adapter.is_healthy().await);
+    }
+
+    #[tokio::test]
+    async fn test_sqlite_queue_adapter_push_pull() {
+        // Create in-memory SQLite database for testing
+        let pool = sqlx::SqlitePool::connect("sqlite::memory:")
+            .await
+            .expect("Failed to connect to in-memory SQLite");
+
+        // Create the queue schema
+        crate::sqlite_schema::create_schema(&pool)
+            .await
+            .expect("Failed to create schema");
+
+        let adapter = Arc::new(SqliteQueueAdapter::<HandleResolutionWork>::new(pool.clone()));
+
+        let test_handle = "alice.example.com";
+        let work = HandleResolutionWork {
+            handle: test_handle.to_string(),
+        };
+
+        // Test push
+        adapter.push(work.clone()).await.unwrap();
+
+        // Verify the record is actually in the database
+        let records: Vec<(i64, String, i64)> = sqlx::query_as(
+            "SELECT id, work, queued_at FROM handle_resolution_queue ORDER BY queued_at ASC"
+        )
+        .fetch_all(&pool)
+        .await
+        .expect("Failed to query database");
+
+        assert_eq!(records.len(), 1);
+        let (db_id, db_work_json, db_queued_at) = &records[0];
+        assert!(*db_id > 0);
+        assert!(*db_queued_at > 0);
+        
+        // Verify the JSON content
+        let stored_work: HandleResolutionWork = serde_json::from_str(db_work_json)
+            .expect("Failed to deserialize stored work");
+        assert_eq!(stored_work.handle, test_handle);
+
+        // Verify depth
+        assert_eq!(adapter.depth().await, Some(1));
+
+        // Test pull
+        let pulled = adapter.pull().await;
+        assert!(pulled.is_some());
+        let pulled_work = pulled.unwrap();
+        assert_eq!(pulled_work.handle, test_handle);
+
+        // Verify the record was deleted from database after pull
+        let records_after_pull: Vec<(i64, String, i64)> = sqlx::query_as(
+            "SELECT id, work, queued_at FROM handle_resolution_queue"
+        )
+        .fetch_all(&pool)
+        .await
+        .expect("Failed to query database after pull");
+
+        assert_eq!(records_after_pull.len(), 0);
+
+        // Test ack - should be no-op since item already deleted
+        adapter.ack(&pulled_work).await.expect("Ack should succeed");
+
+        // Verify depth after ack
+        assert_eq!(adapter.depth().await, Some(0));
+
+        // Verify no more items to pull
+        let empty_pull = adapter.pull().await;
+        assert!(empty_pull.is_none());
+    }
+
+    #[tokio::test]
+    async fn test_sqlite_queue_adapter_multiple_items() {
+        // Create in-memory SQLite database for testing
+        let pool = sqlx::SqlitePool::connect("sqlite::memory:")
+            .await
+            .expect("Failed to connect to in-memory SQLite");
+
+        // Create the queue schema
+        crate::sqlite_schema::create_schema(&pool)
+            .await
+            .expect("Failed to create schema");
+
+        let adapter = Arc::new(SqliteQueueAdapter::<HandleResolutionWork>::new(pool.clone()));
+
+        // Push multiple items
+        let handles = vec!["alice.example.com", "bob.example.com", "charlie.example.com"];
+        for handle in &handles {
+            let work = HandleResolutionWork {
+                handle: handle.to_string(),
+            };
+            adapter.push(work).await.unwrap();
+        }
+
+        // Verify all records are in database with correct order
+        let records: Vec<(i64, String, i64)> = sqlx::query_as(
+            "SELECT id, work, queued_at FROM handle_resolution_queue ORDER BY queued_at ASC"
+        )
+        .fetch_all(&pool)
+        .await
+        .expect("Failed to query database");
+
+        assert_eq!(records.len(), 3);
+        
+        // Verify FIFO ordering by timestamp
+        assert!(records[0].2 <= records[1].2); // queued_at timestamps should be in order
+        assert!(records[1].2 <= records[2].2);
+
+        // Verify JSON content matches expected handles
+        for (i, (db_id, db_work_json, _)) in records.iter().enumerate() {
+            assert!(*db_id > 0);
+            let stored_work: HandleResolutionWork = serde_json::from_str(db_work_json)
+                .expect("Failed to deserialize stored work");
+            assert_eq!(stored_work.handle, handles[i]);
+        }
+
+        // Verify depth
+        assert_eq!(adapter.depth().await, Some(3));
+
+        // Pull items in FIFO order and verify database state changes
+        for (i, expected_handle) in handles.iter().enumerate() {
+            let pulled = adapter.pull().await;
+            assert!(pulled.is_some());
+            let pulled_work = pulled.unwrap();
+            assert_eq!(pulled_work.handle, *expected_handle);
+            
+            // Verify database now has one fewer record
+            let remaining_count: i64 = sqlx::query_scalar(
+                "SELECT COUNT(*) FROM handle_resolution_queue"
+            )
+            .fetch_one(&pool)
+            .await
+            .expect("Failed to count remaining records");
+            assert_eq!(remaining_count, (handles.len() - i - 1) as i64);
+            
+            // Ack the item (no-op)
+            adapter.ack(&pulled_work).await.expect("Ack should succeed");
+        }
+
+        // Verify queue is empty in both adapter and database
+        assert_eq!(adapter.depth().await, Some(0));
+        
+        let final_records: Vec<(i64, String, i64)> = sqlx::query_as(
+            "SELECT id, work, queued_at FROM handle_resolution_queue"
+        )
+        .fetch_all(&pool)
+        .await
+        .expect("Failed to query database");
+        assert_eq!(final_records.len(), 0);
+
+        let empty_pull = adapter.pull().await;
+        assert!(empty_pull.is_none());
+    }
+
+    #[tokio::test]
+    async fn test_sqlite_queue_adapter_simple_pull_delete() {
+        // Create in-memory SQLite database for testing
+        let pool = sqlx::SqlitePool::connect("sqlite::memory:")
+            .await
+            .expect("Failed to connect to in-memory SQLite");
+
+        // Create the queue schema
+        crate::sqlite_schema::create_schema(&pool)
+            .await
+            .expect("Failed to create schema");
+
+        let adapter = Arc::new(SqliteQueueAdapter::<HandleResolutionWork>::new(pool.clone()));
+
+        let test_handle = "simple.example.com";
+        let work = HandleResolutionWork {
+            handle: test_handle.to_string(),
+        };
+
+        // Push item
+        adapter.push(work.clone()).await.unwrap();
+
+        // Verify the record exists in database with correct JSON
+        let records: Vec<(i64, String, i64)> = sqlx::query_as(
+            "SELECT id, work, queued_at FROM handle_resolution_queue"
+        )
+        .fetch_all(&pool)
+        .await
+        .expect("Failed to query database");
+
+        assert_eq!(records.len(), 1);
+        let (db_id, db_work_json, db_queued_at) = &records[0];
+        assert!(*db_id > 0);
+        assert!(*db_queued_at > 0);
+        
+        // Verify JSON content
+        let stored_work: HandleResolutionWork = serde_json::from_str(db_work_json)
+            .expect("Failed to deserialize stored work");
+        assert_eq!(stored_work.handle, test_handle);
+        
+        // Verify item is in queue using schema stats
+        let total_before = crate::sqlite_schema::get_queue_stats(&pool)
+            .await
+            .expect("Failed to get queue stats");
+        assert_eq!(total_before, 1);
+
+        // Pull item (should delete it immediately)
+        let pulled = adapter.pull().await;
+        assert!(pulled.is_some());
+        let pulled_work = pulled.unwrap();
+        assert_eq!(pulled_work.handle, test_handle);
+
+        // Verify the record was deleted from database
+        let records_after_pull: Vec<(i64, String, i64)> = sqlx::query_as(
+            "SELECT id, work, queued_at FROM handle_resolution_queue"
+        )
+        .fetch_all(&pool)
+        .await
+        .expect("Failed to query database after pull");
+        assert_eq!(records_after_pull.len(), 0);
+
+        // Verify that pulling again returns None (no records left)
+        let empty_pull = adapter.pull().await;
+        assert!(empty_pull.is_none());
+
+        // Verify queue is now empty after pull using schema stats
+        let total_after = crate::sqlite_schema::get_queue_stats(&pool)
+            .await
+            .expect("Failed to get queue stats");
+        assert_eq!(total_after, 0);
+
+        // Ack the item (should be no-op)
+        adapter.ack(&pulled_work).await.expect("Ack should succeed");
+
+        // Verify queue is still empty using schema stats
+        let total_final = crate::sqlite_schema::get_queue_stats(&pool)
+            .await
+            .expect("Failed to get queue stats after ack");
+        assert_eq!(total_final, 0);
+    }
+
+    #[tokio::test]
+    async fn test_sqlite_queue_adapter_health() {
+        // Create in-memory SQLite database for testing
+        let pool = sqlx::SqlitePool::connect("sqlite::memory:")
+            .await
+            .expect("Failed to connect to in-memory SQLite");
+
+        // Create the queue schema
+        crate::sqlite_schema::create_schema(&pool)
+            .await
+            .expect("Failed to create schema");
+
+        let adapter = Arc::new(SqliteQueueAdapter::<HandleResolutionWork>::new(pool));
+
+        // Should be healthy if SQLite is working
+        assert!(adapter.is_healthy().await);
+    }
+
+    #[tokio::test]
+    async fn test_sqlite_queue_adapter_ack_no_op() {
+        // Create in-memory SQLite database for testing
+        let pool = sqlx::SqlitePool::connect("sqlite::memory:")
+            .await
+            .expect("Failed to connect to in-memory SQLite");
+
+        // Create the queue schema
+        crate::sqlite_schema::create_schema(&pool)
+            .await
+            .expect("Failed to create schema");
+
+        let adapter = Arc::new(SqliteQueueAdapter::<HandleResolutionWork>::new(pool));
+
+        // Ack should always succeed as it's a no-op
+        let any_work = HandleResolutionWork {
+            handle: "any.example.com".to_string(),
+        };
+
+        let result = adapter.ack(&any_work).await;
+        assert!(result.is_ok());
+    }
+
+    #[tokio::test]
+    async fn test_sqlite_queue_adapter_generic_work_type() {
+        // Test with a different work type to demonstrate genericity
+        #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+        struct CustomWork {
+            id: u64,
+            name: String,
+            data: Vec<i32>,
+        }
+
+        // Create in-memory SQLite database for testing
+        let pool = sqlx::SqlitePool::connect("sqlite::memory:")
+            .await
+            .expect("Failed to connect to in-memory SQLite");
+
+        // Create the queue schema
+        crate::sqlite_schema::create_schema(&pool)
+            .await
+            .expect("Failed to create schema");
+
+        let adapter = Arc::new(SqliteQueueAdapter::<CustomWork>::new(pool.clone()));
+
+        // Create custom work items
+        let work1 = CustomWork {
+            id: 123,
+            name: "test_work".to_string(),
+            data: vec![1, 2, 3, 4, 5],
+        };
+
+        let work2 = CustomWork {
+            id: 456,
+            name: "another_work".to_string(),
+            data: vec![10, 20],
+        };
+
+        // Test push for both items
+        adapter.push(work1.clone()).await.unwrap();
+        adapter.push(work2.clone()).await.unwrap();
+
+        // Verify the records are in database with correct JSON serialization
+        let records: Vec<(i64, String, i64)> = sqlx::query_as(
+            "SELECT id, work, queued_at FROM handle_resolution_queue ORDER BY queued_at ASC"
+        )
+        .fetch_all(&pool)
+        .await
+        .expect("Failed to query database");
+
+        assert_eq!(records.len(), 2);
+
+        // Verify first work item JSON
+        let stored_work1: CustomWork = serde_json::from_str(&records[0].1)
+            .expect("Failed to deserialize first work item");
+        assert_eq!(stored_work1, work1);
+        
+        // Verify the JSON contains all expected fields
+        let json_value1: serde_json::Value = serde_json::from_str(&records[0].1)
+            .expect("Failed to parse JSON");
+        assert_eq!(json_value1["id"], 123);
+        assert_eq!(json_value1["name"], "test_work");
+        assert_eq!(json_value1["data"], serde_json::json!([1, 2, 3, 4, 5]));
+
+        // Verify second work item JSON
+        let stored_work2: CustomWork = serde_json::from_str(&records[1].1)
+            .expect("Failed to deserialize second work item");
+        assert_eq!(stored_work2, work2);
+        
+        let json_value2: serde_json::Value = serde_json::from_str(&records[1].1)
+            .expect("Failed to parse JSON");
+        assert_eq!(json_value2["id"], 456);
+        assert_eq!(json_value2["name"], "another_work");
+        assert_eq!(json_value2["data"], serde_json::json!([10, 20]));
+
+        // Verify depth
+        assert_eq!(adapter.depth().await, Some(2));
+
+        // Test pull - should get items in FIFO order
+        let pulled1 = adapter.pull().await;
+        assert!(pulled1.is_some());
+        let pulled_work1 = pulled1.unwrap();
+        assert_eq!(pulled_work1, work1);
+
+        // Verify database now has one record
+        let count_after_first_pull: i64 = sqlx::query_scalar(
+            "SELECT COUNT(*) FROM handle_resolution_queue"
+        )
+        .fetch_one(&pool)
+        .await
+        .expect("Failed to count records");
+        assert_eq!(count_after_first_pull, 1);
+
+        let pulled2 = adapter.pull().await;
+        assert!(pulled2.is_some());
+        let pulled_work2 = pulled2.unwrap();
+        assert_eq!(pulled_work2, work2);
+
+        // Verify database is now empty
+        let count_after_second_pull: i64 = sqlx::query_scalar(
+            "SELECT COUNT(*) FROM handle_resolution_queue"
+        )
+        .fetch_one(&pool)
+        .await
+        .expect("Failed to count records");
+        assert_eq!(count_after_second_pull, 0);
+
+        // Verify queue is empty
+        assert_eq!(adapter.depth().await, Some(0));
+        let empty_pull = adapter.pull().await;
+        assert!(empty_pull.is_none());
+
+        // Test ack (should be no-op)
+        adapter.ack(&pulled_work1).await.expect("Ack should succeed");
+        adapter.ack(&pulled_work2).await.expect("Ack should succeed");
+    }
+
+    #[tokio::test]
+    async fn test_sqlite_queue_adapter_work_shedding() {
+        // Create in-memory SQLite database for testing
+        let pool = sqlx::SqlitePool::connect("sqlite::memory:")
+            .await
+            .expect("Failed to connect to in-memory SQLite");
+
+        // Create the queue schema
+        crate::sqlite_schema::create_schema(&pool)
+            .await
+            .expect("Failed to create schema");
+
+        // Create adapter with small max_size for testing work shedding
+        let max_size = 10; // Use larger size to properly test batch deletion
+        let adapter = Arc::new(SqliteQueueAdapter::<HandleResolutionWork>::with_max_size(
+            pool.clone(), 
+            max_size
+        ));
+
+        // Verify initial empty state
+        assert_eq!(adapter.depth().await, Some(0));
+
+        // Push items up to the limit (should not trigger shedding)
+        let mut handles = Vec::new();
+        for i in 0..max_size {
+            let handle = format!("test-{:03}", i);
+            handles.push(handle.clone());
+            let work = HandleResolutionWork { handle };
+            adapter.push(work).await.expect("Push should succeed");
+        }
+
+        // Verify all items are present
+        assert_eq!(adapter.depth().await, Some(max_size as usize));
+        
+        // Push beyond 110% of max_size to trigger batch shedding
+        // The implementation checks at 110% and deletes down to 80%
+        let trigger_point = max_size + (max_size / 10) + 1;
+        for i in max_size..trigger_point {
+            let handle = format!("test-{:03}", i);
+            handles.push(handle);
+            let work = HandleResolutionWork { handle: handles[i as usize].clone() };
+            adapter.push(work).await.expect("Push should succeed");
+        }
+
+        // After triggering shedding, queue should be around 80% of max_size
+        let depth_after_shedding = adapter.depth().await.unwrap();
+        let expected_size = (max_size as f64 * 0.8) as usize;
+        
+        // Allow some variance due to batch deletion
+        assert!(
+            depth_after_shedding <= expected_size + 1,
+            "Queue size {} should be around 80% of max_size ({})",
+            depth_after_shedding,
+            expected_size
+        );
+
+        // Verify oldest items were deleted and newest items remain
+        let records: Vec<(i64, String, i64)> = sqlx::query_as(
+            "SELECT id, work, queued_at FROM handle_resolution_queue ORDER BY queued_at ASC"
+        )
+        .fetch_all(&pool)
+        .await
+        .expect("Failed to query database after shedding");
+        
+        // Some of the oldest items should be gone (but not necessarily all the first ones)
+        // With batch deletion to 80%, we keep recent items
+        let last_item: HandleResolutionWork = serde_json::from_str(&records[records.len() - 1].1)
+            .expect("Failed to deserialize last work");
+        // Should have the most recent items
+        assert!(last_item.handle.starts_with("test-01"), "Should have recent items");
+        
+        // Verify FIFO order is maintained for remaining items
+        let mut prev_id = 0;
+        for record in &records {
+            let id: i64 = record.0;
+            assert!(id > prev_id, "IDs should be in ascending order");
+            prev_id = id;
+        }
+    }
+
+    #[tokio::test]
+    async fn test_sqlite_queue_adapter_work_shedding_disabled() {
+        // Create in-memory SQLite database for testing
+        let pool = sqlx::SqlitePool::connect("sqlite::memory:")
+            .await
+            .expect("Failed to connect to in-memory SQLite");
+
+        // Create the queue schema
+        crate::sqlite_schema::create_schema(&pool)
+            .await
+            .expect("Failed to create schema");
+
+        // Create adapter with max_size = 0 (disabled work shedding)
+        let adapter = Arc::new(SqliteQueueAdapter::<HandleResolutionWork>::with_max_size(
+            pool.clone(), 
+            0
+        ));
+
+        // Push many items (should not trigger any shedding)
+        let mut expected_handles = Vec::new();
+        for i in 0..100 {
+            let handle = format!("test-{:03}", i);
+            expected_handles.push(handle.clone());
+            let work = HandleResolutionWork { handle };
+            adapter.push(work).await.expect("Push should succeed");
+        }
+
+        // Verify all items are present (no shedding occurred)
+        assert_eq!(adapter.depth().await, Some(100));
+        
+        // Verify all items are in database
+        let records: Vec<(i64, String, i64)> = sqlx::query_as(
+            "SELECT id, work, queued_at FROM handle_resolution_queue ORDER BY queued_at ASC"
+        )
+        .fetch_all(&pool)
+        .await
+        .expect("Failed to query database");
+
+        assert_eq!(records.len(), 100);
+        
+        // Verify all items are present in correct order
+        for (i, expected_handle) in expected_handles.iter().enumerate() {
+            let stored_work: HandleResolutionWork = serde_json::from_str(&records[i].1)
+                .expect("Failed to deserialize stored work");
+            assert_eq!(stored_work.handle, *expected_handle);
+        }
+    }
+
+    #[tokio::test]
+    async fn test_sqlite_queue_adapter_performance_optimizations() {
+        // Create in-memory SQLite database for testing
+        let pool = sqlx::SqlitePool::connect("sqlite::memory:")
+            .await
+            .expect("Failed to connect to in-memory SQLite");
+
+        // Create the queue schema
+        crate::sqlite_schema::create_schema(&pool)
+            .await
+            .expect("Failed to create schema");
+
+        // Create adapter with reasonable max_size
+        let max_size = 100;
+        let adapter = Arc::new(SqliteQueueAdapter::<HandleResolutionWork>::with_max_size(
+            pool.clone(), 
+            max_size
+        ));
+
+        // Test 1: Verify inserts don't trigger checks when well under limit
+        // Push 50 items (50% of max_size) - should not trigger any cleanup checks
+        for i in 0..50 {
+            let work = HandleResolutionWork {
+                handle: format!("handle-{:04}", i),
+            };
+            adapter.push(work).await.expect("Push should succeed");
+        }
+        assert_eq!(adapter.depth().await, Some(50));
+
+        // Test 2: Verify batch deletion efficiency
+        // Push to 110% to trigger batch cleanup
+        for i in 50..111 {
+            let work = HandleResolutionWork {
+                handle: format!("handle-{:04}", i),
+            };
+            adapter.push(work).await.expect("Push should succeed");
+            // Add tiny delay to ensure different timestamps for proper ordering
+            if i % 10 == 0 {
+                tokio::time::sleep(tokio::time::Duration::from_millis(1)).await;
+            }
+        }
+
+        // Should have deleted down to ~80% of max_size
+        let depth_after_batch = adapter.depth().await.unwrap();
+        assert!(
+            (79..=81).contains(&depth_after_batch),
+            "After batch deletion, size should be ~80 (got {})",
+            depth_after_batch
+        );
+
+        // Test 3: Verify cleanup doesn't happen again immediately
+        // Push a few more items - should not trigger another cleanup
+        for i in 111..115 {
+            let work = HandleResolutionWork {
+                handle: format!("handle-{:04}", i),
+            };
+            adapter.push(work).await.expect("Push should succeed");
+        }
+
+        let depth_no_cleanup = adapter.depth().await.unwrap();
+        assert!(
+            depth_no_cleanup > 80 && depth_no_cleanup < 90,
+            "Should not have triggered cleanup yet (got {})",
+            depth_no_cleanup
+        );
+
+        // Test 4: Verify timestamp-based deletion is working correctly
+        // The oldest items should be gone after batch deletion
+        let records: Vec<(i64, String, i64)> = sqlx::query_as(
+            "SELECT id, work, queued_at FROM handle_resolution_queue 
+             ORDER BY queued_at ASC LIMIT 5"
+        )
+        .fetch_all(&pool)
+        .await
+        .expect("Failed to query database");
+
+        // Verify we have recent items (not necessarily the oldest)
+        let oldest_work: HandleResolutionWork = serde_json::from_str(&records[0].1)
+            .expect("Failed to deserialize work");
+        let oldest_num: i32 = oldest_work.handle
+            .trim_start_matches("handle-")
+            .parse()
+            .unwrap_or(0);
+        
+        // After batch deletion to 80%, we should have deleted approximately the first 31 items
+        // But allow some variance due to timing
+        assert!(
+            oldest_num >= 20,
+            "Should have deleted old items, oldest is now: {}",
+            oldest_work.handle
+        );
+
+        // Test 5: Verify FIFO order is maintained after batch operations
+        let mut prev_timestamp = 0i64;
+        let all_records: Vec<(i64, String, i64)> = sqlx::query_as(
+            "SELECT id, work, queued_at FROM handle_resolution_queue ORDER BY queued_at ASC"
+        )
+        .fetch_all(&pool)
+        .await
+        .expect("Failed to query database");
+
+        for record in &all_records {
+            assert!(
+                record.2 >= prev_timestamp,
+                "Timestamps should be in ascending order"
+            );
+            prev_timestamp = record.2;
+        }
     }
 }

src/sqlite_schema.rs

···
 ON handle_resolution_cache(updated);
 "#;
 
+/// SQL schema for the handle resolution queue table.
+const CREATE_HANDLE_RESOLUTION_QUEUE_TABLE: &str = r#"
+CREATE TABLE IF NOT EXISTS handle_resolution_queue (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    work TEXT NOT NULL,
+    queued_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_handle_resolution_queue_queued_at 
+ON handle_resolution_queue(queued_at);
+"#;
+
 /// Create or connect to a SQLite database and ensure schema is initialized.
 ///
 /// # Arguments
···
     tracing::info!("Initializing SQLite database: {}", database_url);
 
     // Extract the database path from the URL for file-based databases
-    if let Some(path) = database_url.strip_prefix("sqlite:") {
-        if path != ":memory:" && !path.is_empty() {
-            // Create the database file if it doesn't exist
-            if !Sqlite::database_exists(database_url).await? {
-                tracing::info!("Creating SQLite database file: {}", path);
-                Sqlite::create_database(database_url).await?;
-            }
+    if let Some(path) = database_url.strip_prefix("sqlite:") 
+        && path != ":memory:" 
+        && !path.is_empty() 
+    {
+        // Create the database file if it doesn't exist
+        if !Sqlite::database_exists(database_url).await? {
+            tracing::info!("Creating SQLite database file: {}", path);
+            Sqlite::create_database(database_url).await?;
+        }
 
-            // Ensure the parent directory exists
-            if let Some(parent) = Path::new(path).parent() {
-                if !parent.exists() {
-                    tracing::info!("Creating directory: {}", parent.display());
-                    std::fs::create_dir_all(parent)?;
-                }
-            }
+        // Ensure the parent directory exists
+        if let Some(parent) = Path::new(path).parent() 
+            && !parent.exists() 
+        {
+            tracing::info!("Creating directory: {}", parent.display());
+            std::fs::create_dir_all(parent)?;
         }
     }
 
···
 
     // Execute the schema creation SQL
     sqlx::query(CREATE_HANDLE_RESOLUTION_CACHE_TABLE)
+        .execute(pool)
+        .await?;
+    
+    sqlx::query(CREATE_HANDLE_RESOLUTION_QUEUE_TABLE)
         .execute(pool)
         .await?;
 
···
     let size_bytes = page_size * page_count;
 
     Ok((total_entries, size_bytes))
+}
+
+/// Clean up old entries from the handle resolution queue.
+///
+/// This function removes entries that are older than the specified age.
+///
+/// # Arguments
+///
+/// * `pool` - SQLite connection pool
+/// * `max_age_seconds` - Maximum age in seconds for queue entries to be kept
+///
+/// # Returns
+///
+/// Returns the number of entries deleted.
+///
+/// # Example
+///
+/// ```no_run
+/// use quickdid::sqlite_schema::cleanup_queue_entries;
+/// use sqlx::SqlitePool;
+///
+/// # async fn example() -> anyhow::Result<()> {
+/// let pool = SqlitePool::connect("sqlite:./quickdid.db").await?;
+/// let deleted_count = cleanup_queue_entries(&pool, 86400).await?; // 1 day
+/// println!("Deleted {} old queue entries", deleted_count);
+/// # Ok(())
+/// # }
+/// ```
+pub async fn cleanup_queue_entries(pool: &SqlitePool, max_age_seconds: u64) -> Result<u64> {
+    let current_timestamp = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs() as i64;
+
+    let cutoff_timestamp = current_timestamp - (max_age_seconds as i64);
+
+    let result = sqlx::query(
+        "DELETE FROM handle_resolution_queue WHERE queued_at < ?1"
+    )
+    .bind(cutoff_timestamp)
+    .execute(pool)
+    .await?;
+
+    let deleted_count = result.rows_affected();
+    if deleted_count > 0 {
+        tracing::info!("Cleaned up {} old queue entries", deleted_count);
+    }
+
+    Ok(deleted_count)
+}
+
+/// Get statistics about the handle resolution queue.
+///
+/// # Arguments
+///
+/// * `pool` - SQLite connection pool
+///
+/// # Returns
+///
+/// Returns the total number of entries in the queue.
+///
+/// # Example
+///
+/// ```no_run
+/// use quickdid::sqlite_schema::get_queue_stats;
+/// use sqlx::SqlitePool;
+///
+/// # async fn example() -> anyhow::Result<()> {
+/// let pool = SqlitePool::connect("sqlite:./quickdid.db").await?;
+/// let total = get_queue_stats(&pool).await?;
+/// println!("Queue: {} total entries", total);
+/// # Ok(())
+/// # }
+/// ```
+pub async fn get_queue_stats(pool: &SqlitePool) -> Result<i64> {
+    // Get total entries
+    let total_entries: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM handle_resolution_queue")
+        .fetch_one(pool)
+        .await?;
+
+    Ok(total_entries)
 }
 
 #[cfg(test)]

src/test_helpers.rs

···
 //! Test helper utilities for QuickDID tests
-#![cfg(test)]
 
 use crate::cache::create_redis_pool;
 use deadpool_redis::Pool;