server debug endpoints

README.md

···
 
 ```bash
 # Fetch bundles from plc.directory
-plcbundle fetch
+plcbundle sync
 
 # Clone from remote
 plcbundle clone https://plc.example.com

bundle/manager.go

···
 	"sort"
 	"strings"
 	"sync"
+	"sync/atomic"
 	"time"
 
 	"tangled.org/atscan.net/plcbundle/internal/bundleindex"
···
 	bundleCache  map[int]*Bundle
 	cacheMu      sync.RWMutex
 	maxCacheSize int
+
+	// NEW: Resolver performance tracking
+	resolverStats struct {
+		sync.Mutex
+		totalResolutions int64
+		mempoolHits      int64
+		bundleHits       int64
+		errors           int64
+
+		// Timing (in microseconds)
+		totalTime        int64
+		totalMempoolTime int64
+		totalIndexTime   int64
+		totalLoadOpTime  int64
+
+		// Recent timings (circular buffer)
+		recentTimes []resolverTiming
+		recentIdx   int
+		recentSize  int
+	}
 }
 
 // NewManager creates a new bundle manager
···
 		handleResolver = handleresolver.NewClient(config.HandleResolverURL)
 	}
 
-	return &Manager{
+	m := &Manager{
 		config:         config,
 		operations:     ops,
 		index:          index,
···
 		cloner:         cloner,
 		plcClient:      plcClient,
 		handleResolver: handleResolver,
-	}, nil
+	}
+	// Initialize resolver stats
+	m.resolverStats.recentSize = 1000
+	m.resolverStats.recentTimes = make([]resolverTiming, 1000)
+
+	return m, nil
 }
 
 // Close cleans up resources
···
 // ResolveDID resolves a DID to its current document with detailed timing metrics
 func (m *Manager) ResolveDID(ctx context.Context, did string) (*ResolveDIDResult, error) {
 	if err := plcclient.ValidateDIDFormat(did); err != nil {
+		// Track error
+		atomic.AddInt64(&m.resolverStats.errors, 1)
 		return nil, err
 	}
 
···
 
 	var latestMempoolOp *plcclient.PLCOperation
 	if m.mempool != nil {
-		// Fast backwards search with early exit
 		latestMempoolOp = m.mempool.FindLatestDIDOperation(did)
 	}
 	result.MempoolTime = time.Since(mempoolStart)
···
 	if latestMempoolOp != nil {
 		doc, err := plcclient.ResolveDIDDocument(did, []plcclient.PLCOperation{*latestMempoolOp})
 		if err != nil {
+			atomic.AddInt64(&m.resolverStats.errors, 1)
 			return nil, fmt.Errorf("resolution failed: %w", err)
 		}
 
 		result.Document = doc
 		result.Source = "mempool"
 		result.TotalTime = time.Since(totalStart)
+
+		// Record stats
+		m.recordResolverTiming(result, nil)
+
 		return result, nil
 	}
 
 	// STEP 2: Index lookup
 	if m.didIndex == nil || !m.didIndex.Exists() {
+		atomic.AddInt64(&m.resolverStats.errors, 1)
 		return nil, fmt.Errorf("DID index not available - run 'plcbundle index build' to enable DID resolution")
 	}
 
···
 	result.IndexTime = time.Since(indexStart)
 
 	if err != nil {
+		atomic.AddInt64(&m.resolverStats.errors, 1)
 		return nil, err
 	}
 
 	if len(locations) == 0 {
+		atomic.AddInt64(&m.resolverStats.errors, 1)
 		return nil, fmt.Errorf("DID not found")
 	}
 
···
 	}
 
 	if latestLoc == nil {
+		atomic.AddInt64(&m.resolverStats.errors, 1)
 		return nil, fmt.Errorf("no valid operations (all nullified)")
 	}
 
···
 	result.LoadOpTime = time.Since(opStart)
 
 	if err != nil {
+		atomic.AddInt64(&m.resolverStats.errors, 1)
 		return nil, fmt.Errorf("failed to load operation: %w", err)
 	}
 
···
 	// STEP 4: Resolve document
 	doc, err := plcclient.ResolveDIDDocument(did, []plcclient.PLCOperation{*op})
 	if err != nil {
+		atomic.AddInt64(&m.resolverStats.errors, 1)
 		return nil, fmt.Errorf("resolution failed: %w", err)
 	}
 
 	result.Document = doc
 	result.Source = "bundle"
 	result.TotalTime = time.Since(totalStart)
+
+	// Record stats
+	m.recordResolverTiming(result, nil)
 
 	return result, nil
 }
···
 func (m *Manager) GetHandleResolver() *handleresolver.Client {
 	return m.handleResolver
 }
+
+// recordResolverTiming records resolver performance metrics
+func (m *Manager) recordResolverTiming(result *ResolveDIDResult, _ error) {
+	m.resolverStats.Lock()
+	defer m.resolverStats.Unlock()
+
+	// Increment counters
+	atomic.AddInt64(&m.resolverStats.totalResolutions, 1)
+
+	switch result.Source {
+	case "mempool":
+		atomic.AddInt64(&m.resolverStats.mempoolHits, 1)
+	case "bundle":
+		atomic.AddInt64(&m.resolverStats.bundleHits, 1)
+	}
+
+	// Record timings
+	timing := resolverTiming{
+		totalTime:   result.TotalTime.Microseconds(),
+		mempoolTime: result.MempoolTime.Microseconds(),
+		indexTime:   result.IndexTime.Microseconds(),
+		loadOpTime:  result.LoadOpTime.Microseconds(),
+		source:      result.Source,
+	}
+
+	atomic.AddInt64(&m.resolverStats.totalTime, timing.totalTime)
+	atomic.AddInt64(&m.resolverStats.totalMempoolTime, timing.mempoolTime)
+	atomic.AddInt64(&m.resolverStats.totalIndexTime, timing.indexTime)
+	atomic.AddInt64(&m.resolverStats.totalLoadOpTime, timing.loadOpTime)
+
+	// Add to circular buffer
+	m.resolverStats.recentTimes[m.resolverStats.recentIdx] = timing
+	m.resolverStats.recentIdx = (m.resolverStats.recentIdx + 1) % m.resolverStats.recentSize
+}
+
+// GetResolverStats returns resolver performance statistics
+func (m *Manager) GetResolverStats() map[string]interface{} {
+	totalResolutions := atomic.LoadInt64(&m.resolverStats.totalResolutions)
+
+	if totalResolutions == 0 {
+		return map[string]interface{}{
+			"total_resolutions": 0,
+		}
+	}
+
+	mempoolHits := atomic.LoadInt64(&m.resolverStats.mempoolHits)
+	bundleHits := atomic.LoadInt64(&m.resolverStats.bundleHits)
+	errors := atomic.LoadInt64(&m.resolverStats.errors)
+
+	totalTime := atomic.LoadInt64(&m.resolverStats.totalTime)
+	totalMempoolTime := atomic.LoadInt64(&m.resolverStats.totalMempoolTime)
+	totalIndexTime := atomic.LoadInt64(&m.resolverStats.totalIndexTime)
+	totalLoadOpTime := atomic.LoadInt64(&m.resolverStats.totalLoadOpTime)
+
+	// Calculate overall averages
+	avgTotalMs := float64(totalTime) / float64(totalResolutions) / 1000.0
+	avgMempoolMs := float64(totalMempoolTime) / float64(totalResolutions) / 1000.0
+
+	stats := map[string]interface{}{
+		"total_resolutions": totalResolutions,
+		"mempool_hits":      mempoolHits,
+		"bundle_hits":       bundleHits,
+		"errors":            errors,
+		"success_rate":      float64(totalResolutions-errors) / float64(totalResolutions),
+		"mempool_hit_rate":  float64(mempoolHits) / float64(totalResolutions),
+
+		// Overall averages
+		"avg_total_time_ms":   avgTotalMs,
+		"avg_mempool_time_ms": avgMempoolMs,
+	}
+
+	// Only include bundle-specific stats if we have bundle hits
+	if bundleHits > 0 {
+		avgIndexMs := float64(totalIndexTime) / float64(bundleHits) / 1000.0
+		avgLoadMs := float64(totalLoadOpTime) / float64(bundleHits) / 1000.0
+
+		stats["avg_index_time_ms"] = avgIndexMs
+		stats["avg_load_op_time_ms"] = avgLoadMs
+	}
+
+	// Recent statistics
+	m.resolverStats.Lock()
+	recentCopy := make([]resolverTiming, m.resolverStats.recentSize)
+	copy(recentCopy, m.resolverStats.recentTimes)
+	m.resolverStats.Unlock()
+
+	// Filter valid entries
+	validRecent := make([]resolverTiming, 0)
+	for _, t := range recentCopy {
+		if t.totalTime > 0 {
+			validRecent = append(validRecent, t)
+		}
+	}
+
+	if len(validRecent) > 0 {
+		// Extract total times for percentiles
+		totalTimes := make([]int64, len(validRecent))
+		for i, t := range validRecent {
+			totalTimes[i] = t.totalTime
+		}
+		sort.Slice(totalTimes, func(i, j int) bool {
+			return totalTimes[i] < totalTimes[j]
+		})
+
+		// Calculate recent average
+		var recentSum int64
+		var recentMempoolSum int64
+		var recentIndexSum int64
+		var recentLoadSum int64
+		recentBundleCount := 0
+
+		for _, t := range validRecent {
+			recentSum += t.totalTime
+			recentMempoolSum += t.mempoolTime
+			if t.source == "bundle" {
+				recentIndexSum += t.indexTime
+				recentLoadSum += t.loadOpTime
+				recentBundleCount++
+			}
+		}
+
+		stats["recent_avg_total_time_ms"] = float64(recentSum) / float64(len(validRecent)) / 1000.0
+		stats["recent_avg_mempool_time_ms"] = float64(recentMempoolSum) / float64(len(validRecent)) / 1000.0
+
+		if recentBundleCount > 0 {
+			stats["recent_avg_index_time_ms"] = float64(recentIndexSum) / float64(recentBundleCount) / 1000.0
+			stats["recent_avg_load_time_ms"] = float64(recentLoadSum) / float64(recentBundleCount) / 1000.0
+		}
+
+		stats["recent_sample_size"] = len(validRecent)
+
+		// Percentiles
+		p50idx := len(totalTimes) * 50 / 100
+		p95idx := len(totalTimes) * 95 / 100
+		p99idx := len(totalTimes) * 99 / 100
+
+		stats["min_total_time_ms"] = float64(totalTimes[0]) / 1000.0
+		stats["max_total_time_ms"] = float64(totalTimes[len(totalTimes)-1]) / 1000.0
+
+		if p50idx < len(totalTimes) {
+			stats["p50_total_time_ms"] = float64(totalTimes[p50idx]) / 1000.0
+		}
+		if p95idx < len(totalTimes) {
+			stats["p95_total_time_ms"] = float64(totalTimes[p95idx]) / 1000.0
+		}
+		if p99idx < len(totalTimes) {
+			stats["p99_total_time_ms"] = float64(totalTimes[p99idx]) / 1000.0
+		}
+	}
+
+	return stats
+}
+
+// ResetResolverStats resets resolver performance statistics
+func (m *Manager) ResetResolverStats() {
+	m.resolverStats.Lock()
+	defer m.resolverStats.Unlock()
+
+	atomic.StoreInt64(&m.resolverStats.totalResolutions, 0)
+	atomic.StoreInt64(&m.resolverStats.mempoolHits, 0)
+	atomic.StoreInt64(&m.resolverStats.bundleHits, 0)
+	atomic.StoreInt64(&m.resolverStats.errors, 0)
+	atomic.StoreInt64(&m.resolverStats.totalTime, 0)
+	atomic.StoreInt64(&m.resolverStats.totalMempoolTime, 0)
+	atomic.StoreInt64(&m.resolverStats.totalIndexTime, 0)
+	atomic.StoreInt64(&m.resolverStats.totalLoadOpTime, 0)
+
+	m.resolverStats.recentTimes = make([]resolverTiming, m.resolverStats.recentSize)
+	m.resolverStats.recentIdx = 0
+}

bundle/types.go

···
 	BundleNumber   int    // if from bundle
 	Position       int    // if from bundle
 }
+
+type resolverTiming struct {
+	totalTime   int64
+	mempoolTime int64
+	indexTime   int64
+	loadOpTime  int64
+	source      string // "mempool" or "bundle"
+}

cmd/plcbundle/commands/did.go

···
 	return nil
 }
 
-func displayLookupResults(did string, opsWithLoc []PLCOperationWithLocation, mempoolOps []plcclient.PLCOperation, totalElapsed, lookupElapsed, mempoolElapsed time.Duration, verbose bool, stats map[string]interface{}) error {
+func displayLookupResults(did string, opsWithLoc []PLCOperationWithLocation, mempoolOps []plcclient.PLCOperation, totalElapsed, lookupElapsed, mempoolElapsed time.Duration, verbose bool, _ map[string]interface{}) error {
 	nullifiedCount := 0
 	for _, owl := range opsWithLoc {
 		if owl.Operation.IsNullified() {

docs/cli.md

···
 # CLI Guide
 
-A concise guide to using the `plcbundle` command-line tool.
-
-## Installation
-
-```bash
-go install tangled.org/atscan.net/plcbundle/cmd/plcbundle@latest
-plcbundle version  # Verify installation
-```
-
-## Quick Start
-
-```bash
-mkdir plc_archive && cd plc_archive
-plcbundle fetch -count 1        # Fetch one bundle
-plcbundle info                  # Check what you have
-```
-
----
-
-## Commands
-
-### `fetch` - Download from PLC Directory
-
-Fetches operations from PLC directory and creates bundles.
-
-```bash
-plcbundle fetch -count 1        # Fetch exactly 1 bundle
-plcbundle fetch -count 10       # Fetch 10 bundles
-plcbundle fetch                 # Fetch continuously until caught up
-```
-
-**Important:** Without `-count`, fetch runs indefinitely. Always use `-count N` for controlled fetching.
-
-**Options:**
-- `-count N` - Number of bundles to fetch (0 = all available)
-- `-plc URL` - Custom PLC directory URL (default: `https://plc.directory`)
-
----
-
-### `clone` - Download from Remote Server
-
-Downloads pre-made bundles from another plcbundle server (much faster than fetch).
-
-```bash
-plcbundle clone https://plc.example.com
-plcbundle clone https://plc.example.com -workers 16    # Faster with more workers
-```
-
-**Resumable:** Press Ctrl+C to stop, run again to resume.
-
-**Options:**
-- `-workers N` - Concurrent downloads (default: 4)
-- `-v` - Verbose output
-- `-skip-existing` - Skip existing bundles (default: true)
-
----
-
-### `info` - View Archive Status
-
-Shows bundle count, storage size, time ranges, and chain hashes.
-
-```bash
-plcbundle info                  # General overview
-plcbundle info -bundle 42       # Specific bundle details
-plcbundle info --bundles        # List all bundles
-plcbundle info --verify         # Info + chain verification
-```
-
----
-
-### `verify` - Check Integrity
-
-Verifies file hashes and chain links.
-
-```bash
-plcbundle verify                # Verify entire chain
-plcbundle verify -bundle 42     # Verify one bundle
-plcbundle verify -v             # Verbose output
-```
-
----
-
-### `rebuild` - Recreate Index
-
-Scans bundle files and rebuilds `index.json`.
-
-```bash
-plcbundle rebuild               # Auto-detect CPU cores
-plcbundle rebuild -workers 8    # Use 8 workers
-```
-
-**When to use:**
-- Lost/corrupted `index.json`
-- Added bundle files manually
-- Moved files from another location
-
----
-
-### `export` - Extract Operations
-
-Exports operations as JSONL to stdout.
-
-```bash
-plcbundle export -count 1000 > ops.jsonl
-plcbundle export -after "2024-01-01T00:00:00Z" -count 5000 > jan.jsonl
-```
-
----
-
-### `backfill` - Stream All Operations
-
-Streams operations from all bundles, fetching missing ones on-demand.
-
-```bash
-plcbundle backfill > all.jsonl
-plcbundle backfill -start 100 -end 200 > range.jsonl
-```
-
----
-
-### `mempool` - Inspect Staging Area
-
-Shows operations waiting to form a bundle (need 10,000 to create bundle).
-
-```bash
-plcbundle mempool               # Show status
-plcbundle mempool -export > mem.jsonl    # Export mempool ops
-plcbundle mempool -validate     # Verify chronological order
-plcbundle mempool -clear        # Clear (destructive)
-```
-
----
-
-### `serve` - Run HTTP Server
-
-Starts an HTTP server to share bundles with others.
-
-```bash
-plcbundle serve                           # Start on :8080
-plcbundle serve -port 9000 -host 0.0.0.0  # Custom port/host
-plcbundle serve -sync -sync-interval 5m   # Auto-fetch new bundles
-plcbundle serve -websocket                # Enable WebSocket streaming
-```
-
-**Endpoints:**
-- `GET /` - Info page
-- `GET /index.json` - Bundle index
-- `GET /data/:number` - Download bundle
-- `WS /ws` - WebSocket stream (if enabled)
-
----
-
-### `compare` - Compare with Remote
-
-Shows differences between local and remote archives.
-
-```bash
-plcbundle compare https://plc.example.com
-plcbundle compare https://plc.example.com --fetch-missing  # Auto-fix
-```
-
----
-
-### `version` - Show Version
-
-```bash
-plcbundle version
-```
-
----
-
-## Important Concepts
-
-### Working Directory
-
-plcbundle operates in your **current directory**. Always `cd` to your archive first:
-
-```bash
-cd /path/to/plc_archive
-plcbundle info
-```
-
-### Files Created
-
-```
-plc_archive/
-├── 000001.jsonl.zst           # Bundle files (10k ops each)
-├── 000002.jsonl.zst
-├── index.json                 # Index (metadata + hashes)
-└── plc_mempool_*.jsonl        # Mempool (auto-managed, temporary)
-```
-
-### Fetch vs Clone
-
-**Use `fetch`** when:
-- No mirror available
-- Want data directly from PLC
-- Building from scratch
-
-**Use `clone`** when:
-- A mirror exists
-- Want faster setup
-- Syncing with known good source
-
----
-
-## Common Tasks
-
-**Initial setup from mirror:**
-```bash
-mkdir plc_archive && cd plc_archive
-plcbundle clone https://plc.example.com -workers 16
-plcbundle verify
-```
-
-**Initial setup from PLC:**
-```bash
-mkdir plc_archive && cd plc_archive
-plcbundle fetch -count 0  # Fetch all (can take hours)
-```
-
-**Daily sync (cron):**
-```bash
-#!/bin/bash
-cd /path/to/plc_archive
-plcbundle fetch -count 5  # Fetch up to 5 new bundles
-```
-
-**Share your archive:**
-```bash
-plcbundle serve -host 0.0.0.0 -sync
-```
-
-**Export recent data:**
-```bash
-plcbundle export -count 10000 > recent.jsonl
-cat recent.jsonl | jq .  # Process with jq
-```
-
-**Fix corrupted index:**
-```bash
-plcbundle rebuild
-plcbundle verify
-```
-
----
-
-## Troubleshooting
-
-**Command not found:**
-```bash
-export PATH=$PATH:$(go env GOPATH)/bin
-```
-
-**Wrong directory:**
-```bash
-pwd  # Check where you are
-cd /path/to/plc_archive
-```
-
-**Fetch doesn't create bundle:**
-```bash
-plcbundle mempool  # Check if waiting for more ops
-# Need 10,000 operations to create a bundle
-```
-
-**Port already in use:**
-```bash
-plcbundle serve -port 9000
-```
-
-**Hash verification failed:**
-```bash
-rm 000042.jsonl.zst       # Delete corrupted bundle
-plcbundle rebuild         # Mark as missing
-plcbundle fetch -count 1  # Re-fetch
-```
-
-**Out of disk space:**
-```bash
-df -h .  # Check space
-# Move to larger disk or delete old bundles
-```
-
----
-
-## Quick Reference
-
-```bash
-# Fetch
-plcbundle fetch -count 1              # One bundle
-plcbundle fetch                       # All available
-
-# Clone
-plcbundle clone <url>                 # From mirror
-plcbundle clone <url> -workers 16     # Faster
-
-# Info
-plcbundle info                        # Overview
-plcbundle info -bundle 42             # Specific bundle
-
-# Verify
-plcbundle verify                      # Check chain
-plcbundle verify -bundle 42           # Check one
-
-# Rebuild
-plcbundle rebuild                     # Recreate index
-
-# Export
-plcbundle export -count 1000 > ops.jsonl
-
-# Serve
-plcbundle serve                       # Share bundles
-plcbundle serve -sync -websocket      # Full-featured
-
-# Utilities
-plcbundle mempool                     # Check staging
-plcbundle compare <url>               # Compare with remote
-plcbundle backfill > all.jsonl        # Export all
-```
-
----
-
-## Getting Help
-
-```bash
-plcbundle <command> -h    # Command-specific help
-```
-
-**Report issues:** https://tangled.org/@atscan.net/plcbundle/issues
-
+TODO

