cmd index

cmd/plcbundle/commands/common.go

···
 	GetDIDIndexStats() map[string]interface{}
 	GetDIDIndex() *didindex.Manager
 	BuildDIDIndex(ctx context.Context, progress func(int, int)) error
+	GetDIDOperations(ctx context.Context, did string, verbose bool) ([]plcclient.PLCOperation, error)
 	GetDIDOperationsWithLocations(ctx context.Context, did string, verbose bool) ([]bundle.PLCOperationWithLocation, error)
 	GetDIDOperationsFromMempool(did string) ([]plcclient.PLCOperation, error)
 	GetLatestDIDOperation(ctx context.Context, did string) (*plcclient.PLCOperation, error)
···
 	ResolveDID(ctx context.Context, did string) (*bundle.ResolveDIDResult, error)
 	RunSyncOnce(ctx context.Context, config *internalsync.SyncLoopConfig, verbose bool) (int, error)
 	RunSyncLoop(ctx context.Context, config *internalsync.SyncLoopConfig) error
+	GetBundleIndex() didindex.BundleIndexProvider
+	ScanDirectoryParallel(workers int, progressCallback func(current, total int, bytesProcessed int64)) (*bundle.DirectoryScanResult, error)
+	LoadBundleForDIDIndex(ctx context.Context, bundleNumber int) (*didindex.BundleData, error)
 }
 
 // PLCOperationWithLocation wraps operation with location info

cmd/plcbundle/commands/did.go

···
 
 	return nil
 }
+
+// ============================================================================
+// Shared Helper Functions (used by both DID and legacy index commands)
+// ============================================================================
+
+func outputLookupJSON(did string, opsWithLoc []PLCOperationWithLocation, mempoolOps []plcclient.PLCOperation, totalElapsed, lookupElapsed, mempoolElapsed time.Duration) error {
+	output := map[string]interface{}{
+		"found": true,
+		"did":   did,
+		"timing": map[string]interface{}{
+			"total_ms":   totalElapsed.Milliseconds(),
+			"lookup_ms":  lookupElapsed.Milliseconds(),
+			"mempool_ms": mempoolElapsed.Milliseconds(),
+		},
+		"bundled": make([]map[string]interface{}, 0),
+		"mempool": make([]map[string]interface{}, 0),
+	}
+
+	for _, owl := range opsWithLoc {
+		output["bundled"] = append(output["bundled"].([]map[string]interface{}), map[string]interface{}{
+			"bundle":     owl.Bundle,
+			"position":   owl.Position,
+			"cid":        owl.Operation.CID,
+			"nullified":  owl.Operation.IsNullified(),
+			"created_at": owl.Operation.CreatedAt.Format(time.RFC3339Nano),
+		})
+	}
+
+	for _, op := range mempoolOps {
+		output["mempool"] = append(output["mempool"].([]map[string]interface{}), map[string]interface{}{
+			"cid":        op.CID,
+			"nullified":  op.IsNullified(),
+			"created_at": op.CreatedAt.Format(time.RFC3339Nano),
+		})
+	}
+
+	data, _ := json.MarshalIndent(output, "", "  ")
+	fmt.Println(string(data))
+
+	return nil
+}
+
+func displayLookupResults(did string, opsWithLoc []PLCOperationWithLocation, mempoolOps []plcclient.PLCOperation, totalElapsed, lookupElapsed, mempoolElapsed time.Duration, verbose bool, stats map[string]interface{}) error {
+	nullifiedCount := 0
+	for _, owl := range opsWithLoc {
+		if owl.Operation.IsNullified() {
+			nullifiedCount++
+		}
+	}
+
+	totalOps := len(opsWithLoc) + len(mempoolOps)
+	activeOps := len(opsWithLoc) - nullifiedCount + len(mempoolOps)
+
+	fmt.Printf("═══════════════════════════════════════════════════════════════\n")
+	fmt.Printf("                    DID Lookup Results\n")
+	fmt.Printf("═══════════════════════════════════════════════════════════════\n\n")
+	fmt.Printf("DID: %s\n\n", did)
+
+	fmt.Printf("Summary\n───────\n")
+	fmt.Printf("  Total operations:   %d\n", totalOps)
+	fmt.Printf("  Active operations:  %d\n", activeOps)
+	if nullifiedCount > 0 {
+		fmt.Printf("  Nullified:          %d\n", nullifiedCount)
+	}
+	if len(opsWithLoc) > 0 {
+		fmt.Printf("  Bundled:            %d\n", len(opsWithLoc))
+	}
+	if len(mempoolOps) > 0 {
+		fmt.Printf("  Mempool:            %d\n", len(mempoolOps))
+	}
+	fmt.Printf("\n")
+
+	fmt.Printf("Performance\n───────────\n")
+	fmt.Printf("  Index lookup:       %s\n", lookupElapsed)
+	fmt.Printf("  Mempool check:      %s\n", mempoolElapsed)
+	fmt.Printf("  Total time:         %s\n\n", totalElapsed)
+
+	// Show operations
+	if len(opsWithLoc) > 0 {
+		fmt.Printf("Bundled Operations (%d total)\n", len(opsWithLoc))
+		fmt.Printf("══════════════════════════════════════════════════════════════\n\n")
+
+		for i, owl := range opsWithLoc {
+			op := owl.Operation
+			status := "✓ Active"
+			if op.IsNullified() {
+				status = "✗ Nullified"
+			}
+
+			fmt.Printf("Operation %d [Bundle %06d, Position %04d]\n", i+1, owl.Bundle, owl.Position)
+			fmt.Printf("   CID:        %s\n", op.CID)
+			fmt.Printf("   Created:    %s\n", op.CreatedAt.Format("2006-01-02 15:04:05.000 MST"))
+			fmt.Printf("   Status:     %s\n", status)
+
+			if verbose && !op.IsNullified() {
+				showOperationDetails(&op)
+			}
+
+			fmt.Printf("\n")
+		}
+	}
+
+	fmt.Printf("═══════════════════════════════════════════════════════════════\n")
+	fmt.Printf("✓ Lookup complete in %s\n", totalElapsed)
+	if stats["exists"].(bool) {
+		fmt.Printf("  Method: DID index (fast)\n")
+	} else {
+		fmt.Printf("  Method: Full scan (slow)\n")
+	}
+	fmt.Printf("═══════════════════════════════════════════════════════════════\n")
+
+	return nil
+}
+
+func showOperationDetails(op *plcclient.PLCOperation) {
+	if opData, err := op.GetOperationData(); err == nil && opData != nil {
+		if opType, ok := opData["type"].(string); ok {
+			fmt.Printf("   Type:       %s\n", opType)
+		}
+
+		if handle, ok := opData["handle"].(string); ok {
+			fmt.Printf("   Handle:     %s\n", handle)
+		} else if aka, ok := opData["alsoKnownAs"].([]interface{}); ok && len(aka) > 0 {
+			if akaStr, ok := aka[0].(string); ok {
+				handle := strings.TrimPrefix(akaStr, "at://")
+				fmt.Printf("   Handle:     %s\n", handle)
+			}
+		}
+	}
+}

