docs: add module-level documentation comments to all source files

Add descriptive module-level documentation comments to clearly explain the purpose and functionality of each module in the codebase. This improves code discoverability and maintainability.

src/cache.rs

···
+//! In-memory cache for bundle operations with simple capacity-based eviction
 // src/cache.rs
 use crate::operations::Operation;
 use std::collections::HashMap;

src/constants.rs

···
+//! Global constants and helpers for filenames/paths, networking defaults, compression, index settings, and position conversions
 // Constants for version and binary identification
 use std::path::{Path, PathBuf};
 

src/did_index.rs

···
+//! Memory-mapped DID index with 256 shards and delta segments; packed `OpLocation` encodes global position and nullified flag; supports build, verify, repair, and sampling
 // Simplified DID Index implementation matching Go version
 use crate::constants;
 use anyhow::{Context, Result};

src/ffi.rs

···
+//! C-compatible FFI surface exposing BundleManager and related types for integration from other languages
 use crate::constants;
 use crate::manager::*;
 use crate::operations::*;

src/format.rs

···
+//! Formatting helpers for bytes, durations, rates, and numbers used across CLI/server/library components
 // Shared formatting helpers used across CLI/server/library components.
 
 use chrono::Duration as ChronoDuration;

src/handle_resolver.rs

···
+//! AT Protocol handle resolver client using XRPC; includes validation and normalization helpers
 // Handle resolver - resolves AT Protocol handles to DIDs via XRPC
 
 use crate::constants;

src/index.rs

···
+//! Bundle repository index: load/save, sequence validation, and rebuild from bundle metadata
 // Replace your current src/index.rs with this:
 
 use anyhow::Result;

src/iterators.rs

···
+//! Iterators for traversing bundles and operations: range iteration and streaming export
 // src/iterators.rs
 use crate::manager::{BundleManager, ExportSpec, LoadOptions, QuerySpec};
 use crate::operations::{Operation, OperationFilter};

src/manager.rs

···
+//! High-level manager orchestrating loading, random access, DID resolution, querying/export, sync, verification, rollback/migration, and mempool management
 // src/manager.rs
 use crate::constants::{self, bundle_position_to_global, total_operations_from_bundles};
 use crate::index::{BundleMetadata, Index};

src/mempool.rs

···
+//! Persistent pre-bundle operation store with strict chronological validation, CID deduplication, incremental saving, and fast DID lookups
 // src/mempool.rs
 use crate::constants;
 use crate::operations::Operation;

src/operations.rs

···
+//! Core PLC operation model backed by `sonic_rs`; preserves raw JSON for deterministic hashing; includes filters, requests, and location wrapper
 // src/operations.rs
 use serde::{Deserialize, Serialize};
 use sonic_rs::{self, Value};

src/options.rs

···
+//! Processor options and builder, including `QueryMode` for simple path vs JMESPath queries
 use std::path::PathBuf;
 
 /// Configuration options for the PLC bundle processor

src/plc_client.rs

···
+//! Rate-limited HTTP client for PLC directory: fetch operations and DID documents with retries/backoff and token-bucket limiting
 // PLC Client - HTTP client for interacting with PLC directory APIs
 use crate::constants;
 use crate::resolver::DIDDocument;

src/processor.rs

···
+//! Query engine and processor supporting simple path and JMESPath queries with parallel bundle processing and batched output
 use crate::constants;
 use crate::index::Index;
 use crate::options::{Options, QueryMode};

src/remote.rs

···
-// Remote access module for fetching data from remote plcbundle instances
+//! Remote client for plcbundle instances: fetch index, bundles, operations, and DID documents; includes local index loader and URL normalization
 // This module is for fetching from other plcbundle repositories, not from PLC directory
 use crate::constants;
 use crate::index::Index;

src/resolver.rs

···
+//! DID resolution: build PLC DID state and convert to W3C DID Documents; handles legacy fields and endpoint normalization
 // DID Resolution - Convert PLC operations to W3C DID Documents
 use crate::operations::Operation;
 use anyhow::Result;

src/runtime.rs

···
+//! Graceful shutdown coordination for server and background tasks, with unified shutdown future and fatal-error handling
 // Runtime module - shutdown coordination for server and background tasks
 use tokio::signal;
 use tokio::sync::watch;

src/sync.rs

···
+
+//! PLC synchronization: events and logger, boundary-CID deduplication, one-shot and continuous modes, and robust error/backoff handling
 
 // Sync module - PLC directory synchronization
 use crate::constants;

src/verification.rs

···
+//! Bundle and chain verification: fast metadata checks, compressed/content hash validation, operation count checks, and parent/cursor linkage
 // src/verification.rs
 use crate::bundle_format;
 use crate::constants;