docs/library.md

···
 
 ---
 
-## Getting Started
-
-### Installation
-
-```bash
-go get tangled.org/atscan.net/plcbundle
-```
-
-### Your First Program
-
-Create a simple program to fetch and display bundle information:
-
-```go
-package main
-
-import (
-    "context"
-    "log"
-    
-    plcbundle "tangled.org/atscan.net/plcbundle"
-)
-
-func main() {
-    // Create a manager
-    mgr, err := plcbundle.New("./plc_data", "https://plc.directory")
-    if err != nil {
-        log.Fatal(err)
-    }
-    defer mgr.Close()
-    
-    // Get repository info
-    info := mgr.GetInfo()
-    log.Printf("Bundle directory: %s", info["bundle_dir"])
-    
-    // Get index stats
-    index := mgr.GetIndex()
-    stats := index.GetStats()
-    log.Printf("Total bundles: %d", stats["bundle_count"])
-}
-```
-
-Run it:
-```bash
-go run main.go
-# 2025/01/15 10:30:00 Bundle directory: ./plc_data
-# 2025/01/15 10:30:00 Total bundles: 0
-```
-
-### Fetching Your First Bundle
-
-Let's fetch a bundle from the PLC directory:
-
-```go
-package main
-
-import (
-    "context"
-    "log"
-    
-    plcbundle "tangled.org/atscan.net/plcbundle"
-)
-
-func main() {
-    mgr, err := plcbundle.New("./plc_data", "https://plc.directory")
-    if err != nil {
-        log.Fatal(err)
-    }
-    defer mgr.Close()
-    
-    ctx := context.Background()
-    
-    // Fetch next bundle
-    log.Println("Fetching bundle...")
-    bundle, err := mgr.FetchNext(ctx)
-    if err != nil {
-        log.Fatal(err)
-    }
-    
-    log.Printf("✓ Fetched bundle %d", bundle.BundleNumber)
-    log.Printf("  Operations: %d", len(bundle.Operations))
-    log.Printf("  Unique DIDs: %d", bundle.DIDCount)
-    log.Printf("  Time range: %s to %s", 
-        bundle.StartTime.Format("2006-01-02"),
-        bundle.EndTime.Format("2006-01-02"))
-}
-```
-
-**What's happening here?**
-
-1. `plcbundle.New()` creates a manager that handles all bundle operations
-2. `FetchNext()` automatically:
-   - Fetches operations from PLC directory
-   - Creates a bundle when 10,000 operations are collected
-   - Saves the bundle to disk
-   - Updates the index
-   - Returns the bundle object
-
-### Reading Bundles
-
-Once you have bundles, you can load and read them:
-
-```go
-package main
-
-import (
-    "context"
-    "log"
-    
-    plcbundle "tangled.org/atscan.net/plcbundle"
-)
-
-func main() {
-    mgr, err := plcbundle.New("./plc_data", "")
-    if err != nil {
-        log.Fatal(err)
-    }
-    defer mgr.Close()
-    
-    ctx := context.Background()
-    
-    // Load bundle 1
-    bundle, err := mgr.Load(ctx, 1)
-    if err != nil {
-        log.Fatal(err)
-    }
-    
-    log.Printf("Bundle %d loaded", bundle.BundleNumber)
-    
-    // Iterate through operations
-    for i, op := range bundle.Operations {
-        if i >= 5 {
-            break // Just show first 5
-        }
-        log.Printf("%d. DID: %s, CID: %s", i+1, op.DID, op.CID)
-    }
-}
-```
-
----
-
-## Core Concepts
-
-### The Manager
-
-The `Manager` is your main entry point. It handles:
-- Bundle storage and retrieval
-- Index management
-- PLC directory synchronization
-- Verification
-- Mempool management
-
-**Creating a manager:**
-
-```go
-// Simple creation
-mgr, err := plcbundle.New("./bundles", "https://plc.directory")
-
-// Custom configuration
-config := plcbundle.DefaultConfig("./bundles")
-config.VerifyOnLoad = true
-config.AutoRebuild = true
-
-plcClient := plcbundle.NewPLCClient("https://plc.directory")
-mgr, err := plcbundle.NewManager(config, plcClient)
-```
-
-### Bundles
-
-A bundle contains exactly 10,000 operations:
-
-```go
-type Bundle struct {
-    BundleNumber     int                    // Sequential number (1, 2, 3...)
-    StartTime        time.Time              // First operation timestamp
-    EndTime          time.Time              // Last operation timestamp
-    Operations       []plcclient.PLCOperation     // The 10,000 operations
-    DIDCount         int                    // Unique DIDs in bundle
-    Hash             string                 // Chain hash (includes history)
-    ContentHash      string                 // This bundle's content hash
-    Parent           string                 // Previous bundle's chain hash
-    CompressedSize   int64                  // File size on disk
-    UncompressedSize int64                  // Original JSONL size
-}
-```
-
-### The Index
-
-The index tracks all bundles and their metadata:
-
-```go
-index := mgr.GetIndex()
-
-// Get all bundles
-bundles := index.GetBundles()
-for _, meta := range bundles {
-    log.Printf("Bundle %d: %s to %s", 
-        meta.BundleNumber, 
-        meta.StartTime.Format("2006-01-02"),
-        meta.EndTime.Format("2006-01-02"))
-}
-
-// Get specific bundle metadata
-meta, err := index.GetBundle(42)
-
-// Get last bundle
-lastBundle := index.GetLastBundle()
-```
-
-### Operations
-
-Each operation represents a DID PLC directory event:
-
-```go
-type PLCOperation struct {
-    DID       string          // The DID (did:plc:...)
-    Operation json.RawMessage // Raw JSON bytes (use GetOperationMap() to parse)
-    CID       string          // Content identifier
-    Nullified interface{}     // nil, false, or CID string
-    CreatedAt time.Time       // When it was created
-    
-    // Internal fields (populated automatically)
-    RawJSON         []byte                 // Original JSON line
-    ParsedOperation map[string]interface{} // Cached parsed data
-}
-
-// Accessing operation data:
-operation, err := op.GetOperationMap()  // Parses Operation field (cached)
-if err != nil || operation == nil {
-    return
-}
-
-// Now you can access fields
-services := operation["services"].(map[string]interface{})
-
-// Check if operation was nullified
-if op.IsNullified() {
-    log.Printf("Operation %s was nullified by %s", op.CID, op.GetNullifyingCID())
-}
-```
-
-### Accessing Operation Data
-
-The `Operation` field uses lazy parsing for performance. Always parse it before accessing:
-
-```go
-// ❌ Wrong - won't compile
-services := op.Operation["services"]
-
-// ✅ Correct
-operation, err := op.GetOperationMap()
-if err != nil || operation == nil {
-    return
-}
-services, ok := operation["services"].(map[string]interface{})
-```
-
-The parsed data is cached, so repeated calls are fast:
-// First call: parses JSON
-data1, _ := op.GetOperationMap()
-
-// Second call: returns cached data (fast)
-data2, _ := op.GetOperationMap()
-
----
-
-## Common Patterns
-
-### Pattern 1: Transparent Sync Service
-
-**Goal:** Keep a local PLC mirror continuously synchronized.
-
-This is the most common use case - maintaining an up-to-date copy of the PLC directory.
-
-```go
-package main
-
-import (
-    "context"
-    "log"
-    "os"
-    "os/signal"
-    "syscall"
-    "time"
-    
-    plcbundle "tangled.org/atscan.net/plcbundle"
-)
-
-type SyncService struct {
-    mgr      *plcbundle.Manager
-    interval time.Duration
-    stop     chan struct{}
-}
-
-func NewSyncService(bundleDir string, interval time.Duration) (*SyncService, error) {
-    mgr, err := plcbundle.New(bundleDir, "https://plc.directory")
-    if err != nil {
-        return nil, err
-    }
-    
-    return &SyncService{
-        mgr:      mgr,
-        interval: interval,
-        stop:     make(chan struct{}),
-    }, nil
-}
-
-func (s *SyncService) Start() {
-    log.Println("Starting sync service...")
-    
-    // Initial sync
-    s.sync()
-    
-    // Periodic sync
-    ticker := time.NewTicker(s.interval)
-    defer ticker.Stop()
-    
-    for {
-        select {
-        case <-ticker.C:
-            s.sync()
-        case <-s.stop:
-            log.Println("Sync service stopped")
-            return
-        }
-    }
-}
-
-func (s *SyncService) sync() {
-    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
-    defer cancel()
-    
-    log.Println("Checking for new bundles...")
-    
-    fetched := 0
-    for {
-        bundle, err := s.mgr.FetchNext(ctx)
-        if err != nil {
-            if isInsufficientOps(err) {
-                if fetched > 0 {
-                    log.Printf("✓ Synced %d new bundles", fetched)
-                } else {
-                    log.Println("✓ Up to date")
-                }
-                return
-            }
-            log.Printf("Error: %v", err)
-            return
-        }
-        
-        fetched++
-        log.Printf("✓ Fetched bundle %d (%d ops, %d DIDs)", 
-            bundle.BundleNumber, len(bundle.Operations), bundle.DIDCount)
-    }
-}
-
-func (s *SyncService) Stop() {
-    close(s.stop)
-    s.mgr.Close()
-}
-
-func isInsufficientOps(err error) bool {
-    return err != nil && 
-        (strings.Contains(err.Error(), "insufficient operations") ||
-         strings.Contains(err.Error(), "no more available"))
-}
-
-func main() {
-    service, err := NewSyncService("./plc_data", 5*time.Minute)
-    if err != nil {
-        log.Fatal(err)
-    }
-    
-    // Start service in background
-    go service.Start()
-    
-    // Wait for interrupt
-    sigChan := make(chan os.Signal, 1)
-    signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)
-    <-sigChan
-    
-    log.Println("Shutting down...")
-    service.Stop()
-}
-```
-
-**Usage:**
-```bash
-go run main.go
-# Starting sync service...
-# Checking for new bundles...
-# ✓ Fetched bundle 8548 (10000 ops, 8234 DIDs)
-# ✓ Fetched bundle 8549 (10000 ops, 8156 DIDs)
-# ✓ Up to date
-# ... (repeats every 5 minutes)
-```
-
-### Pattern 2: Reading and Processing Operations
-
-**Goal:** Process all historical operations for analysis.
-
-```go
-package main
-
-import (
-    "context"
-    "log"
-    
-    plcbundle "tangled.org/atscan.net/plcbundle"
-)
-
-type OperationProcessor struct {
-    mgr *plcbundle.Manager
-}
-
-func NewOperationProcessor(bundleDir string) (*OperationProcessor, error) {
-    mgr, err := plcbundle.New(bundleDir, "")
-    if err != nil {
-        return nil, err
-    }
-    
-    return &OperationProcessor{mgr: mgr}, nil
-}
-
-func (p *OperationProcessor) ProcessAll() error {
-    ctx := context.Background()
-    
-    index := p.mgr.GetIndex()
-    bundles := index.GetBundles()
-    
-    log.Printf("Processing %d bundles...", len(bundles))
-    
-    totalOps := 0
-    uniqueDIDs := make(map[string]bool)
-    
-    for _, meta := range bundles {
-        // Load bundle
-        bundle, err := p.mgr.Load(ctx, meta.BundleNumber)
-        if err != nil {
-            return err
-        }
-        
-        // Process operations
-        for _, op := range bundle.Operations {
-            totalOps++
-            uniqueDIDs[op.DID] = true
-            
-            // Your processing logic here
-            p.processOperation(op)
-        }
-        
-        if meta.BundleNumber % 100 == 0 {
-            log.Printf("Processed bundle %d...", meta.BundleNumber)
-        }
-    }
-    
-    log.Printf("✓ Processed %d operations from %d unique DIDs", 
-        totalOps, len(uniqueDIDs))
-    
-    return nil
-}
-
-func (p *OperationProcessor) processOperation(op plcbundle.PLCOperation) {
-    // Parse Operation field on-demand
-    operation, err := op.GetOperationMap()
-    if err != nil || operation == nil {
-        return
-    }
-    
-    // Example: Extract PDS endpoints
-    if services, ok := operation["services"].(map[string]interface{}); ok {
-        if pds, ok := services["atproto_pds"].(map[string]interface{}); ok {
-            if endpoint, ok := pds["endpoint"].(string); ok {
-                log.Printf("DID %s uses PDS: %s", op.DID, endpoint)
-            }
-        }
-    }
-}
-
-
-func main() {
-    processor, err := NewOperationProcessor("./plc_data")
-    if err != nil {
-        log.Fatal(err)
-    }
-    
-    if err := processor.ProcessAll(); err != nil {
-        log.Fatal(err)
-    }
-}
-```
-
-### Pattern 3: Time-Based Queries
-
-**Goal:** Export operations from a specific time period.
-
-```go
-package main
-
-import (
-    "context"
-    "encoding/json"
-    "log"
-    "os"
-    "time"
-    
-    plcbundle "tangled.org/atscan.net/plcbundle"
-)
-
-func exportOperationsSince(bundleDir string, since time.Time, limit int) error {
-    mgr, err := plcbundle.New(bundleDir, "")
-    if err != nil {
-        return err
-    }
-    defer mgr.Close()
-    
-    ctx := context.Background()
-    
-    // Export operations after timestamp
-    ops, err := mgr.Export(ctx, since, limit)
-    if err != nil {
-        return err
-    }
-    
-    log.Printf("Exporting %d operations...", len(ops))
-    
-    // Write as JSONL to stdout
-    encoder := json.NewEncoder(os.Stdout)
-    for _, op := range ops {
-        if err := encoder.Encode(op); err != nil {
-            return err
-        }
-    }
-    
-    return nil
-}
-
-func main() {
-    // Export operations from the last 7 days
-    since := time.Now().AddDate(0, 0, -7)
-    
-    if err := exportOperationsSince("./plc_data", since, 50000); err != nil {
-        log.Fatal(err)
-    }
-}
-```
-
-**Output to file:**
-```bash
-go run main.go > last_7_days.jsonl
-```
-
-### Pattern 4: Verification Service
-
-**Goal:** Periodically verify bundle integrity.
-
-```go
-package main
-
-import (
-    "context"
-    "log"
-    "time"
-    
-    plcbundle "tangled.org/atscan.net/plcbundle"
-)
-
-type VerificationService struct {
-    mgr      *plcbundle.Manager
-    interval time.Duration
-}
-
-func NewVerificationService(bundleDir string, interval time.Duration) (*VerificationService, error) {
-    mgr, err := plcbundle.New(bundleDir, "")
-    if err != nil {
-        return nil, err
-    }
-    
-    return &VerificationService{
-        mgr:      mgr,
-        interval: interval,
-    }, nil
-}
-
-func (v *VerificationService) Start() {
-    ticker := time.NewTicker(v.interval)
-    defer ticker.Stop()
-    
-    // Verify immediately on start
-    v.verify()
-    
-    for range ticker.C {
-        v.verify()
-    }
-}
-
-func (v *VerificationService) verify() {
-    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Minute)
-    defer cancel()
-    
-    log.Println("Starting chain verification...")
-    start := time.Now()
-    
-    result, err := v.mgr.VerifyChain(ctx)
-    if err != nil {
-        log.Printf("❌ Verification error: %v", err)
-        return
-    }
-    
-    elapsed := time.Since(start)
-    
-    if result.Valid {
-        log.Printf("✅ Chain verified: %d bundles, took %s", 
-            result.ChainLength, elapsed.Round(time.Second))
-        
-        // Get head hash
-        index := v.mgr.GetIndex()
-        if last := index.GetLastBundle(); last != nil {
-            log.Printf("   Head hash: %s...", last.Hash[:16])
-        }
-    } else {
-        log.Printf("❌ Chain broken at bundle %d: %s", 
-            result.BrokenAt, result.Error)
-        
-        // Alert or take action
-        v.handleBrokenChain(result)
-    }
-}
-
-func (v *VerificationService) handleBrokenChain(result *plcbundle.ChainVerificationResult) {
-    // Send alert, trigger re-sync, etc.
-    log.Printf("⚠️  ALERT: Chain integrity compromised!")
-    // TODO: Implement your alerting logic
-}
-
-func main() {
-    service, err := NewVerificationService("./plc_data", 24*time.Hour)
-    if err != nil {
-        log.Fatal(err)
-    }
-    
-    log.Println("Verification service started (daily checks)")
-    service.Start()
-}
-```
-
-### Pattern 5: Custom HTTP API
-
-**Goal:** Build a custom API on top of your bundle archive.
-
-```go
-package main
-
-import (
-    "encoding/json"
-    "log"
-    "net/http"
-    "strconv"
-    
-    plcbundle "tangled.org/atscan.net/plcbundle"
-)
-
-type API struct {
-    mgr *plcbundle.Manager
-}
-
-func NewAPI(bundleDir string) (*API, error) {
-    mgr, err := plcbundle.New(bundleDir, "")
-    if err != nil {
-        return nil, err
-    }
-    
-    return &API{mgr: mgr}, nil
-}
-
-func (api *API) handleStats(w http.ResponseWriter, r *http.Request) {
-    index := api.mgr.GetIndex()
-    stats := index.GetStats()
-    
-    response := map[string]interface{}{
-        "bundles":     stats["bundle_count"],
-        "first":       stats["first_bundle"],
-        "last":        stats["last_bundle"],
-        "total_size":  stats["total_size"],
-        "start_time":  stats["start_time"],
-        "end_time":    stats["end_time"],
-        "updated_at":  stats["updated_at"],
-    }
-    
-    w.Header().Set("Content-Type", "application/json")
-    json.NewEncoder(w).Encode(response)
-}
-
-func (api *API) handleOperations(w http.ResponseWriter, r *http.Request) {
-    bundleNumStr := r.URL.Query().Get("bundle")
-    if bundleNumStr == "" {
-        http.Error(w, "bundle parameter required", http.StatusBadRequest)
-        return
-    }
-    
-    bundleNum, err := strconv.Atoi(bundleNumStr)
-    if err != nil {
-        http.Error(w, "invalid bundle number", http.StatusBadRequest)
-        return
-    }
-    
-    ctx := r.Context()
-    bundle, err := api.mgr.Load(ctx, bundleNum)
-    if err != nil {
-        http.Error(w, err.Error(), http.StatusNotFound)
-        return
-    }
-    
-    w.Header().Set("Content-Type", "application/x-ndjson")
-    encoder := json.NewEncoder(w)
-    for _, op := range bundle.Operations {
-        encoder.Encode(op)
-    }
-}
-
-func (api *API) handleDID(w http.ResponseWriter, r *http.Request) {
-    did := r.URL.Query().Get("did")
-    if did == "" {
-        http.Error(w, "did parameter required", http.StatusBadRequest)
-        return
-    }
-    
-    ctx := r.Context()
-    
-    // Search through bundles for this DID
-    var operations []plcbundle.PLCOperation
-    
-    index := api.mgr.GetIndex()
-    bundles := index.GetBundles()
-    
-    for _, meta := range bundles {
-        bundle, err := api.mgr.Load(ctx, meta.BundleNumber)
-        if err != nil {
-            continue
-        }
-        
-        for _, op := range bundle.Operations {
-            if op.DID == did {
-                operations = append(operations, op)
-            }
-        }
-    }
-    
-    w.Header().Set("Content-Type", "application/json")
-    json.NewEncoder(w).Encode(map[string]interface{}{
-        "did":        did,
-        "operations": operations,
-        "count":      len(operations),
-    })
-}
-
-func main() {
-    api, err := NewAPI("./plc_data")
-    if err != nil {
-        log.Fatal(err)
-    }
-    
-    http.HandleFunc("/stats", api.handleStats)
-    http.HandleFunc("/operations", api.handleOperations)
-    http.HandleFunc("/did", api.handleDID)
-    
-    log.Println("API listening on :8080")
-    log.Fatal(http.ListenAndServe(":8080", nil))
-}
-```
-
-**Usage:**
-```bash
-# Get stats
-curl http://localhost:8080/stats
-
-# Get operations from bundle 1
-curl http://localhost:8080/operations?bundle=1
-
-# Get all operations for a DID
-curl http://localhost:8080/did?did=did:plc:example123
-```
-
----
-
-## Building Applications
-
-### Application 1: PDS Discovery Tool
-
-Find all PDS endpoints in the network:
-
-```go
-package main
-
-import (
-    "context"
-    "fmt"
-    "log"
-    
-    plcbundle "tangled.org/atscan.net/plcbundle"
-)
-
-type PDSTracker struct {
-    mgr       *plcbundle.Manager
-    endpoints map[string]int  // endpoint -> count
-}
-
-func NewPDSTracker(bundleDir string) (*PDSTracker, error) {
-    mgr, err := plcbundle.New(bundleDir, "")
-    if err != nil {
-        return nil, err
-    }
-    
-    return &PDSTracker{
-        mgr:       mgr,
-        endpoints: make(map[string]int),
-    }, nil
-}
-
-func (pt *PDSTracker) Scan() error {
-    ctx := context.Background()
-    
-    index := pt.mgr.GetIndex()
-    bundles := index.GetBundles()
-    
-    log.Printf("Scanning %d bundles for PDS endpoints...", len(bundles))
-    
-    for _, meta := range bundles {
-        bundle, err := pt.mgr.Load(ctx, meta.BundleNumber)
-        if err != nil {
-            return err
-        }
-        
-        for _, op := range bundle.Operations {
-            if endpoint := pt.extractPDS(op); endpoint != "" {
-                pt.endpoints[endpoint]++
-            }
-        }
-    }
-    
-    return nil
-}
-
-func (pt *PDSTracker) extractPDS(op plcbundle.PLCOperation) string {
-    // Parse Operation field on-demand
-    operation, err := op.GetOperationMap()
-    if err != nil || operation == nil {
-        return ""
-    }
-    
-    services, ok := operation["services"].(map[string]interface{})
-    if !ok {
-        return ""
-    }
-    
-    pds, ok := services["atproto_pds"].(map[string]interface{})
-    if !ok {
-        return ""
-    }
-    
-    endpoint, ok := pds["endpoint"].(string)
-    if !ok {
-        return ""
-    }
-    
-    return endpoint
-}
-
-
-func (pt *PDSTracker) PrintResults() {
-    log.Printf("\nFound %d unique PDS endpoints:\n", len(pt.endpoints))
-    
-    // Sort by count
-    type endpointCount struct {
-        endpoint string
-        count    int
-    }
-    
-    var sorted []endpointCount
-    for endpoint, count := range pt.endpoints {
-        sorted = append(sorted, endpointCount{endpoint, count})
-    }
-    
-    sort.Slice(sorted, func(i, j int) bool {
-        return sorted[i].count > sorted[j].count
-    })
-    
-    // Print top 20
-    for i, ec := range sorted {
-        if i >= 20 {
-            break
-        }
-        fmt.Printf("%3d. %s (%d DIDs)\n", i+1, ec.endpoint, ec.count)
-    }
-}
-
-func main() {
-    tracker, err := NewPDSTracker("./plc_data")
-    if err != nil {
-        log.Fatal(err)
-    }
-    
-    if err := tracker.Scan(); err != nil {
-        log.Fatal(err)
-    }
-    
-    tracker.PrintResults()
-}
-```
-
-### Application 2: DID History Viewer
-
-View the complete history of a DID:
-
-```go
-package main
-
-import (
-    "context"
-    "encoding/json"
-    "fmt"
-    "log"
-    "os"
-    
-    plcbundle "tangled.org/atscan.net/plcbundle"
-)
-
-type DIDHistory struct {
-    DID        string                    `json:"did"`
-    Operations []plcbundle.PLCOperation  `json:"operations"`
-    FirstSeen  time.Time                 `json:"first_seen"`
-    LastSeen   time.Time                 `json:"last_seen"`
-    OpCount    int                       `json:"operation_count"`
-}
-
-func getDIDHistory(bundleDir, did string) (*DIDHistory, error) {
-    mgr, err := plcbundle.New(bundleDir, "")
-    if err != nil {
-        return nil, err
-    }
-    defer mgr.Close()
-    
-    ctx := context.Background()
-    
-    history := &DIDHistory{
-        DID:        did,
-        Operations: make([]plcbundle.PLCOperation, 0),
-    }
-    
-    index := mgr.GetIndex()
-    bundles := index.GetBundles()
-    
-    log.Printf("Searching for DID %s...", did)
-    
-    for _, meta := range bundles {
-        bundle, err := mgr.Load(ctx, meta.BundleNumber)
-        if err != nil {
-            continue
-        }
-        
-        for _, op := range bundle.Operations {
-            if op.DID == did {
-                history.Operations = append(history.Operations, op)
-            }
-        }
-    }
-    
-    if len(history.Operations) == 0 {
-        return nil, fmt.Errorf("DID not found")
-    }
-    
-    // Set timestamps
-    history.FirstSeen = history.Operations[0].CreatedAt
-    history.LastSeen = history.Operations[len(history.Operations)-1].CreatedAt
-    history.OpCount = len(history.Operations)
-    
-    return history, nil
-}
-
-func main() {
-    if len(os.Args) < 2 {
-        log.Fatal("Usage: did-history <did>")
-    }
-    
-    did := os.Args[1]
-    
-    history, err := getDIDHistory("./plc_data", did)
-    if err != nil {
-        log.Fatal(err)
-    }
-    
-    // Print as JSON
-    encoder := json.NewEncoder(os.Stdout)
-    encoder.SetIndent("", "  ")
-    encoder.Encode(history)
-}
-```
-
-### Application 3: Real-time Monitor
-
-Monitor new operations as they arrive:
-
-```go
-package main
-
-import (
-    "context"
-    "log"
-    "time"
-    
-    plcbundle "tangled.org/atscan.net/plcbundle"
-)
-
-type Monitor struct {
-    mgr          *plcbundle.Manager
-    lastSeen     int  // Last bundle number processed
-    pollInterval time.Duration
-}
-
-func NewMonitor(bundleDir string, pollInterval time.Duration) (*Monitor, error) {
-    mgr, err := plcbundle.New(bundleDir, "https://plc.directory")
-    if err != nil {
-        return nil, err
-    }
-    
-    // Get current position
-    index := mgr.GetIndex()
-    lastBundle := index.GetLastBundle()
-    lastSeen := 0
-    if lastBundle != nil {
-        lastSeen = lastBundle.BundleNumber
-    }
-    
-    return &Monitor{
-        mgr:          mgr,
-        lastSeen:     lastSeen,
-        pollInterval: pollInterval,
-    }, nil
-}
-
-func (m *Monitor) Start() {
-    log.Println("Monitor started, watching for new bundles...")
-    
-    ticker := time.NewTicker(m.pollInterval)
-    defer ticker.Stop()
-    
-    for range ticker.C {
-        m.check()
-    }
-}
-
-func (m *Monitor) check() {
-    ctx := context.Background()
-    
-    // Try to fetch next bundle
-    bundle, err := m.mgr.FetchNext(ctx)
-    if err != nil {
-        // Not an error if no new bundle available
-        return
-    }
-    
-    // New bundle!
-    log.Printf("🔔 New bundle: %d", bundle.BundleNumber)
-    log.Printf("   Operations: %d", len(bundle.Operations))
-    log.Printf("   DIDs: %d", bundle.DIDCount)
-    log.Printf("   Time: %s", bundle.EndTime.Format("2006-01-02 15:04:05"))
-    
-    // Process new operations
-    m.processNewOperations(bundle)
-    
-    m.lastSeen = bundle.BundleNumber
-}
-
-func (m *Monitor) processNewOperations(bundle *plcbundle.Bundle) {
-    for _, op := range bundle.Operations {
-        // Check for interesting operations
-        if op.IsNullified() {
-            log.Printf("   ⚠️  Nullified: %s", op.DID)
-        }
-        
-        // Check for new DIDs (operation type "create")
-        operation, err := op.GetOperationMap()
-        if err == nil && operation != nil {
-            if opType, ok := operation["type"].(string); ok && opType == "create" {
-                log.Printf("   ➕ New DID: %s", op.DID)
-            }
-        }
-    }
-}
-
-func main() {
-    monitor, err := NewMonitor("./plc_data", 30*time.Second)
-    if err != nil {
-        log.Fatal(err)
-    }
-    
-    monitor.Start()
-}
-```
-
----
-
-## Advanced Usage
-
-### Custom Configuration
-
-Full control over bundle manager behavior:
-
-```go
-package main
-
-import (
-    "log"
-    "runtime"
-    "time"
-    
-    "tangled.org/atscan.net/plcbundle/bundle"
-    "tangled.org/atscan.net/plcbundle/plcclient"
-    plcbundle "tangled.org/atscan.net/plcbundle"
-)
-
-func main() {
-    // Custom configuration
-    config := &bundle.Config{
-        BundleDir:       "./my_bundles",
-        VerifyOnLoad:    true,                    // Verify hashes when loading
-        AutoRebuild:     true,                    // Auto-rebuild index if needed
-        RebuildWorkers:  runtime.NumCPU(),        // Parallel workers for rebuild
-        Logger:          &MyCustomLogger{},       // Custom logger
-        
-        // Progress callback for rebuild
-        RebuildProgress: func(current, total int) {
-            if current%100 == 0 {
-                log.Printf("Rebuild: %d/%d (%.1f%%)", 
-                    current, total, float64(current)/float64(total)*100)
-            }
-        },
-    }
-    
-    // Custom PLC client with rate limiting
-    plcClient := plcclient.NewClient("https://plc.directory",
-        plcclient.WithRateLimit(60, time.Minute),      // 60 req/min
-        plcclient.WithTimeout(30*time.Second),         // 30s timeout
-        plcclient.WithLogger(&MyCustomLogger{}),       // Custom logger
-    )
-    
-    // Create manager
-    mgr, err := bundle.NewManager(config, plcClient)
-    if err != nil {
-        log.Fatal(err)
-    }
-    defer mgr.Close()
-    
-    log.Println("Manager created with custom configuration")
-}
-
-// Custom logger implementation
-type MyCustomLogger struct{}
-
-func (l *MyCustomLogger) Printf(format string, v ...interface{}) {
-    // Add custom formatting, filtering, etc.
-    log.Printf("[PLCBUNDLE] "+format, v...)
-}
-
-func (l *MyCustomLogger) Println(v ...interface{}) {
-    log.Println(append([]interface{}{"[PLCBUNDLE]"}, v...)...)
-}
-```
-
-### Streaming Data
-
-Stream bundle data without loading everything into memory:
-
-```go
-package main
-
-import (
-    "bufio"
-    "context"
-    "encoding/json"
-    "io"
-    "log"
-    
-    plcbundle "tangled.org/atscan.net/plcbundle"
-)
-
-func streamBundle(mgr *plcbundle.Manager, bundleNumber int) error {
-    ctx := context.Background()
-    
-    // Get decompressed stream
-    reader, err := mgr.StreamDecompressed(ctx, bundleNumber)
-    if err != nil {
-        return err
-    }
-    defer reader.Close()
-    
-    // Read line by line (JSONL)
-    scanner := bufio.NewScanner(reader)
-    
-    // Set buffer size for large lines
-    buf := make([]byte, 0, 64*1024)
-    scanner.Buffer(buf, 1024*1024)
-    
-    lineNum := 0
-    for scanner.Scan() {
-        lineNum++
-        
-        var op plcbundle.PLCOperation
-        if err := json.Unmarshal(scanner.Bytes(), &op); err != nil {
-            log.Printf("Warning: failed to parse line %d: %v", lineNum, err)
-            continue
-        }
-        
-        // Process operation without storing all in memory
-        processOperation(op)
-    }
-    
-    return scanner.Err()
-}
-
-func processOperation(op plcbundle.PLCOperation) {
-    // Your processing logic
-    log.Printf("Processing: %s", op.DID)
-}
-
-func main() {
-    mgr, err := plcbundle.New("./plc_data", "")
-    if err != nil {
-        log.Fatal(err)
-    }
-    defer mgr.Close()
-    
-    // Stream bundle 1
-    if err := streamBundle(mgr, 1); err != nil {
-        log.Fatal(err)
-    }
-}
-```
-
-### Parallel Processing
-
-Process multiple bundles concurrently:
-
-```go
-package main
-
-import (
-    "context"
-    "log"
-    "sync"
-    
-    plcbundle "tangled.org/atscan.net/plcbundle"
-)
-
-func processParallel(mgr *plcbundle.Manager, workers int) error {
-    ctx := context.Background()
-    
-    index := mgr.GetIndex()
-    bundles := index.GetBundles()
-    
-    // Create job channel
-    jobs := make(chan int, len(bundles))
-    results := make(chan error, len(bundles))
-    
-    // Start workers
-    var wg sync.WaitGroup
-    for w := 0; w < workers; w++ {
-        wg.Add(1)
-        go func() {
-            defer wg.Done()
-            for bundleNum := range jobs {
-                if err := processBundle(ctx, mgr, bundleNum); err != nil {
-                    results <- err
-                } else {
-                    results <- nil
-                }
-            }
-        }()
-    }
-    
-    // Send jobs
-    for _, meta := range bundles {
-        jobs <- meta.BundleNumber
-    }
-    close(jobs)
-    
-    // Wait for completion
-    go func() {
-        wg.Wait()
-        close(results)
-    }()
-    
-    // Collect results
-    errors := 0
-    for err := range results {
-        if err != nil {
-            log.Printf("Error: %v", err)
-            errors++
-        }
-    }
-    
-    if errors > 0 {
-        return fmt.Errorf("%d bundles failed processing", errors)
-    }
-    
-    return nil
-}
-
-func processBundle(ctx context.Context, mgr *plcbundle.Manager, bundleNum int) error {
-    bundle, err := mgr.Load(ctx, bundleNum)
-    if err != nil {
-        return err
-    }
-    
-    // Process operations
-    for _, op := range bundle.Operations {
-        // Your logic here
-        _ = op
-    }
-    
-    log.Printf("Processed bundle %d", bundleNum)
-    return nil
-}
-
-func main() {
-    mgr, err := plcbundle.New("./plc_data", "")
-    if err != nil {
-        log.Fatal(err)
-    }
-    defer mgr.Close()
-    
-    // Process with 8 workers
-    if err := processParallel(mgr, 8); err != nil {
-        log.Fatal(err)
-    }
-}
-```
-
-### Working with Mempool
-
-Access operations before they're bundled:
-
-```go
-package main
-
-import (
-    "log"
-    
-    plcbundle "tangled.org/atscan.net/plcbundle"
-)
-
-func main() {
-    mgr, err := plcbundle.New("./plc_data", "https://plc.directory")
-    if err != nil {
-        log.Fatal(err)
-    }
-    defer mgr.Close()
-    
-    // Get mempool stats
-    stats := mgr.GetMempoolStats()
-    
-    count := stats["count"].(int)
-    targetBundle := stats["target_bundle"].(int)
-    canCreate := stats["can_create_bundle"].(bool)
-    
-    log.Printf("Mempool status:")
-    log.Printf("  Target bundle: %d", targetBundle)
-    log.Printf("  Operations: %d/%d", count, plcbundle.BUNDLE_SIZE)
-    log.Printf("  Ready: %v", canCreate)
-    
-    if count > 0 {
-        // Get mempool operations
-        ops, err := mgr.GetMempoolOperations()
-        if err != nil {
-            log.Fatal(err)
-        }
-        
-        log.Printf("Latest unbundled operations:")
-        for i, op := range ops {
-            if i >= 5 {
-                break
-            }
-            log.Printf("  %d. %s (%s)", i+1, op.DID, op.CreatedAt.Format("15:04:05"))
-        }
-    }
-    
-    // Validate chronological order
-    if err := mgr.ValidateMempool(); err != nil {
-        log.Printf("⚠️  Mempool validation failed: %v", err)
-    } else {
-        log.Println("✓ Mempool validated")
-    }
-}
-```
-
----
-
-## Best Practices
-
-### 1. Always Close the Manager
-
-Use `defer` to ensure cleanup:
-
-```go
-mgr, err := plcbundle.New("./plc_data", "https://plc.directory")
-if err != nil {
-    return err
-}
-defer mgr.Close()  // Always close!
-```
-
-### 2. Handle Context Cancellation
-
-Support graceful shutdown:
-
-```go
-ctx, cancel := context.WithCancel(context.Background())
-defer cancel()
-
-// Listen for interrupt
-sigChan := make(chan os.Signal, 1)
-signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)
-
-go func() {
-    <-sigChan
-    log.Println("Interrupt received, stopping...")
-    cancel()
-}()
-
-// Use context in operations
-bundle, err := mgr.FetchNext(ctx)
-if err == context.Canceled {
-    log.Println("Operation cancelled gracefully")
-    return nil
-}
-```
-
-### 3. Check Errors Properly
-
-Distinguish between different error types:
-
-```go
-bundle, err := mgr.FetchNext(ctx)
-if err != nil {
-    // Check if it's just "caught up"
-    if strings.Contains(err.Error(), "insufficient operations") {
-        log.Println("No new bundles available (caught up)")
-        return nil
-    }
-    
-    // Real error
-    return fmt.Errorf("fetch failed: %w", err)
-}
-```
-
-### 4. Use Streaming for Large Datasets
-
-Don't load everything into memory:
-
-```go
-// ❌ Bad: Loads all operations into memory
-index := mgr.GetIndex()
-var allOps []plcbundle.PLCOperation
-for _, meta := range index.GetBundles() {
-    bundle, _ := mgr.Load(ctx, meta.BundleNumber)
-    allOps = append(allOps, bundle.Operations...)
-}
-
-// ✅ Good: Process one bundle at a time
-for _, meta := range index.GetBundles() {
-    bundle, _ := mgr.Load(ctx, meta.BundleNumber)
-    for _, op := range bundle.Operations {
-        processOperation(op)
-    }
-}
-```
-
-### 5. Enable Verification in Production
-
-```go
-config := plcbundle.DefaultConfig("./plc_data")
-config.VerifyOnLoad = true  // Verify hashes when loading
-
-mgr, err := plcbundle.NewManager(config, plcClient)
-```
-
-### 6. Log Appropriately
-
-Implement custom logger for production:
-
-```go
-type ProductionLogger struct {
-    logger *zap.Logger
-}
-
-func (l *ProductionLogger) Printf(format string, v ...interface{}) {
-    l.logger.Sugar().Infof(format, v...)
-}
-
-func (l *ProductionLogger) Println(v ...interface{}) {
-    l.logger.Sugar().Info(v...)
-}
-```
-
-### 7. Handle Rate Limits
-
-Configure PLC client appropriately:
-
-```go
-// Production: Be conservative
-plcClient := plcclient.NewClient("https://plc.directory",
-    plcclient.WithRateLimit(60, time.Minute),  // 60 req/min max
-    plcclient.WithTimeout(60*time.Second),
-)
-
-// Development: Can be more aggressive (but respectful)
-plcClient := plcclient.NewClient("https://plc.directory",
-    plcclient.WithRateLimit(90, time.Minute),
-    plcclient.WithTimeout(30*time.Second),
-)
-```
-
----
-
-## API Reference
-
-### Manager Methods
-
-```go
-// Creation
-New(bundleDir, plcURL string) (*Manager, error)
-NewManager(config *Config, plcClient *PLCClient) (*Manager, error)
-
-// Lifecycle
-Close()
-
-// Fetching
-FetchNext(ctx) (*Bundle, error)
-
-// Loading
-Load(ctx, bundleNumber int) (*Bundle, error)
-
-// Verification
-Verify(ctx, bundleNumber int) (*VerificationResult, error)
-VerifyChain(ctx) (*ChainVerificationResult, error)
-
-// Exporting
-Export(ctx, afterTime time.Time, count int) ([]PLCOperation, error)
-
-// Streaming
-StreamRaw(ctx, bundleNumber int) (io.ReadCloser, error)
-StreamDecompressed(ctx, bundleNumber int) (io.ReadCloser, error)
-
-// Index
-GetIndex() *Index
-ScanBundle(path string, bundleNumber int) (*BundleMetadata, error)
-Scan() (*DirectoryScanResult, error)
-
-// Mempool
-GetMempoolStats() map[string]interface{}
-GetMempoolOperations() ([]PLCOperation, error)
-ValidateMempool() error
-ClearMempool() error
-
-// Info
-GetInfo() map[string]interface{}
-IsBundleIndexed(bundleNumber int) bool
-```
-
-### Index Methods
-
-```go
-// Creation
-NewIndex() *Index
-LoadIndex(path string) (*Index, error)
-
-// Persistence
-Save(path string) error
-
-// Queries
-GetBundle(bundleNumber int) (*BundleMetadata, error)
-GetLastBundle() *BundleMetadata
-GetBundles() []*BundleMetadata
-GetBundleRange(start, end int) []*BundleMetadata
-
-// Stats
-Count() int
-FindGaps() []int
-GetStats() map[string]interface{}
-```
-
-### Configuration Types
-
-```go
-type Config struct {
-    BundleDir       string
-    VerifyOnLoad    bool
-    AutoRebuild     bool
-    RebuildWorkers  int
-    RebuildProgress func(current, total int)
-    Logger          Logger
-}
-
-type Logger interface {
-    Printf(format string, v ...interface{})
-    Println(v ...interface{})
-}
-```
-
----
-
-## Troubleshooting
-
-### Bundle Not Found Error
-
-```go
-bundle, err := mgr.Load(ctx, 999)
-if err != nil {
-    if strings.Contains(err.Error(), "not in index") {
-        // Bundle doesn't exist
-        log.Printf("Bundle 999 hasn't been fetched yet")
-    }
-}
-```
-
-### Insufficient Operations Error
-
-```go
-bundle, err := mgr.FetchNext(ctx)
-if err != nil {
-    if strings.Contains(err.Error(), "insufficient operations") {
-        // Not enough operations for a complete bundle
-        // Check mempool
-        stats := mgr.GetMempoolStats()
-        count := stats["count"].(int)
-        log.Printf("Only %d operations available (need %d)", count, plcbundle.BUNDLE_SIZE)
-    }
-}
-```
-
-### Memory Usage
-
-If processing large numbers of bundles:
-
-```go
-// Force garbage collection between bundles
-for _, meta := range index.GetBundles() {
-    bundle, _ := mgr.Load(ctx, meta.BundleNumber)
-    processBundle(bundle)
-    
-    runtime.GC()  // Help garbage collector
-}
-```
-
----
-
-## Examples Repository
-
-Find complete, runnable examples at:
-- https://github.com/plcbundle/examples
-
-Including:
-- Complete sync service
-- API server
-- Analysis tools
-- Monitoring services
-
+TODO