cmd/plcbundle/commands/index.go

···
+// repo/cmd/plcbundle/commands/index.go
 package commands
 
 import (
 	"context"
 	"fmt"
-	"os"
-	"strings"
 	"time"
-
-	flag "github.com/spf13/pflag"
 
 	"github.com/goccy/go-json"
+	"github.com/spf13/cobra"
 	"tangled.org/atscan.net/plcbundle/cmd/plcbundle/ui"
-	"tangled.org/atscan.net/plcbundle/internal/plcclient"
 )
 
-// IndexCommand handles the index subcommand
-func IndexCommand(args []string) error {
-	if len(args) < 1 {
-		printIndexUsage()
-		return fmt.Errorf("subcommand required")
+func NewIndexCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "index",
+		Short: "DID index management",
+		Long: `DID index management operations
+
+Manage the DID position index which maps DIDs to their bundle locations.
+This index enables fast O(1) DID lookups and is required for DID
+resolution and query operations.`,
+
+		Example: `  # Build DID position index
+  plcbundle index build
+
+  # Repair DID index (rebuild from bundles)
+  plcbundle index repair
+
+  # Show DID index statistics
+  plcbundle index stats
+
+  # Verify DID index integrity
+  plcbundle index verify`,
 	}
 
-	subcommand := args[0]
+	cmd.AddCommand(newIndexBuildCommand())
+	cmd.AddCommand(newIndexRepairCommand())
+	cmd.AddCommand(newIndexStatsCommand())
+	cmd.AddCommand(newIndexVerifyCommand())
 
-	switch subcommand {
-	case "build":
-		return indexBuild(args[1:])
-	case "stats":
-		return indexStats(args[1:])
-	case "lookup":
-		return indexLookup(args[1:])
-	case "resolve":
-		return indexResolve(args[1:])
-	default:
-		printIndexUsage()
-		return fmt.Errorf("unknown index subcommand: %s", subcommand)
-	}
+	return cmd
 }
 
-func printIndexUsage() {
-	fmt.Printf(`Usage: plcbundle index <command> [options]
+// ============================================================================
+// INDEX BUILD - Build DID position index
+// ============================================================================
+
+func newIndexBuildCommand() *cobra.Command {
+	var force bool
+
+	cmd := &cobra.Command{
+		Use:   "build",
+		Short: "Build DID position index",
+		Long: `Build DID position index from bundles
 
-Commands:
-  build     Build DID index from bundles
-  stats     Show index statistics
-  lookup    Lookup a specific DID
-  resolve   Resolve DID to current document
+Creates a sharded index mapping each DID to its bundle locations,
+enabling fast O(1) DID lookups. Required for DID resolution.
+
+The index is built incrementally and auto-updates as new bundles
+are added. Use --force to rebuild from scratch.`,
 
-Examples:
+		Example: `  # Build index
   plcbundle index build
-  plcbundle index stats
-  plcbundle index lookup did:plc:524tuhdhh3m7li5gycdn6boe
-  plcbundle index resolve did:plc:524tuhdhh3m7li5gycdn6boe
-`)
-}
+
+  # Force rebuild from scratch
+  plcbundle index build --force`,
 
-func indexBuild(args []string) error {
-	fs := flag.NewFlagSet("index build", flag.ExitOnError)
-	force := fs.Bool("force", false, "rebuild even if index exists")
+		RunE: func(cmd *cobra.Command, args []string) error {
+			mgr, dir, err := getManager(&ManagerOptions{Cmd: cmd})
+			if err != nil {
+				return err
+			}
+			defer mgr.Close()
 
-	if err := fs.Parse(args); err != nil {
-		return err
-	}
+			stats := mgr.GetDIDIndexStats()
+			if stats["exists"].(bool) && !force {
+				fmt.Printf("DID index already exists (use --force to rebuild)\n")
+				fmt.Printf("Directory: %s\n", dir)
+				fmt.Printf("Total DIDs: %s\n", formatNumber(int(stats["total_dids"].(int64))))
+				return nil
+			}
 
-	mgr, dir, err := getManager(nil)
-	if err != nil {
-		return err
-	}
-	defer mgr.Close()
+			index := mgr.GetIndex()
+			bundleCount := index.Count()
 
-	stats := mgr.GetDIDIndexStats()
-	if stats["exists"].(bool) && !*force {
-		fmt.Printf("DID index already exists (use --force to rebuild)\n")
-		fmt.Printf("Directory: %s\n", dir)
-		fmt.Printf("Total DIDs: %d\n", stats["total_dids"])
-		return nil
-	}
+			if bundleCount == 0 {
+				fmt.Printf("No bundles to index\n")
+				return nil
+			}
 
-	fmt.Printf("Building DID index in: %s\n", dir)
+			fmt.Printf("Building DID index in: %s\n", dir)
+			fmt.Printf("Indexing %d bundles...\n\n", bundleCount)
 
-	index := mgr.GetIndex()
-	bundleCount := index.Count()
+			progress := ui.NewProgressBar(bundleCount)
+			start := time.Now()
+			ctx := context.Background()
 
-	if bundleCount == 0 {
-		fmt.Printf("No bundles to index\n")
-		return nil
-	}
+			err = mgr.BuildDIDIndex(ctx, func(current, total int) {
+				progress.Set(current)
+			})
 
-	fmt.Printf("Indexing %d bundles...\n\n", bundleCount)
+			progress.Finish()
 
-	progress := ui.NewProgressBar(bundleCount)
-	start := time.Now()
-	ctx := context.Background()
+			if err != nil {
+				return fmt.Errorf("build failed: %w", err)
+			}
 
-	err = mgr.BuildDIDIndex(ctx, func(current, total int) {
-		progress.Set(current)
-	})
+			elapsed := time.Since(start)
+			stats = mgr.GetDIDIndexStats()
 
-	progress.Finish()
+			fmt.Printf("\n✓ DID index built in %s\n", elapsed.Round(time.Millisecond))
+			fmt.Printf("  Total DIDs: %s\n", formatNumber(int(stats["total_dids"].(int64))))
+			fmt.Printf("  Shards: %d\n", stats["shard_count"])
+			fmt.Printf("  Location: %s/.plcbundle/\n", dir)
 
-	if err != nil {
-		return fmt.Errorf("error building index: %w", err)
+			return nil
+		},
 	}
 
-	elapsed := time.Since(start)
-	stats = mgr.GetDIDIndexStats()
-
-	fmt.Printf("\n✓ DID index built in %s\n", elapsed.Round(time.Millisecond))
-	fmt.Printf("  Total DIDs: %s\n", formatNumber(int(stats["total_dids"].(int64))))
-	fmt.Printf("  Shards: %d\n", stats["shard_count"])
-	fmt.Printf("  Location: %s/.plcbundle/\n", dir)
+	cmd.Flags().BoolVar(&force, "force", false, "Rebuild even if index exists")
 
-	return nil
+	return cmd
 }
 
-func indexStats(args []string) error {
-	mgr, dir, err := getManager(nil)
-	if err != nil {
-		return err
-	}
-	defer mgr.Close()
+// ============================================================================
+// INDEX REPAIR - Repair/rebuild DID index
+// ============================================================================
 
-	stats := mgr.GetDIDIndexStats()
+func newIndexRepairCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "repair",
+		Aliases: []string{"rebuild"},
+		Short:   "Repair DID index",
+		Long: `Repair DID index by rebuilding from bundles
 
-	if !stats["exists"].(bool) {
-		fmt.Printf("DID index does not exist\n")
-		fmt.Printf("Run: plcbundle index build\n")
-		return nil
-	}
+Rebuilds the DID index from scratch and verifies consistency.
+Use this when:
+  • DID index is corrupted
+  • Index is out of sync with bundles
+  • After manual bundle operations
+  • Upgrade to new index version`,
 
-	indexedDIDs := stats["indexed_dids"].(int64)
-	mempoolDIDs := stats["mempool_dids"].(int64)
-	totalDIDs := stats["total_dids"].(int64)
+		Example: `  # Repair DID index
+  plcbundle index repair
 
-	fmt.Printf("\nDID Index Statistics\n")
-	fmt.Printf("════════════════════\n\n")
-	fmt.Printf("  Location:      %s/.plcbundle/\n", dir)
+  # Verbose output
+  plcbundle index repair -v`,
 
-	if mempoolDIDs > 0 {
-		fmt.Printf("  Indexed DIDs:  %s (in bundles)\n", formatNumber(int(indexedDIDs)))
-		fmt.Printf("  Mempool DIDs:  %s (not yet bundled)\n", formatNumber(int(mempoolDIDs)))
-		fmt.Printf("  Total DIDs:    %s\n", formatNumber(int(totalDIDs)))
-	} else {
-		fmt.Printf("  Total DIDs:    %s\n", formatNumber(int(totalDIDs)))
-	}
+		RunE: func(cmd *cobra.Command, args []string) error {
+			verbose, _ := cmd.Root().PersistentFlags().GetBool("verbose")
 
-	fmt.Printf("  Shard count:   %d\n", stats["shard_count"])
-	fmt.Printf("  Last bundle:   %06d\n", stats["last_bundle"])
-	fmt.Printf("  Updated:       %s\n\n", stats["updated_at"].(time.Time).Format("2006-01-02 15:04:05"))
-	fmt.Printf("  Cached shards: %d / %d\n", stats["cached_shards"], stats["cache_limit"])
+			mgr, dir, err := getManager(&ManagerOptions{Cmd: cmd})
+			if err != nil {
+				return err
+			}
+			defer mgr.Close()
 
-	if cachedList, ok := stats["cache_order"].([]int); ok && len(cachedList) > 0 {
-		fmt.Printf("  Hot shards:    ")
-		for i, shard := range cachedList {
-			if i > 0 {
-				fmt.Printf(", ")
+			stats := mgr.GetDIDIndexStats()
+			if !stats["exists"].(bool) {
+				fmt.Printf("DID index does not exist\n")
+				fmt.Printf("Use: plcbundle index build\n")
+				return nil
 			}
-			if i >= 10 {
-				fmt.Printf("... (+%d more)", len(cachedList)-10)
-				break
+
+			fmt.Printf("Repairing DID index in: %s\n\n", dir)
+
+			index := mgr.GetIndex()
+			bundleCount := index.Count()
+
+			if bundleCount == 0 {
+				fmt.Printf("No bundles to index\n")
+				return nil
 			}
-			fmt.Printf("%02x", shard)
-		}
-		fmt.Printf("\n")
-	}
 
-	fmt.Printf("\n")
-	return nil
-}
+			fmt.Printf("Rebuilding index from %d bundles...\n\n", bundleCount)
 
-func indexLookup(args []string) error {
-	fs := flag.NewFlagSet("index lookup", flag.ExitOnError)
-	verbose := fs.Bool("v", false, "verbose debug output")
-	showJSON := fs.Bool("json", false, "output as JSON")
+			var progress *ui.ProgressBar
+			if !verbose {
+				progress = ui.NewProgressBar(bundleCount)
+			}
 
-	if err := fs.Parse(args); err != nil {
-		return err
-	}
+			start := time.Now()
+			ctx := context.Background()
 
-	if fs.NArg() < 1 {
-		return fmt.Errorf("usage: plcbundle index lookup <did> [-v] [--json]")
-	}
+			err = mgr.BuildDIDIndex(ctx, func(current, total int) {
+				if progress != nil {
+					progress.Set(current)
+				} else if current%100 == 0 || current == total {
+					fmt.Printf("Progress: %d/%d (%.1f%%)   \r",
+						current, total, float64(current)/float64(total)*100)
+				}
+			})
 
-	did := fs.Arg(0)
+			if progress != nil {
+				progress.Finish()
+			}
 
-	mgr, _, err := getManager(nil)
-	if err != nil {
-		return err
-	}
-	defer mgr.Close()
+			if err != nil {
+				return fmt.Errorf("repair failed: %w", err)
+			}
 
-	stats := mgr.GetDIDIndexStats()
-	if !stats["exists"].(bool) {
-		fmt.Fprintf(os.Stderr, "⚠️  DID index does not exist. Run: plcbundle index build\n")
-		fmt.Fprintf(os.Stderr, "    Falling back to full scan (this will be slow)...\n\n")
-	}
+			// Verify consistency
+			fmt.Printf("\nVerifying consistency...\n")
+			if err := mgr.GetDIDIndex().VerifyAndRepairIndex(ctx, mgr); err != nil {
+				return fmt.Errorf("verification failed: %w", err)
+			}
 
-	if !*showJSON {
-		fmt.Printf("Looking up: %s\n", did)
-		if *verbose {
-			fmt.Printf("Verbose mode: enabled\n")
-		}
-		fmt.Printf("\n")
-	}
+			elapsed := time.Since(start)
+			stats = mgr.GetDIDIndexStats()
 
-	totalStart := time.Now()
-	ctx := context.Background()
+			fmt.Printf("\n✓ DID index repaired in %s\n", elapsed.Round(time.Millisecond))
+			fmt.Printf("  Total DIDs: %s\n", formatNumber(int(stats["total_dids"].(int64))))
+			fmt.Printf("  Shards: %d\n", stats["shard_count"])
+			fmt.Printf("  Last bundle: %06d\n", stats["last_bundle"])
 
-	// Lookup operations
-	lookupStart := time.Now()
-	opsWithLoc, err := mgr.GetDIDOperationsWithLocations(ctx, did, *verbose)
-	if err != nil {
-		return err
+			return nil
+		},
 	}
-	lookupElapsed := time.Since(lookupStart)
 
-	// Check mempool
-	mempoolStart := time.Now()
-	mempoolOps, err := mgr.GetDIDOperationsFromMempool(did)
-	if err != nil {
-		return fmt.Errorf("error checking mempool: %w", err)
-	}
-	mempoolElapsed := time.Since(mempoolStart)
+	return cmd
+}
 
-	totalElapsed := time.Since(totalStart)
+// ============================================================================
+// INDEX STATS - Show DID index statistics
+// ============================================================================
 
-	if len(opsWithLoc) == 0 && len(mempoolOps) == 0 {
-		if *showJSON {
-			fmt.Println("{\"found\": false, \"operations\": []}")
-		} else {
-			fmt.Printf("DID not found (searched in %s)\n", totalElapsed)
-		}
-		return nil
-	}
+func newIndexStatsCommand() *cobra.Command {
+	var showJSON bool
 
-	if *showJSON {
-		return outputLookupJSON(did, opsWithLoc, mempoolOps, totalElapsed, lookupElapsed, mempoolElapsed)
-	}
+	cmd := &cobra.Command{
+		Use:     "stats",
+		Aliases: []string{"info"},
+		Short:   "Show DID index statistics",
+		Long: `Show DID index statistics
 
-	return displayLookupResults(did, opsWithLoc, mempoolOps, totalElapsed, lookupElapsed, mempoolElapsed, *verbose, stats)
-}
+Displays DID index information including total DIDs indexed,
+shard distribution, cache statistics, and coverage.`,
 
-func indexResolve(args []string) error {
-	fs := flag.NewFlagSet("index resolve", flag.ExitOnError)
-	verbose := fs.BoolP("verbose", "v", false, "verbose timing breakdown")
+		Example: `  # Show statistics
+  plcbundle index stats
 
-	if err := fs.Parse(args); err != nil {
-		return err
-	}
+  # JSON output
+  plcbundle index stats --json`,
 
-	if fs.NArg() < 1 {
-		return fmt.Errorf("usage: plcbundle index resolve <did> [-v]")
-	}
+		RunE: func(cmd *cobra.Command, args []string) error {
+			mgr, dir, err := getManager(&ManagerOptions{Cmd: cmd})
+			if err != nil {
+				return err
+			}
+			defer mgr.Close()
 
-	did := fs.Arg(0)
+			stats := mgr.GetDIDIndexStats()
 
-	mgr, _, err := getManager(nil)
-	if err != nil {
-		return err
-	}
-	defer mgr.Close()
+			if showJSON {
+				data, _ := json.MarshalIndent(stats, "", "  ")
+				fmt.Println(string(data))
+				return nil
+			}
 
-	ctx := context.Background()
-	fmt.Fprintf(os.Stderr, "Resolving: %s\n", did)
+			if !stats["exists"].(bool) {
+				fmt.Printf("DID index does not exist\n")
+				fmt.Printf("Run: plcbundle index build\n")
+				return nil
+			}
 
-	if *verbose {
-		mgr.GetDIDIndex().SetVerbose(true)
-	}
+			indexedDIDs := stats["indexed_dids"].(int64)
+			mempoolDIDs := stats["mempool_dids"].(int64)
+			totalDIDs := stats["total_dids"].(int64)
 
-	// Use unified resolution method with metrics
-	result, err := mgr.ResolveDID(ctx, did)
-	if err != nil {
-		return err
-	}
+			fmt.Printf("\nDID Index Statistics\n")
+			fmt.Printf("════════════════════\n\n")
+			fmt.Printf("  Location:      %s/.plcbundle/\n", dir)
 
-	// Display timing metrics
-	if result.Source == "mempool" {
-		fmt.Fprintf(os.Stderr, "Mempool check: %s (✓ found in mempool)\n", result.MempoolTime)
-		fmt.Fprintf(os.Stderr, "Total: %s (resolved from mempool)\n\n", result.TotalTime)
-	} else {
-		fmt.Fprintf(os.Stderr, "Mempool check: %s (not found)\n", result.MempoolTime)
-		fmt.Fprintf(os.Stderr, "Index lookup: %s (shard access)\n", result.IndexTime)
-		fmt.Fprintf(os.Stderr, "Operation load: %s (bundle %d, pos %d)\n",
-			result.LoadOpTime, result.BundleNumber, result.Position)
-		fmt.Fprintf(os.Stderr, "Total: %s\n", result.TotalTime)
+			if mempoolDIDs > 0 {
+				fmt.Printf("  Indexed DIDs:  %s (in bundles)\n", formatNumber(int(indexedDIDs)))
+				fmt.Printf("  Mempool DIDs:  %s (not yet bundled)\n", formatNumber(int(mempoolDIDs)))
+				fmt.Printf("  Total DIDs:    %s\n", formatNumber(int(totalDIDs)))
+			} else {
+				fmt.Printf("  Total DIDs:    %s\n", formatNumber(int(totalDIDs)))
+			}
 
-		// Verbose timing breakdown
-		if *verbose {
-			fmt.Fprintf(os.Stderr, "\nTiming breakdown:\n")
-			fmt.Fprintf(os.Stderr, "  Mempool:   %6s (%5.1f%%)\n",
-				result.MempoolTime, float64(result.MempoolTime)/float64(result.TotalTime)*100)
-			fmt.Fprintf(os.Stderr, "  Index:     %6s (%5.1f%%)\n",
-				result.IndexTime, float64(result.IndexTime)/float64(result.TotalTime)*100)
-			fmt.Fprintf(os.Stderr, "  Load op:   %6s (%5.1f%%)\n",
-				result.LoadOpTime, float64(result.LoadOpTime)/float64(result.TotalTime)*100)
-		}
-		fmt.Fprintf(os.Stderr, "\n")
-	}
+			fmt.Printf("  Shard count:   %d\n", stats["shard_count"])
+			fmt.Printf("  Last bundle:   %06d\n", stats["last_bundle"])
+			fmt.Printf("  Updated:       %s\n\n", stats["updated_at"].(time.Time).Format("2006-01-02 15:04:05"))
 
-	// Output document to stdout
-	data, _ := json.MarshalIndent(result.Document, "", "  ")
-	fmt.Println(string(data))
+			fmt.Printf("  Cached shards: %d / %d\n", stats["cached_shards"], stats["cache_limit"])
 
-	return nil
-}
+			if cachedList, ok := stats["cache_order"].([]int); ok && len(cachedList) > 0 {
+				fmt.Printf("  Hot shards:    ")
+				for i, shard := range cachedList {
+					if i > 0 {
+						fmt.Printf(", ")
+					}
+					if i >= 10 {
+						fmt.Printf("... (+%d more)", len(cachedList)-10)
+						break
+					}
+					fmt.Printf("%02x", shard)
+				}
+				fmt.Printf("\n")
+			}
 
-func outputLookupJSON(did string, opsWithLoc []PLCOperationWithLocation, mempoolOps []plcclient.PLCOperation, totalElapsed, lookupElapsed, mempoolElapsed time.Duration) error {
-	output := map[string]interface{}{
-		"found": true,
-		"did":   did,
-		"timing": map[string]interface{}{
-			"total_ms":   totalElapsed.Milliseconds(),
-			"lookup_ms":  lookupElapsed.Milliseconds(),
-			"mempool_ms": mempoolElapsed.Milliseconds(),
+			fmt.Printf("\n")
+			return nil
 		},
-		"bundled": make([]map[string]interface{}, 0),
-		"mempool": make([]map[string]interface{}, 0),
 	}
 
-	for _, owl := range opsWithLoc {
-		output["bundled"] = append(output["bundled"].([]map[string]interface{}), map[string]interface{}{
-			"bundle":     owl.Bundle,
-			"position":   owl.Position,
-			"cid":        owl.Operation.CID,
-			"nullified":  owl.Operation.IsNullified(),
-			"created_at": owl.Operation.CreatedAt.Format(time.RFC3339Nano),
-		})
-	}
+	cmd.Flags().BoolVar(&showJSON, "json", false, "Output as JSON")
 
-	for _, op := range mempoolOps {
-		output["mempool"] = append(output["mempool"].([]map[string]interface{}), map[string]interface{}{
-			"cid":        op.CID,
-			"nullified":  op.IsNullified(),
-			"created_at": op.CreatedAt.Format(time.RFC3339Nano),
-		})
-	}
-
-	data, _ := json.MarshalIndent(output, "", "  ")
-	fmt.Println(string(data))
-
-	return nil
+	return cmd
 }
 
-func displayLookupResults(did string, opsWithLoc []PLCOperationWithLocation, mempoolOps []plcclient.PLCOperation, totalElapsed, lookupElapsed, mempoolElapsed time.Duration, verbose bool, stats map[string]interface{}) error {
-	nullifiedCount := 0
-	for _, owl := range opsWithLoc {
-		if owl.Operation.IsNullified() {
-			nullifiedCount++
-		}
-	}
+// ============================================================================
+// INDEX VERIFY - Verify DID index integrity
+// ============================================================================
 
-	totalOps := len(opsWithLoc) + len(mempoolOps)
-	activeOps := len(opsWithLoc) - nullifiedCount + len(mempoolOps)
+func newIndexVerifyCommand() *cobra.Command {
+	var verbose bool
 
-	fmt.Printf("═══════════════════════════════════════════════════════════════\n")
-	fmt.Printf("                    DID Lookup Results\n")
-	fmt.Printf("═══════════════════════════════════════════════════════════════\n\n")
-	fmt.Printf("DID: %s\n\n", did)
+	cmd := &cobra.Command{
+		Use:     "verify",
+		Aliases: []string{"check"},
+		Short:   "Verify DID index integrity",
+		Long: `Verify DID index integrity and consistency
 
-	fmt.Printf("Summary\n───────\n")
-	fmt.Printf("  Total operations:   %d\n", totalOps)
-	fmt.Printf("  Active operations:  %d\n", activeOps)
-	if nullifiedCount > 0 {
-		fmt.Printf("  Nullified:          %d\n", nullifiedCount)
-	}
-	if len(opsWithLoc) > 0 {
-		fmt.Printf("  Bundled:            %d\n", len(opsWithLoc))
-	}
-	if len(mempoolOps) > 0 {
-		fmt.Printf("  Mempool:            %d\n", len(mempoolOps))
-	}
-	fmt.Printf("\n")
+Checks the DID index for consistency with bundles:
+  • Index version is current
+  • All bundles are indexed
+  • Shard files are valid
+  • No corruption detected
 
-	fmt.Printf("Performance\n───────────\n")
-	fmt.Printf("  Index lookup:       %s\n", lookupElapsed)
-	fmt.Printf("  Mempool check:      %s\n", mempoolElapsed)
-	fmt.Printf("  Total time:         %s\n\n", totalElapsed)
+Automatically repairs minor issues.`,
 
-	// Show operations
-	if len(opsWithLoc) > 0 {
-		fmt.Printf("Bundled Operations (%d total)\n", len(opsWithLoc))
-		fmt.Printf("══════════════════════════════════════════════════════════════\n\n")
+		Example: `  # Verify DID index
+  plcbundle index verify
 
-		for i, owl := range opsWithLoc {
-			op := owl.Operation
-			status := "✓ Active"
-			if op.IsNullified() {
-				status = "✗ Nullified"
+  # Verbose output
+  plcbundle index verify -v`,
+
+		RunE: func(cmd *cobra.Command, args []string) error {
+			mgr, dir, err := getManager(&ManagerOptions{Cmd: cmd})
+			if err != nil {
+				return err
 			}
+			defer mgr.Close()
 
-			fmt.Printf("Operation %d [Bundle %06d, Position %04d]\n", i+1, owl.Bundle, owl.Position)
-			fmt.Printf("   CID:        %s\n", op.CID)
-			fmt.Printf("   Created:    %s\n", op.CreatedAt.Format("2006-01-02 15:04:05.000 MST"))
-			fmt.Printf("   Status:     %s\n", status)
+			stats := mgr.GetDIDIndexStats()
 
-			if verbose && !op.IsNullified() {
-				showOperationDetails(&op)
+			if !stats["exists"].(bool) {
+				fmt.Printf("DID index does not exist\n")
+				fmt.Printf("Run: plcbundle index build\n")
+				return nil
 			}
 
-			fmt.Printf("\n")
-		}
-	}
+			fmt.Printf("Verifying DID index in: %s\n\n", dir)
 
-	fmt.Printf("═══════════════════════════════════════════════════════════════\n")
-	fmt.Printf("✓ Lookup complete in %s\n", totalElapsed)
-	if stats["exists"].(bool) {
-		fmt.Printf("  Method: DID index (fast)\n")
-	} else {
-		fmt.Printf("  Method: Full scan (slow)\n")
-	}
-	fmt.Printf("═══════════════════════════════════════════════════════════════\n")
+			ctx := context.Background()
 
-	return nil
-}
+			if verbose {
+				fmt.Printf("Index version: %d\n", mgr.GetDIDIndex().GetConfig().Version)
+				fmt.Printf("Total DIDs:    %s\n", formatNumber(int(stats["total_dids"].(int64))))
+				fmt.Printf("Shards:        %d\n", stats["shard_count"])
+				fmt.Printf("Last bundle:   %06d\n\n", stats["last_bundle"])
+			}
 
-func showOperationDetails(op *plcclient.PLCOperation) {
-	if opData, err := op.GetOperationData(); err == nil && opData != nil {
-		if opType, ok := opData["type"].(string); ok {
-			fmt.Printf("   Type:       %s\n", opType)
-		}
+			fmt.Printf("Checking consistency with bundles...\n")
 
-		if handle, ok := opData["handle"].(string); ok {
-			fmt.Printf("   Handle:     %s\n", handle)
-		} else if aka, ok := opData["alsoKnownAs"].([]interface{}); ok && len(aka) > 0 {
-			if akaStr, ok := aka[0].(string); ok {
-				handle := strings.TrimPrefix(akaStr, "at://")
-				fmt.Printf("   Handle:     %s\n", handle)
+			if err := mgr.GetDIDIndex().VerifyAndRepairIndex(ctx, mgr); err != nil {
+				fmt.Printf("\n✗ DID index verification failed\n")
+				fmt.Printf("  Error: %v\n", err)
+				return fmt.Errorf("verification failed: %w", err)
 			}
-		}
+
+			stats = mgr.GetDIDIndexStats()
+
+			fmt.Printf("\n✓ DID index is valid\n")
+			fmt.Printf("  Total DIDs:  %s\n", formatNumber(int(stats["total_dids"].(int64))))
+			fmt.Printf("  Shards:      %d\n", stats["shard_count"])
+			fmt.Printf("  Last bundle: %06d\n", stats["last_bundle"])
+
+			return nil
+		},
 	}
+
+	cmd.Flags().BoolVarP(&verbose, "verbose", "v", false, "Verbose output")
+
+	return cmd
 }

cmd/plcbundle/main.go

···
 
 	// Namespaced commands
 	cmd.AddCommand(commands.NewDIDCommand())
-	//cmd.AddCommand(commands.NewIndexCommand())
+	cmd.AddCommand(commands.NewIndexCommand())
 	cmd.AddCommand(commands.NewMempoolCommand())
 	/*cmd.AddCommand(commands.NewDetectorCommand())