internal/didindex/manager.go

···
 		evictionThreshold: 5,
 		config:            config,
 		logger:            logger,
+		recentLookupSize:  1000, // Track last 100 lookups
+		recentLookups:     make([]int64, 1000),
 	}
 }
 
···
 	dim.verbose = verbose
 }
 
-// GetDIDLocations returns all bundle+position locations for a DID
+// GetDIDLocations returns all bundle+position locations for a DID (with timing)
 func (dim *Manager) GetDIDLocations(did string) ([]OpLocation, error) {
+	// Start timing
+	lookupStart := time.Now()
+	defer func() {
+		dim.recordLookupTime(time.Since(lookupStart))
+	}()
+
 	identifier, err := extractDIDIdentifier(did)
 	if err != nil {
 		return nil, err
···
 		return nil, fmt.Errorf("failed to load shard %02x: %w", shardNum, err)
 	}
 
-	// CRITICAL: Release shard when done
 	defer dim.releaseShard(shard)
 
 	if shard.data == nil {
···
 		dim.logger.Printf("DEBUG: Shard %02x loaded, size: %d bytes", shardNum, len(shard.data))
 	}
 
-	// Safe to read - refcount prevents eviction
 	locations := dim.searchShard(shard, identifier)
 
 	if dim.verbose {
···
 		atomic.AddInt64(&shard.refCount, 1)
 		atomic.StoreInt64(&shard.lastUsed, time.Now().Unix())
 		atomic.AddInt64(&shard.accessCount, 1)
+		atomic.AddInt64(&dim.cacheHits, 1)
 
 		return shard, nil
 	}
+	atomic.AddInt64(&dim.cacheMisses, 1)
 
 	// Cache miss - load from disk
 	shardPath := filepath.Join(dim.shardDir, fmt.Sprintf("%02x.idx", shardNum))
···
 	}
 }
 
-// GetStats returns index statistics
+// GetStats returns index statistics (updated)
 func (dim *Manager) GetStats() map[string]interface{} {
 	cachedShards := make([]int, 0)
 
···
 
 	sort.Ints(cachedShards)
 
-	return map[string]interface{}{
-		"total_dids":    dim.config.TotalDIDs,
-		"last_bundle":   dim.config.LastBundle,
-		"shard_count":   dim.config.ShardCount,
-		"cached_shards": len(cachedShards),
-		"cache_limit":   dim.maxCache,
-		"cache_order":   cachedShards,
-		"updated_at":    dim.config.UpdatedAt,
+	// Calculate cache hit rate
+	hits := atomic.LoadInt64(&dim.cacheHits)
+	misses := atomic.LoadInt64(&dim.cacheMisses)
+	total := hits + misses
+
+	cacheHitRate := 0.0
+	if total > 0 {
+		cacheHitRate = float64(hits) / float64(total)
+	}
+
+	baseStats := map[string]interface{}{
+		"total_dids":     dim.config.TotalDIDs,
+		"last_bundle":    dim.config.LastBundle,
+		"shard_count":    dim.config.ShardCount,
+		"cached_shards":  len(cachedShards),
+		"cache_limit":    dim.maxCache,
+		"cache_order":    cachedShards,
+		"updated_at":     dim.config.UpdatedAt,
+		"cache_hits":     hits,
+		"cache_misses":   misses,
+		"cache_hit_rate": cacheHitRate,
+		"total_lookups":  total,
+	}
+
+	// Merge with performance stats
+	perfStats := dim.calculateLookupStats()
+	for k, v := range perfStats {
+		baseStats[k] = v
 	}
+
+	return baseStats
 }
 
 // Exists checks if index exists
···
 
 	atomic.AddInt64(&shard.refCount, -1)
 }
+
+// ResetCacheStats resets cache statistics (useful for monitoring)
+func (dim *Manager) ResetCacheStats() {
+	atomic.StoreInt64(&dim.cacheHits, 0)
+	atomic.StoreInt64(&dim.cacheMisses, 0)
+}
+
+// recordLookupTime records a lookup time (thread-safe)
+func (dim *Manager) recordLookupTime(duration time.Duration) {
+	micros := duration.Microseconds()
+
+	// Update totals (atomic)
+	atomic.AddInt64(&dim.totalLookups, 1)
+	atomic.AddInt64(&dim.totalLookupTime, micros)
+
+	// Update circular buffer (with lock)
+	dim.lookupTimeLock.Lock()
+	dim.recentLookups[dim.recentLookupIdx] = micros
+	dim.recentLookupIdx = (dim.recentLookupIdx + 1) % dim.recentLookupSize
+	dim.lookupTimeLock.Unlock()
+}
+
+// calculateLookupStats calculates performance statistics
+func (dim *Manager) calculateLookupStats() map[string]interface{} {
+	totalLookups := atomic.LoadInt64(&dim.totalLookups)
+	totalTime := atomic.LoadInt64(&dim.totalLookupTime)
+
+	stats := make(map[string]interface{})
+
+	if totalLookups == 0 {
+		return stats
+	}
+
+	// Overall average (all time)
+	avgMicros := float64(totalTime) / float64(totalLookups)
+	stats["avg_lookup_time_ms"] = avgMicros / 1000.0
+	stats["total_lookups"] = totalLookups
+
+	// Recent statistics (last N lookups)
+	dim.lookupTimeLock.Lock()
+	recentCopy := make([]int64, dim.recentLookupSize)
+	copy(recentCopy, dim.recentLookups)
+	dim.lookupTimeLock.Unlock()
+
+	// Find valid entries (non-zero)
+	validRecent := make([]int64, 0, dim.recentLookupSize)
+	for _, t := range recentCopy {
+		if t > 0 {
+			validRecent = append(validRecent, t)
+		}
+	}
+
+	if len(validRecent) > 0 {
+		// Sort for percentiles
+		sortedRecent := make([]int64, len(validRecent))
+		copy(sortedRecent, validRecent)
+		sort.Slice(sortedRecent, func(i, j int) bool {
+			return sortedRecent[i] < sortedRecent[j]
+		})
+
+		// Calculate recent average
+		var recentSum int64
+		for _, t := range validRecent {
+			recentSum += t
+		}
+		recentAvg := float64(recentSum) / float64(len(validRecent))
+		stats["recent_avg_lookup_time_ms"] = recentAvg / 1000.0
+		stats["recent_sample_size"] = len(validRecent)
+
+		// Min/Max
+		stats["min_lookup_time_ms"] = float64(sortedRecent[0]) / 1000.0
+		stats["max_lookup_time_ms"] = float64(sortedRecent[len(sortedRecent)-1]) / 1000.0
+
+		// Percentiles (p50, p95, p99)
+		p50idx := len(sortedRecent) * 50 / 100
+		p95idx := len(sortedRecent) * 95 / 100
+		p99idx := len(sortedRecent) * 99 / 100
+
+		if p50idx < len(sortedRecent) {
+			stats["p50_lookup_time_ms"] = float64(sortedRecent[p50idx]) / 1000.0
+		}
+		if p95idx < len(sortedRecent) {
+			stats["p95_lookup_time_ms"] = float64(sortedRecent[p95idx]) / 1000.0
+		}
+		if p99idx < len(sortedRecent) {
+			stats["p99_lookup_time_ms"] = float64(sortedRecent[p99idx]) / 1000.0
+		}
+	}
+
+	return stats
+}
+
+// ResetPerformanceStats resets performance statistics (useful for monitoring periods)
+func (dim *Manager) ResetPerformanceStats() {
+	atomic.StoreInt64(&dim.cacheHits, 0)
+	atomic.StoreInt64(&dim.cacheMisses, 0)
+	atomic.StoreInt64(&dim.totalLookups, 0)
+	atomic.StoreInt64(&dim.totalLookupTime, 0)
+
+	dim.lookupTimeLock.Lock()
+	dim.recentLookups = make([]int64, dim.recentLookupSize)
+	dim.recentLookupIdx = 0
+	dim.lookupTimeLock.Unlock()
+}

internal/didindex/types.go

···
 	shardCache        sync.Map
 	maxCache          int
 	evictionThreshold int
+	cacheHits         int64 // atomic counter
+	cacheMisses       int64 // atomic counter
 
 	config  *Config
 	logger  Logger
 	verbose bool
 
 	indexMu sync.RWMutex
+
+	// Performance tracking
+	totalLookups     int64 // Total number of lookups
+	totalLookupTime  int64 // Total time in microseconds
+	lookupTimeLock   sync.Mutex
+	recentLookups    []int64 // Circular buffer for recent lookup times (microseconds)
+	recentLookupIdx  int
+	recentLookupSize int
 }
 
 // mmapShard represents a memory-mapped shard file

internal/handleresolver/resolver.go

···
 	handle = strings.TrimPrefix(handle, "@")
 	return handle
 }
+
+// GetBaseURL returns the PLC directory base URL
+func (c *Client) GetBaseURL() string {
+	return c.baseURL
+}

internal/sync/syncer.go

···
 
 		// Success
 		fetchedCount++
-		totalIndexTime += stats.IndexTime
+		if stats != nil {
+			totalIndexTime += stats.IndexTime
+		}
 
 		// Callback if provided
 		if config.OnBundleSynced != nil {

server/handlers.go

···
 				UptimeSeconds:    int(time.Since(s.startTime).Seconds()),
 				SyncMode:         s.config.SyncMode,
 				WebSocketEnabled: s.config.EnableWebSocket,
+				ResolverEnabled:  s.config.EnableResolver,
 				Origin:           s.manager.GetPLCOrigin(),
 			},
 			Bundles: BundleStatus{
···
 				UncompressedSize: indexStats["total_uncompressed_size"].(int64),
 				UpdatedAt:        indexStats["updated_at"].(time.Time),
 			},
+		}
+
+		if resolver := s.manager.GetHandleResolver(); resolver != nil {
+			response.Server.HandleResolver = resolver.GetBaseURL()
 		}
 
 		if s.config.SyncMode && s.config.SyncInterval > 0 {
···
 			}
 		}
 
+		// DID Index stats
+		didStats := s.manager.GetDIDIndexStats()
+		if didStats["enabled"].(bool) {
+			didIndex := &DIDIndexStatus{
+				Enabled:      true,
+				Exists:       didStats["exists"].(bool),
+				TotalDIDs:    didStats["total_dids"].(int64),
+				IndexedDIDs:  didStats["indexed_dids"].(int64),
+				LastBundle:   didStats["last_bundle"].(int),
+				ShardCount:   didStats["shard_count"].(int),
+				CachedShards: didStats["cached_shards"].(int),
+				CacheLimit:   didStats["cache_limit"].(int),
+				UpdatedAt:    didStats["updated_at"].(time.Time),
+			}
+
+			// Mempool DIDs
+			if mempoolDIDs, ok := didStats["mempool_dids"].(int64); ok && mempoolDIDs > 0 {
+				didIndex.MempoolDIDs = mempoolDIDs
+			}
+
+			// Version and format
+			if s.manager.GetDIDIndex() != nil {
+				config := s.manager.GetDIDIndex().GetConfig()
+				didIndex.Version = config.Version
+				didIndex.Format = config.Format
+			}
+
+			// Hot shards
+			if cacheOrder, ok := didStats["cache_order"].([]int); ok && len(cacheOrder) > 0 {
+				maxShards := 10
+				if len(cacheOrder) < maxShards {
+					maxShards = len(cacheOrder)
+				}
+				didIndex.HotShards = cacheOrder[:maxShards]
+			}
+
+			// Cache performance
+			if cacheHitRate, ok := didStats["cache_hit_rate"].(float64); ok {
+				didIndex.CacheHitRate = cacheHitRate
+			}
+			if cacheHits, ok := didStats["cache_hits"].(int64); ok {
+				didIndex.CacheHits = cacheHits
+			}
+			if cacheMisses, ok := didStats["cache_misses"].(int64); ok {
+				didIndex.CacheMisses = cacheMisses
+			}
+			if totalLookups, ok := didStats["total_lookups"].(int64); ok {
+				didIndex.TotalLookups = totalLookups
+			}
+
+			// NEW: Lookup performance metrics
+			if avgTime, ok := didStats["avg_lookup_time_ms"].(float64); ok {
+				didIndex.AvgLookupTimeMs = avgTime
+			}
+			if recentAvg, ok := didStats["recent_avg_lookup_time_ms"].(float64); ok {
+				didIndex.RecentAvgLookupTimeMs = recentAvg
+			}
+			if minTime, ok := didStats["min_lookup_time_ms"].(float64); ok {
+				didIndex.MinLookupTimeMs = minTime
+			}
+			if maxTime, ok := didStats["max_lookup_time_ms"].(float64); ok {
+				didIndex.MaxLookupTimeMs = maxTime
+			}
+			if p50, ok := didStats["p50_lookup_time_ms"].(float64); ok {
+				didIndex.P50LookupTimeMs = p50
+			}
+			if p95, ok := didStats["p95_lookup_time_ms"].(float64); ok {
+				didIndex.P95LookupTimeMs = p95
+			}
+			if p99, ok := didStats["p99_lookup_time_ms"].(float64); ok {
+				didIndex.P99LookupTimeMs = p99
+			}
+			if sampleSize, ok := didStats["recent_sample_size"].(int); ok {
+				didIndex.RecentSampleSize = sampleSize
+			}
+
+			response.DIDIndex = didIndex
+		}
+
+		// Resolver performance stats
+		if s.config.EnableResolver {
+			resolverStats := s.manager.GetResolverStats()
+
+			if totalRes, ok := resolverStats["total_resolutions"].(int64); ok && totalRes > 0 {
+				resolver := &ResolverStatus{
+					Enabled:          true,
+					TotalResolutions: totalRes,
+				}
+
+				// Handle resolver URL
+				if hr := s.manager.GetHandleResolver(); hr != nil {
+					resolver.HandleResolver = hr.GetBaseURL()
+				}
+
+				// Counts
+				if v, ok := resolverStats["mempool_hits"].(int64); ok {
+					resolver.MempoolHits = v
+				}
+				if v, ok := resolverStats["bundle_hits"].(int64); ok {
+					resolver.BundleHits = v
+				}
+				if v, ok := resolverStats["errors"].(int64); ok {
+					resolver.Errors = v
+				}
+				if v, ok := resolverStats["success_rate"].(float64); ok {
+					resolver.SuccessRate = v
+				}
+				if v, ok := resolverStats["mempool_hit_rate"].(float64); ok {
+					resolver.MempoolHitRate = v
+				}
+
+				// Overall averages
+				if v, ok := resolverStats["avg_total_time_ms"].(float64); ok {
+					resolver.AvgTotalTimeMs = v
+				}
+				if v, ok := resolverStats["avg_mempool_time_ms"].(float64); ok {
+					resolver.AvgMempoolTimeMs = v
+				}
+				if v, ok := resolverStats["avg_index_time_ms"].(float64); ok {
+					resolver.AvgIndexTimeMs = v
+				}
+				if v, ok := resolverStats["avg_load_op_time_ms"].(float64); ok {
+					resolver.AvgLoadOpTimeMs = v
+				}
+
+				// Recent averages
+				if v, ok := resolverStats["recent_avg_total_time_ms"].(float64); ok {
+					resolver.RecentAvgTotalTimeMs = v
+				}
+				if v, ok := resolverStats["recent_avg_mempool_time_ms"].(float64); ok {
+					resolver.RecentAvgMempoolTimeMs = v
+				}
+				if v, ok := resolverStats["recent_avg_index_time_ms"].(float64); ok {
+					resolver.RecentAvgIndexTimeMs = v
+				}
+				if v, ok := resolverStats["recent_avg_load_time_ms"].(float64); ok {
+					resolver.RecentAvgLoadTimeMs = v
+				}
+				if v, ok := resolverStats["recent_sample_size"].(int); ok {
+					resolver.RecentSampleSize = v
+				}
+
+				// Percentiles
+				if v, ok := resolverStats["min_total_time_ms"].(float64); ok {
+					resolver.MinTotalTimeMs = v
+				}
+				if v, ok := resolverStats["max_total_time_ms"].(float64); ok {
+					resolver.MaxTotalTimeMs = v
+				}
+				if v, ok := resolverStats["p50_total_time_ms"].(float64); ok {
+					resolver.P50TotalTimeMs = v
+				}
+				if v, ok := resolverStats["p95_total_time_ms"].(float64); ok {
+					resolver.P95TotalTimeMs = v
+				}
+				if v, ok := resolverStats["p99_total_time_ms"].(float64); ok {
+					resolver.P99TotalTimeMs = v
+				}
+				if v, ok := resolverStats["p95_index_time_ms"].(float64); ok {
+					resolver.P95IndexTimeMs = v
+				}
+				if v, ok := resolverStats["p95_load_op_time_ms"].(float64); ok {
+					resolver.P95LoadOpTimeMs = v
+				}
+
+				response.Resolver = resolver
+			} else {
+				// No resolutions yet, but resolver is enabled
+				response.Resolver = &ResolverStatus{
+					Enabled:          true,
+					TotalResolutions: 0,
+				}
+
+				if hr := s.manager.GetHandleResolver(); hr != nil {
+					response.Resolver.HandleResolver = hr.GetBaseURL()
+				}
+			}
+		}
+
 		sendJSON(w, 200, response)
 	}
 }
···
 
 func (s *Server) handleDIDDocument(did string) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
+		// OPTIONS already handled by middleware, but extra safety check
+		if r.Method == "OPTIONS" {
+			return
+		}
+
+		// Track only actual GET requests
 		result, err := s.manager.ResolveDID(r.Context(), did)
 		if err != nil {
 			if strings.Contains(err.Error(), "deactivated") {
···
 			return
 		}
 
-		// Add timing headers in MILLISECONDS (float for precision)
+		// Add timing headers in MILLISECONDS
 		w.Header().Set("X-Resolution-Time-Ms", fmt.Sprintf("%.3f", float64(result.TotalTime.Microseconds())/1000.0))
 		w.Header().Set("X-Resolution-Source", result.Source)
 		w.Header().Set("X-Mempool-Time-Ms", fmt.Sprintf("%.3f", float64(result.MempoolTime.Microseconds())/1000.0))
···
 	w.Header().Set("Cache-Control", "public, max-age=31536000, immutable")
 	w.Header().Set("ETag", op.CID) // CID is perfect for ETag
 }
+
+// handleDIDIndexStats returns detailed DID index performance metrics
+func (s *Server) handleDebugDIDIndex() http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		didStats := s.manager.GetDIDIndexStats()
+
+		if !didStats["enabled"].(bool) || !didStats["exists"].(bool) {
+			sendJSON(w, 404, map[string]string{
+				"error": "DID index not available",
+			})
+			return
+		}
+
+		// Return all stats (more detailed than /status)
+		sendJSON(w, 200, didStats)
+	}
+}
+
+func (s *Server) handleDebugResolver() http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		resolverStats := s.manager.GetResolverStats()
+
+		if resolverStats == nil {
+			sendJSON(w, 404, map[string]string{
+				"error": "Resolver not enabled",
+			})
+			return
+		}
+
+		// Return all stats (more detailed than /status)
+		sendJSON(w, 200, resolverStats)
+	}
+}

server/middleware.go

···
 			return
 		}
 
-		// Normal CORS handling
+		// Set CORS headers for all requests
 		w.Header().Set("Access-Control-Allow-Origin", "*")
-		w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
-
-		if requestedHeaders := r.Header.Get("Access-Control-Request-Headers"); requestedHeaders != "" {
-			w.Header().Set("Access-Control-Allow-Headers", requestedHeaders)
-		} else {
-			w.Header().Set("Access-Control-Allow-Headers", "*")
-		}
-
+		w.Header().Set("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+		w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
 		w.Header().Set("Access-Control-Max-Age", "86400")
+		w.Header().Set("Access-Control-Expose-Headers",
+			"X-Bundle-Number, X-Position, X-Global-Position, X-Pointer, "+
+				"X-Operation-DID, X-Operation-CID, X-Load-Time-Ms, X-Total-Time-Ms, "+
+				"X-Resolution-Time-Ms, X-Resolution-Source, X-Index-Time-Ms")
 
+		// Handle OPTIONS preflight - return immediately WITHOUT calling handler
 		if r.Method == "OPTIONS" {
-			w.WriteHeader(204)
-			return
+			w.WriteHeader(http.StatusNoContent) // 204
+			return                              // STOP HERE - don't call next
 		}
 
+		// Only call handler for non-OPTIONS requests
 		next.ServeHTTP(w, r)
 	})
 }

server/server.go

···
 	"tangled.org/atscan.net/plcbundle/bundle"
 )
 
-// Server serves bundle data over HTTP
-type Server struct {
-	manager    *bundle.Manager
-	addr       string
-	config     *Config
-	startTime  time.Time
-	httpServer *http.Server
-}
-
-// Config configures the server
-type Config struct {
-	Addr            string
-	SyncMode        bool
-	SyncInterval    time.Duration
-	EnableWebSocket bool
-	EnableResolver  bool
-	Version         string
-}
-
 // New creates a new HTTP server
 func New(manager *bundle.Manager, config *Config) *Server {
 	if config.Version == "" {
···
 	return s
 }
 
-// ListenAndServe starts the HTTP server
-func (s *Server) ListenAndServe() error {
-	return s.httpServer.ListenAndServe()
-}
-
-// Shutdown gracefully shuts down the server
-func (s *Server) Shutdown(ctx context.Context) error {
-	return s.httpServer.Shutdown(ctx)
-}
-
 // createHandler creates the HTTP handler with all routes
 func (s *Server) createHandler() http.Handler {
 	mux := http.NewServeMux()
···
 	mux.HandleFunc("GET /op/{pointer}", s.handleOperation())
 	mux.HandleFunc("GET /status", s.handleStatus())
 	mux.HandleFunc("GET /debug/memory", s.handleDebugMemory())
+	mux.HandleFunc("GET /debug/didindex", s.handleDebugDIDIndex())
+	mux.HandleFunc("GET /debug/resolver", s.handleDebugResolver())
 
 	// WebSocket
 	if s.config.EnableWebSocket {
···
 		sendJSON(w, 404, map[string]string{"error": "not found"})
 	})
 
-	return corsMiddleware(mux)
+	// Apply middleware in correct order:
+	handler := corsMiddleware(mux)
+
+	return handler
+}
+
+// ListenAndServe starts the HTTP server
+func (s *Server) ListenAndServe() error {
+	return s.httpServer.ListenAndServe()
+}
+
+// Shutdown gracefully shuts down the server
+func (s *Server) Shutdown(ctx context.Context) error {
+	return s.httpServer.Shutdown(ctx)
 }
 
 // GetStartTime returns when the server started
···
 	return s.startTime
 }
 
-// Add this method to Server
+// Handler returns the configured HTTP handler
 func (s *Server) Handler() http.Handler {
 	return s.createHandler()
 }

server/types.go

···
 package server
 
-import "time"
+import (
+	"net/http"
+	"time"
+
+	"tangled.org/atscan.net/plcbundle/bundle"
+)
+
+// Server serves bundle data over HTTP
+type Server struct {
+	manager    *bundle.Manager
+	addr       string
+	config     *Config
+	startTime  time.Time
+	httpServer *http.Server
+}
+
+// Config configures the server
+type Config struct {
+	Addr            string
+	SyncMode        bool
+	SyncInterval    time.Duration
+	EnableWebSocket bool
+	EnableResolver  bool
+	Version         string
+}
 
 // StatusResponse is the /status endpoint response
 type StatusResponse struct {
-	Bundles BundleStatus   `json:"bundles"`
-	Mempool *MempoolStatus `json:"mempool,omitempty"`
-	Server  ServerStatus   `json:"server"`
+	Server   ServerStatus    `json:"server"`
+	Bundles  BundleStatus    `json:"bundles"`
+	Mempool  *MempoolStatus  `json:"mempool,omitempty"`
+	DIDIndex *DIDIndexStatus `json:"didindex,omitempty"`
+	Resolver *ResolverStatus `json:"resolver,omitempty"`
 }
 
 // ServerStatus contains server information
 type ServerStatus struct {
 	Version             string `json:"version"`
-	UptimeSeconds       int    `json:"uptime_seconds"`
+	Origin              string `json:"origin,omitempty"`
 	SyncMode            bool   `json:"sync_mode"`
 	SyncIntervalSeconds int    `json:"sync_interval_seconds,omitempty"`
 	WebSocketEnabled    bool   `json:"websocket_enabled"`
-	Origin              string `json:"origin,omitempty"`
+	ResolverEnabled     bool   `json:"resolver_enabled"`
+	HandleResolver      string `json:"handle_resolver,omitempty"`
+	UptimeSeconds       int    `json:"uptime_seconds"`
+}
+
+// DIDIndexStatus contains DID index statistics
+type DIDIndexStatus struct {
+	Enabled      bool      `json:"enabled"`
+	Exists       bool      `json:"exists"`
+	TotalDIDs    int64     `json:"total_dids"`
+	IndexedDIDs  int64     `json:"indexed_dids"`
+	MempoolDIDs  int64     `json:"mempool_dids,omitempty"`
+	LastBundle   int       `json:"last_bundle"`
+	ShardCount   int       `json:"shard_count"`
+	CachedShards int       `json:"cached_shards"`
+	CacheLimit   int       `json:"cache_limit"`
+	CacheHitRate float64   `json:"cache_hit_rate"`
+	CacheHits    int64     `json:"cache_hits"`
+	CacheMisses  int64     `json:"cache_misses"`
+	TotalLookups int64     `json:"total_lookups"`
+	UpdatedAt    time.Time `json:"updated_at"`
+	Version      int       `json:"version,omitempty"`
+	Format       string    `json:"format,omitempty"`
+	HotShards    []int     `json:"hot_shards,omitempty"`
+
+	// Lookup performance metrics
+	AvgLookupTimeMs       float64 `json:"avg_lookup_time_ms"`           // All-time average
+	RecentAvgLookupTimeMs float64 `json:"recent_avg_lookup_time_ms"`    // Recent average
+	MinLookupTimeMs       float64 `json:"min_lookup_time_ms,omitempty"` // Fastest
+	MaxLookupTimeMs       float64 `json:"max_lookup_time_ms,omitempty"` // Slowest
+	P50LookupTimeMs       float64 `json:"p50_lookup_time_ms,omitempty"` // Median
+	P95LookupTimeMs       float64 `json:"p95_lookup_time_ms,omitempty"` // 95th percentile
+	P99LookupTimeMs       float64 `json:"p99_lookup_time_ms,omitempty"` // 99th percentile
+	RecentSampleSize      int     `json:"recent_sample_size,omitempty"` // How many samples
+}
+
+// ResolverStatus contains DID document resolver performance metrics
+type ResolverStatus struct {
+	Enabled        bool   `json:"enabled"`
+	HandleResolver string `json:"handle_resolver,omitempty"`
+
+	// Resolution counts
+	TotalResolutions int64   `json:"total_resolutions"`
+	MempoolHits      int64   `json:"mempool_hits"`
+	BundleHits       int64   `json:"bundle_hits"`
+	Errors           int64   `json:"errors"`
+	SuccessRate      float64 `json:"success_rate"`
+	MempoolHitRate   float64 `json:"mempool_hit_rate"`
+
+	// Overall timing (all-time averages)
+	AvgTotalTimeMs   float64 `json:"avg_total_time_ms"`
+	AvgMempoolTimeMs float64 `json:"avg_mempool_time_ms"`
+	AvgIndexTimeMs   float64 `json:"avg_index_time_ms,omitempty"`
+	AvgLoadOpTimeMs  float64 `json:"avg_load_op_time_ms,omitempty"`
+
+	// Recent performance (last N resolutions)
+	RecentAvgTotalTimeMs   float64 `json:"recent_avg_total_time_ms"`
+	RecentAvgMempoolTimeMs float64 `json:"recent_avg_mempool_time_ms"`
+	RecentAvgIndexTimeMs   float64 `json:"recent_avg_index_time_ms,omitempty"`
+	RecentAvgLoadTimeMs    float64 `json:"recent_avg_load_time_ms,omitempty"`
+	RecentSampleSize       int     `json:"recent_sample_size"`
+
+	// Percentiles (total response time)
+	MinTotalTimeMs float64 `json:"min_total_time_ms,omitempty"`
+	MaxTotalTimeMs float64 `json:"max_total_time_ms,omitempty"`
+	P50TotalTimeMs float64 `json:"p50_total_time_ms,omitempty"`
+	P95TotalTimeMs float64 `json:"p95_total_time_ms,omitempty"`
+	P99TotalTimeMs float64 `json:"p99_total_time_ms,omitempty"`
+
+	// Breakdown percentiles (for bundle resolutions only)
+	P95IndexTimeMs  float64 `json:"p95_index_time_ms,omitempty"`
+	P95LoadOpTimeMs float64 `json:"p95_load_op_time_ms,omitempty"`
 }
 
 // BundleStatus contains bundle statistics
···
 	LastOpAgeSeconds     int       `json:"last_op_age_seconds,omitempty"`
 	EtaNextBundleSeconds int       `json:"eta_next_bundle_seconds,omitempty"`
 }
+
+// RequestLog represents a logged HTTP request
+type RequestLog struct {
+	Timestamp  time.Time `json:"timestamp"`
+	Method     string    `json:"method"`
+	Path       string    `json:"path"`
+	UserAgent  string    `json:"user_agent"`
+	RemoteAddr string    `json:"remote_addr"`
+}