basics for did resolver

bundle/did_index.go

···
+package bundle
+
+import (
+	"encoding/binary"
+	"fmt"
+	"hash/fnv"
+	"os"
+	"path/filepath"
+	"sort"
+	"sync"
+	"syscall"
+	"time"
+
+	"github.com/goccy/go-json"
+	"tangled.org/atscan.net/plcbundle/plc"
+)
+
+const (
+	DID_INDEX_DIR      = ".plcbundle"
+	DID_INDEX_SHARDS   = "shards"
+	DID_INDEX_CONFIG   = "config.json"
+	DID_SHARD_COUNT    = 256
+	DID_PREFIX         = "did:plc:"
+	DID_IDENTIFIER_LEN = 24 // Without "did:plc:" prefix
+
+	// Binary format constants (renamed to avoid conflict)
+	DIDINDEX_MAGIC   = "PLCD"
+	DIDINDEX_VERSION = 1
+)
+
+// DIDIndexManager manages sharded DID position indexes with mmap
+type DIDIndexManager struct {
+	baseDir    string
+	indexDir   string
+	shardDir   string
+	configPath string
+
+	// LRU cache for hot shards
+	shardCache map[uint8]*mmapShard
+	cacheOrder []uint8 // For LRU
+	maxCache   int
+	cacheMu    sync.RWMutex
+
+	config  *DIDIndexConfig
+	logger  Logger
+	verbose bool
+}
+
+// mmapShard represents a memory-mapped shard file
+type mmapShard struct {
+	shardNum uint8
+	data     []byte
+	file     *os.File
+	lastUsed time.Time
+}
+
+// DIDIndexConfig stores index metadata
+type DIDIndexConfig struct {
+	Version    int       `json:"version"`
+	Format     string    `json:"format"`
+	ShardCount int       `json:"shard_count"`
+	TotalDIDs  int64     `json:"total_dids"`
+	UpdatedAt  time.Time `json:"updated_at"`
+	LastBundle int       `json:"last_bundle"`
+}
+
+// OpLocation represents exact location of an operation
+type OpLocation struct {
+	Bundle    uint16
+	Position  uint16
+	Nullified bool
+}
+
+// NewDIDIndexManager creates a new DID index manager
+func NewDIDIndexManager(baseDir string, logger Logger) *DIDIndexManager {
+	indexDir := filepath.Join(baseDir, DID_INDEX_DIR)
+	shardDir := filepath.Join(indexDir, DID_INDEX_SHARDS)
+	configPath := filepath.Join(indexDir, DID_INDEX_CONFIG)
+
+	// Ensure directories exist
+	os.MkdirAll(shardDir, 0755)
+
+	// Load or create config
+	config, _ := loadIndexConfig(configPath)
+	if config == nil {
+		config = &DIDIndexConfig{
+			Version:    DIDINDEX_VERSION,
+			Format:     "binary_v1",
+			ShardCount: DID_SHARD_COUNT,
+			UpdatedAt:  time.Now().UTC(),
+		}
+	}
+
+	return &DIDIndexManager{
+		baseDir:    baseDir,
+		indexDir:   indexDir,
+		shardDir:   shardDir,
+		configPath: configPath,
+		shardCache: make(map[uint8]*mmapShard),
+		cacheOrder: make([]uint8, 0),
+		maxCache:   20, // Keep 20 hot shards in memory (~120 MB)
+		config:     config,
+		logger:     logger,
+	}
+}
+
+// Close unmaps all shards and cleans up
+func (dim *DIDIndexManager) Close() error {
+	dim.cacheMu.Lock()
+	defer dim.cacheMu.Unlock()
+
+	for _, shard := range dim.shardCache {
+		dim.unmapShard(shard)
+	}
+
+	dim.shardCache = make(map[uint8]*mmapShard)
+	dim.cacheOrder = make([]uint8, 0)
+
+	return nil
+}
+
+func (dim *DIDIndexManager) SetVerbose(verbose bool) {
+	dim.verbose = verbose
+}
+
+// GetDIDLocations returns all bundle+position locations for a DID
+func (dim *DIDIndexManager) GetDIDLocations(did string) ([]OpLocation, error) {
+	// Validate and extract identifier
+	identifier, err := extractDIDIdentifier(did)
+	if err != nil {
+		return nil, err
+	}
+
+	// Calculate shard number
+	shardNum := dim.calculateShard(identifier)
+	if dim.verbose {
+		dim.logger.Printf("DEBUG: DID %s -> identifier '%s' -> shard %02x", did, identifier, shardNum)
+	}
+
+	// Load shard
+	shard, err := dim.loadShard(shardNum)
+	if err != nil {
+		if dim.verbose {
+			dim.logger.Printf("DEBUG: Failed to load shard: %v", err)
+		}
+		return nil, fmt.Errorf("failed to load shard %02x: %w", shardNum, err)
+	}
+
+	if shard.data == nil {
+		if dim.verbose {
+			dim.logger.Printf("DEBUG: Shard %02x has no data (empty shard)", shardNum)
+		}
+		return nil, nil
+	}
+
+	if dim.verbose {
+		dim.logger.Printf("DEBUG: Shard %02x loaded, size: %d bytes", shardNum, len(shard.data))
+	}
+
+	// Binary search
+	locations := dim.searchShard(shard, identifier)
+	if dim.verbose {
+		dim.logger.Printf("DEBUG: Binary search found %d locations", len(locations))
+		if len(locations) > 0 {
+			dim.logger.Printf("DEBUG: Locations: %v", locations)
+		}
+	}
+
+	return locations, nil
+}
+
+// calculateShard determines which shard a DID belongs to
+func (dim *DIDIndexManager) calculateShard(identifier string) uint8 {
+	h := fnv.New32a()
+	h.Write([]byte(identifier))
+	hash := h.Sum32()
+	return uint8(hash % DID_SHARD_COUNT)
+}
+
+// loadShard loads a shard from cache or disk (with mmap)
+func (dim *DIDIndexManager) loadShard(shardNum uint8) (*mmapShard, error) {
+	dim.cacheMu.Lock()
+	defer dim.cacheMu.Unlock()
+
+	// Check cache
+	if shard, exists := dim.shardCache[shardNum]; exists {
+		shard.lastUsed = time.Now()
+		dim.updateLRU(shardNum)
+		return shard, nil
+	}
+
+	// Load from disk
+	shardPath := filepath.Join(dim.shardDir, fmt.Sprintf("%02x.idx", shardNum))
+
+	// Check if file exists
+	if _, err := os.Stat(shardPath); os.IsNotExist(err) {
+		// Shard doesn't exist yet (no DIDs in this shard)
+		return &mmapShard{
+			shardNum: shardNum,
+			data:     nil,
+			lastUsed: time.Now(),
+		}, nil
+	}
+
+	// Open file
+	file, err := os.Open(shardPath)
+	if err != nil {
+		return nil, err
+	}
+
+	// Get file size
+	info, err := file.Stat()
+	if err != nil {
+		file.Close()
+		return nil, err
+	}
+
+	if info.Size() == 0 {
+		file.Close()
+		return &mmapShard{
+			shardNum: shardNum,
+			data:     nil,
+			lastUsed: time.Now(),
+		}, nil
+	}
+
+	// Memory-map the file
+	data, err := syscall.Mmap(int(file.Fd()), 0, int(info.Size()),
+		syscall.PROT_READ, syscall.MAP_SHARED)
+	if err != nil {
+		file.Close()
+		return nil, fmt.Errorf("mmap failed: %w", err)
+	}
+
+	shard := &mmapShard{
+		shardNum: shardNum,
+		data:     data,
+		file:     file,
+		lastUsed: time.Now(),
+	}
+
+	// Add to cache
+	dim.shardCache[shardNum] = shard
+	dim.cacheOrder = append(dim.cacheOrder, shardNum)
+
+	// Evict if cache is full
+	if len(dim.shardCache) > dim.maxCache {
+		dim.evictLRU()
+	}
+
+	return shard, nil
+}
+
+// searchShard performs binary search in a memory-mapped shard
+func (dim *DIDIndexManager) searchShard(shard *mmapShard, identifier string) []OpLocation {
+	if shard.data == nil || len(shard.data) < 32 {
+		return nil
+	}
+
+	data := shard.data
+
+	// Read header
+	if string(data[0:4]) != DIDINDEX_MAGIC {
+		dim.logger.Printf("Warning: invalid shard magic")
+		return nil
+	}
+
+	entryCount := binary.LittleEndian.Uint32(data[9:13])
+	if entryCount == 0 {
+		return nil
+	}
+
+	if dim.verbose {
+		dim.logger.Printf("DEBUG: Searching %d entries for '%s'", entryCount, identifier)
+	}
+
+	// Binary search in entries
+	left, right := 0, int(entryCount)
+
+	// Track for debugging
+	attempts := 0
+
+	for left < right {
+		attempts++
+		mid := (left + right) / 2
+
+		// Calculate offset for this entry
+		entryOffset := dim.getEntryOffset(data, 32, mid)
+		if entryOffset < 0 {
+			if dim.verbose {
+				dim.logger.Printf("DEBUG: Invalid entry offset at mid=%d", mid)
+			}
+			return nil
+		}
+
+		// Read identifier at this position
+		if entryOffset+DID_IDENTIFIER_LEN > len(data) {
+			if dim.verbose {
+				dim.logger.Printf("DEBUG: Entry offset out of bounds: %d + %d > %d",
+					entryOffset, DID_IDENTIFIER_LEN, len(data))
+			}
+			return nil
+		}
+
+		entryID := string(data[entryOffset : entryOffset+DID_IDENTIFIER_LEN])
+
+		if dim.verbose && attempts <= 5 {
+			dim.logger.Printf("DEBUG: Attempt %d: mid=%d, comparing '%s' vs '%s'",
+				attempts, mid, identifier, entryID)
+		}
+
+		// Compare
+		cmp := 0
+		if identifier < entryID {
+			cmp = -1
+		} else if identifier > entryID {
+			cmp = 1
+		}
+
+		if cmp == 0 {
+			// Found!
+			if dim.verbose {
+				dim.logger.Printf("DEBUG: FOUND at mid=%d after %d attempts", mid, attempts)
+			}
+			return dim.readLocations(data, entryOffset)
+		} else if cmp < 0 {
+			right = mid
+		} else {
+			left = mid + 1
+		}
+	}
+
+	if dim.verbose {
+		dim.logger.Printf("DEBUG: NOT FOUND after %d attempts (left=%d, right=%d)",
+			attempts, left, right)
+	}
+
+	return nil // Not found
+}
+
+// getEntryOffset calculates byte offset for nth entry
+func (dim *DIDIndexManager) getEntryOffset(data []byte, baseOffset int, entryIndex int) int {
+	offset := baseOffset
+
+	// Skip to the nth entry
+	for i := 0; i < entryIndex; i++ {
+		if offset+DID_IDENTIFIER_LEN+2 > len(data) {
+			return -1
+		}
+
+		// Skip identifier (24 bytes)
+		offset += DID_IDENTIFIER_LEN
+
+		// Read location count
+		count := binary.LittleEndian.Uint16(data[offset : offset+2])
+		offset += 2
+
+		// Skip locations (5 bytes each)
+		offset += int(count) * 5
+	}
+
+	return offset
+}
+
+// readLocations reads location data at given offset
+func (dim *DIDIndexManager) readLocations(data []byte, offset int) []OpLocation {
+	// Skip identifier
+	offset += DID_IDENTIFIER_LEN
+
+	// Read count
+	if offset+2 > len(data) {
+		return nil
+	}
+	count := binary.LittleEndian.Uint16(data[offset : offset+2])
+	offset += 2
+
+	// Read locations
+	locations := make([]OpLocation, count)
+	for i := 0; i < int(count); i++ {
+		if offset+5 > len(data) {
+			return locations[:i]
+		}
+
+		bundle := binary.LittleEndian.Uint16(data[offset : offset+2])
+		position := binary.LittleEndian.Uint16(data[offset+2 : offset+4])
+		nullified := data[offset+4] != 0
+
+		locations[i] = OpLocation{
+			Bundle:    bundle,
+			Position:  position,
+			Nullified: nullified,
+		}
+
+		offset += 5
+	}
+
+	return locations
+}
+
+// updateLRU updates LRU order
+func (dim *DIDIndexManager) updateLRU(shardNum uint8) {
+	// Remove from current position
+	for i, s := range dim.cacheOrder {
+		if s == shardNum {
+			dim.cacheOrder = append(dim.cacheOrder[:i], dim.cacheOrder[i+1:]...)
+			break
+		}
+	}
+
+	// Add to end (most recent)
+	dim.cacheOrder = append(dim.cacheOrder, shardNum)
+}
+
+// evictLRU removes least recently used shard
+func (dim *DIDIndexManager) evictLRU() {
+	if len(dim.cacheOrder) == 0 {
+		return
+	}
+
+	// Remove oldest
+	victimNum := dim.cacheOrder[0]
+	dim.cacheOrder = dim.cacheOrder[1:]
+
+	if victim, exists := dim.shardCache[victimNum]; exists {
+		dim.unmapShard(victim)
+		delete(dim.shardCache, victimNum)
+	}
+}
+
+// unmapShard unmaps and closes a shard
+func (dim *DIDIndexManager) unmapShard(shard *mmapShard) {
+	if shard.data != nil {
+		syscall.Munmap(shard.data)
+	}
+	if shard.file != nil {
+		shard.file.Close()
+	}
+}
+
+// GetStats returns index statistics
+func (dim *DIDIndexManager) GetStats() map[string]interface{} {
+	dim.cacheMu.RLock()
+	defer dim.cacheMu.RUnlock()
+
+	cachedShards := make([]int, 0)
+	for num := range dim.shardCache {
+		cachedShards = append(cachedShards, int(num))
+	}
+	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(dim.shardCache),
+		"cache_limit":   dim.maxCache,
+		"cache_order":   cachedShards,
+		"updated_at":    dim.config.UpdatedAt,
+	}
+}
+
+// Exists checks if index exists
+func (dim *DIDIndexManager) Exists() bool {
+	_, err := os.Stat(dim.configPath)
+	return err == nil
+}
+
+// extractDIDIdentifier extracts the 24-char identifier from full DID
+func extractDIDIdentifier(did string) (string, error) {
+	if err := plc.ValidateDIDFormat(did); err != nil {
+		return "", err
+	}
+
+	// Remove "did:plc:" prefix
+	identifier := did[8:] // Skip "did:plc:"
+
+	if len(identifier) != DID_IDENTIFIER_LEN {
+		return "", fmt.Errorf("invalid identifier length: %d", len(identifier))
+	}
+
+	return identifier, nil
+}
+
+// loadIndexConfig loads index configuration
+func loadIndexConfig(path string) (*DIDIndexConfig, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+
+	var config DIDIndexConfig
+	if err := json.Unmarshal(data, &config); err != nil {
+		return nil, err
+	}
+
+	return &config, nil
+}
+
+// saveIndexConfig saves index configuration
+func (dim *DIDIndexManager) saveIndexConfig() error {
+	dim.config.UpdatedAt = time.Now().UTC()
+
+	data, err := json.MarshalIndent(dim.config, "", "  ")
+	if err != nil {
+		return err
+	}
+
+	return os.WriteFile(dim.configPath, data, 0644)
+}
+
+// Add this debug command to verify shard integrity
+
+func (dim *DIDIndexManager) DebugShard(shardNum uint8) error {
+	shardPath := filepath.Join(dim.shardDir, fmt.Sprintf("%02x.idx", shardNum))
+	data, err := os.ReadFile(shardPath)
+	if err != nil {
+		return err
+	}
+
+	fmt.Printf("Shard %02x debug:\n", shardNum)
+	fmt.Printf("  File size: %d bytes\n", len(data))
+	fmt.Printf("  Magic: %s\n", string(data[0:4]))
+	fmt.Printf("  Version: %d\n", binary.LittleEndian.Uint32(data[4:8]))
+	fmt.Printf("  Shard num: %d\n", data[8])
+	fmt.Printf("  Entry count: %d\n", binary.LittleEndian.Uint32(data[9:13]))
+
+	// Show first few entries
+	entryCount := binary.LittleEndian.Uint32(data[9:13])
+	fmt.Printf("\n  First 5 entries:\n")
+
+	offset := 32
+	for i := 0; i < 5 && i < int(entryCount); i++ {
+		if offset+DID_IDENTIFIER_LEN+2 > len(data) {
+			break
+		}
+
+		identifier := string(data[offset : offset+DID_IDENTIFIER_LEN])
+		offset += DID_IDENTIFIER_LEN
+
+		locCount := binary.LittleEndian.Uint16(data[offset : offset+2])
+		offset += 2
+
+		fmt.Printf("    %d. '%s' (%d locations)\n", i+1, identifier, locCount)
+
+		offset += int(locCount) * 4 // Skip locations
+	}
+
+	return nil
+}

bundle/did_index_builder.go

···
+package bundle
+
+import (
+	"context"
+	"encoding/binary"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"sync"
+)
+
+const (
+	BUILD_BATCH_SIZE = 100 // Process 100 bundles at a time (not used in streaming approach)
+)
+
+// ShardBuilder accumulates DID positions for a shard
+type ShardBuilder struct {
+	entries map[string][]OpLocation
+	mu      sync.Mutex
+}
+
+// newShardBuilder creates a new shard builder
+func newShardBuilder() *ShardBuilder {
+	return &ShardBuilder{
+		entries: make(map[string][]OpLocation),
+	}
+}
+
+// add adds a location to the shard
+func (sb *ShardBuilder) add(identifier string, bundle uint16, position uint16, nullified bool) {
+	sb.mu.Lock()
+	defer sb.mu.Unlock()
+
+	sb.entries[identifier] = append(sb.entries[identifier], OpLocation{
+		Bundle:    bundle,
+		Position:  position,
+		Nullified: nullified,
+	})
+}
+
+// BuildIndexFromScratch builds index with controlled memory usage
+func (dim *DIDIndexManager) BuildIndexFromScratch(ctx context.Context, mgr *Manager, progressCallback func(current, total int)) error {
+	dim.logger.Printf("Building DID index from scratch (memory-efficient mode)...")
+
+	bundles := mgr.index.GetBundles()
+	if len(bundles) == 0 {
+		return fmt.Errorf("no bundles to index")
+	}
+
+	// Create temporary shard files
+	tempShards := make([]*os.File, DID_SHARD_COUNT)
+	for i := 0; i < DID_SHARD_COUNT; i++ {
+		tempPath := filepath.Join(dim.shardDir, fmt.Sprintf("%02x.tmp", i))
+		f, err := os.Create(tempPath)
+		if err != nil {
+			for j := 0; j < i; j++ {
+				tempShards[j].Close()
+				os.Remove(filepath.Join(dim.shardDir, fmt.Sprintf("%02x.tmp", j)))
+			}
+			return fmt.Errorf("failed to create temp shard: %w", err)
+		}
+		tempShards[i] = f
+	}
+
+	dim.logger.Printf("Pass 1/2: Scanning %d bundles...", len(bundles))
+
+	// Stream all operations to temp files
+	for i, meta := range bundles {
+		select {
+		case <-ctx.Done():
+			for _, f := range tempShards {
+				f.Close()
+				os.Remove(f.Name())
+			}
+			return ctx.Err()
+		default:
+		}
+
+		if progressCallback != nil {
+			progressCallback(i+1, len(bundles))
+		}
+
+		// Load bundle
+		bundle, err := mgr.LoadBundle(ctx, meta.BundleNumber)
+		if err != nil {
+			dim.logger.Printf("Warning: failed to load bundle %d: %v", meta.BundleNumber, err)
+			continue
+		}
+
+		// Process each operation
+		for pos, op := range bundle.Operations {
+			identifier, err := extractDIDIdentifier(op.DID)
+			if err != nil {
+				continue
+			}
+
+			shardNum := dim.calculateShard(identifier)
+
+			// Write entry: [24 bytes ID][2 bytes bundle][2 bytes pos][1 byte nullified]
+			entry := make([]byte, 29)
+			copy(entry[0:24], identifier)
+			binary.LittleEndian.PutUint16(entry[24:26], uint16(meta.BundleNumber))
+			binary.LittleEndian.PutUint16(entry[26:28], uint16(pos))
+
+			// Store nullified flag
+			if op.IsNullified() {
+				entry[28] = 1
+			} else {
+				entry[28] = 0
+			}
+
+			if _, err := tempShards[shardNum].Write(entry); err != nil {
+				dim.logger.Printf("Warning: failed to write to temp shard %02x: %v", shardNum, err)
+			}
+		}
+	}
+
+	// Close temp files
+	for _, f := range tempShards {
+		f.Close()
+	}
+
+	dim.logger.Printf("\n")
+	dim.logger.Printf("Pass 2/2: Consolidating %d shards...", DID_SHARD_COUNT)
+
+	// Consolidate shards
+	totalDIDs := int64(0)
+	for i := 0; i < DID_SHARD_COUNT; i++ {
+		// Log every 32 shards
+		if i%32 == 0 || i == DID_SHARD_COUNT-1 {
+			dim.logger.Printf("  Consolidating shards: %d/%d (%.1f%%)",
+				i+1, DID_SHARD_COUNT, float64(i+1)/float64(DID_SHARD_COUNT)*100)
+		}
+
+		count, err := dim.consolidateShard(uint8(i))
+		if err != nil {
+			return fmt.Errorf("failed to consolidate shard %02x: %w", i, err)
+		}
+		totalDIDs += count
+	}
+
+	dim.config.TotalDIDs = totalDIDs
+	dim.config.LastBundle = bundles[len(bundles)-1].BundleNumber
+
+	if err := dim.saveIndexConfig(); err != nil {
+		return fmt.Errorf("failed to save config: %w", err)
+	}
+
+	dim.logger.Printf("✓ Index built: %d DIDs indexed", totalDIDs)
+
+	return nil
+}
+
+// consolidateShard reads temp file, sorts, and writes final shard
+func (dim *DIDIndexManager) consolidateShard(shardNum uint8) (int64, error) {
+	tempPath := filepath.Join(dim.shardDir, fmt.Sprintf("%02x.tmp", shardNum))
+
+	// Read all entries from temp file
+	data, err := os.ReadFile(tempPath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return 0, nil // No entries for this shard
+		}
+		return 0, err
+	}
+
+	if len(data) == 0 {
+		os.Remove(tempPath)
+		return 0, nil
+	}
+
+	// Parse entries (29 bytes each)
+	entryCount := len(data) / 29
+	if len(data)%29 != 0 {
+		return 0, fmt.Errorf("corrupted temp shard: size not multiple of 29")
+	}
+
+	type tempEntry struct {
+		identifier string
+		bundle     uint16
+		position   uint16
+		nullified  bool
+	}
+
+	entries := make([]tempEntry, entryCount)
+	for i := 0; i < entryCount; i++ {
+		offset := i * 29
+		entries[i] = tempEntry{
+			identifier: string(data[offset : offset+24]),
+			bundle:     binary.LittleEndian.Uint16(data[offset+24 : offset+26]),
+			position:   binary.LittleEndian.Uint16(data[offset+26 : offset+28]),
+			nullified:  data[offset+28] != 0,
+		}
+	}
+
+	// Free the data slice
+	data = nil
+
+	// Sort by identifier
+	sort.Slice(entries, func(i, j int) bool {
+		return entries[i].identifier < entries[j].identifier
+	})
+
+	// Group by DID
+	builder := newShardBuilder()
+	for _, entry := range entries {
+		builder.add(entry.identifier, entry.bundle, entry.position, entry.nullified)
+	}
+
+	// Free entries
+	entries = nil
+
+	// Write final shard
+	if err := dim.writeShard(shardNum, builder); err != nil {
+		return 0, err
+	}
+
+	// Clean up temp file
+	os.Remove(tempPath)
+
+	return int64(len(builder.entries)), nil
+}
+
+// UpdateIndexForBundle adds operations from a new bundle (incremental)
+func (dim *DIDIndexManager) UpdateIndexForBundle(ctx context.Context, bundle *Bundle) error {
+	// Group operations by shard
+	shardOps := make(map[uint8]map[string][]OpLocation)
+
+	for pos, op := range bundle.Operations {
+		identifier, err := extractDIDIdentifier(op.DID)
+		if err != nil {
+			continue
+		}
+
+		shardNum := dim.calculateShard(identifier)
+
+		if shardOps[shardNum] == nil {
+			shardOps[shardNum] = make(map[string][]OpLocation)
+		}
+
+		shardOps[shardNum][identifier] = append(shardOps[shardNum][identifier], OpLocation{
+			Bundle:    uint16(bundle.BundleNumber),
+			Position:  uint16(pos),
+			Nullified: op.IsNullified(),
+		})
+	}
+
+	// Update affected shards (one at a time to save memory)
+	for shardNum, newOps := range shardOps {
+		if err := dim.updateShard(shardNum, newOps); err != nil {
+			return fmt.Errorf("failed to update shard %02x: %w", shardNum, err)
+		}
+	}
+
+	// Update config
+	dim.config.LastBundle = bundle.BundleNumber
+	return dim.saveIndexConfig()
+}
+
+// updateShard updates a single shard with new operations
+func (dim *DIDIndexManager) updateShard(shardNum uint8, newOps map[string][]OpLocation) error {
+	// Load existing shard data
+	shardPath := filepath.Join(dim.shardDir, fmt.Sprintf("%02x.idx", shardNum))
+
+	existingBuilder := newShardBuilder()
+
+	// Read existing shard if it exists
+	if data, err := os.ReadFile(shardPath); err == nil && len(data) > 32 {
+		if err := dim.parseShardData(data, existingBuilder); err != nil {
+			return err
+		}
+	}
+
+	// Merge new operations
+	for identifier, locations := range newOps {
+		existingBuilder.entries[identifier] = append(existingBuilder.entries[identifier], locations...)
+	}
+
+	// Write updated shard
+	return dim.writeShard(shardNum, existingBuilder)
+}
+
+// parseShardData parses binary shard data into builder
+func (dim *DIDIndexManager) parseShardData(data []byte, builder *ShardBuilder) error {
+	if len(data) < 32 {
+		return nil
+	}
+
+	entryCount := binary.LittleEndian.Uint32(data[9:13]) // Fixed offset
+	offset := 32
+
+	for i := 0; i < int(entryCount); i++ {
+		if offset+DID_IDENTIFIER_LEN+2 > len(data) {
+			break
+		}
+
+		// Read identifier
+		identifier := string(data[offset : offset+DID_IDENTIFIER_LEN])
+		offset += DID_IDENTIFIER_LEN
+
+		// Read location count
+		locCount := binary.LittleEndian.Uint16(data[offset : offset+2])
+		offset += 2
+
+		// Read locations
+		locations := make([]OpLocation, locCount)
+		for j := 0; j < int(locCount); j++ {
+			if offset+5 > len(data) {
+				break
+			}
+
+			locations[j] = OpLocation{
+				Bundle:    binary.LittleEndian.Uint16(data[offset : offset+2]),
+				Position:  binary.LittleEndian.Uint16(data[offset+2 : offset+4]),
+				Nullified: data[offset+4] != 0,
+			}
+			offset += 5
+		}
+
+		builder.entries[identifier] = locations
+	}
+
+	return nil
+}
+
+// writeShard writes a shard to disk in binary format
+func (dim *DIDIndexManager) writeShard(shardNum uint8, builder *ShardBuilder) error {
+	// Sort identifiers for binary search
+	identifiers := make([]string, 0, len(builder.entries))
+	for id := range builder.entries {
+		identifiers = append(identifiers, id)
+	}
+	sort.Strings(identifiers)
+
+	// Calculate size
+	totalSize := 32 // Header
+	for _, id := range identifiers {
+		locations := builder.entries[id]
+		totalSize += DID_IDENTIFIER_LEN + 2 + (len(locations) * 5)
+	}
+
+	// Allocate buffer
+	buf := make([]byte, totalSize)
+
+	// Write header
+	copy(buf[0:4], DIDINDEX_MAGIC)
+	binary.LittleEndian.PutUint32(buf[4:8], DIDINDEX_VERSION)
+	buf[8] = shardNum
+	binary.LittleEndian.PutUint32(buf[9:13], uint32(len(identifiers)))
+	// Reserved bytes 13-32 stay zero
+
+	// Write entries
+	offset := 32
+	for _, identifier := range identifiers {
+		locations := builder.entries[identifier]
+
+		// Write identifier (24 bytes)
+		copy(buf[offset:offset+DID_IDENTIFIER_LEN], identifier)
+		offset += DID_IDENTIFIER_LEN
+
+		// Write location count
+		binary.LittleEndian.PutUint16(buf[offset:offset+2], uint16(len(locations)))
+		offset += 2
+
+		// Write locations
+		for _, loc := range locations {
+			binary.LittleEndian.PutUint16(buf[offset:offset+2], loc.Bundle)
+			binary.LittleEndian.PutUint16(buf[offset+2:offset+4], loc.Position)
+
+			// Write nullified flag
+			if loc.Nullified {
+				buf[offset+4] = 1
+			} else {
+				buf[offset+4] = 0
+			}
+
+			offset += 5
+		}
+	}
+
+	// Write atomically (tmp → rename)
+	shardPath := filepath.Join(dim.shardDir, fmt.Sprintf("%02x.idx", shardNum))
+	tempPath := shardPath + ".tmp"
+
+	if err := os.WriteFile(tempPath, buf, 0644); err != nil {
+		return err
+	}
+
+	if err := os.Rename(tempPath, shardPath); err != nil {
+		os.Remove(tempPath)
+		return err
+	}
+
+	// Invalidate cache for this shard
+	dim.invalidateShard(shardNum)
+
+	return nil
+}
+
+// invalidateShard removes a shard from cache
+func (dim *DIDIndexManager) invalidateShard(shardNum uint8) {
+	dim.cacheMu.Lock()
+	defer dim.cacheMu.Unlock()
+
+	if cached, exists := dim.shardCache[shardNum]; exists {
+		dim.unmapShard(cached)
+		delete(dim.shardCache, shardNum)
+
+		// Remove from LRU order
+		for i, s := range dim.cacheOrder {
+			if s == shardNum {
+				dim.cacheOrder = append(dim.cacheOrder[:i], dim.cacheOrder[i+1:]...)
+				break
+			}
+		}
+	}
+}

bundle/did_resolver.go

···
+package bundle
+
+import (
+	"context"
+	"fmt"
+	"sort"
+
+	"tangled.org/atscan.net/plcbundle/plc"
+)
+
+// GetDIDOperationsBundledOnly retrieves operations from bundles only (no mempool)
+func (m *Manager) GetDIDOperationsBundledOnly(ctx context.Context, did string, verbose bool) ([]plc.PLCOperation, error) {
+	if err := plc.ValidateDIDFormat(did); err != nil {
+		return nil, err
+	}
+
+	// Set verbose mode on index
+	if m.didIndex != nil {
+		m.didIndex.SetVerbose(verbose)
+	}
+
+	// Use index if available
+	if m.didIndex != nil && m.didIndex.Exists() {
+		if verbose {
+			m.logger.Printf("DEBUG: Using DID index for lookup")
+		}
+		return m.getDIDOperationsIndexed(ctx, did, verbose)
+	}
+
+	// Fallback to full scan
+	if verbose {
+		m.logger.Printf("DEBUG: DID index not available, using full scan")
+	}
+	m.logger.Printf("Warning: DID index not available, falling back to full scan")
+	return m.getDIDOperationsScan(ctx, did)
+}
+
+// GetDIDOperationsFromMempool retrieves operations for a DID from mempool only
+func (m *Manager) GetDIDOperationsFromMempool(did string) ([]plc.PLCOperation, error) {
+	if err := plc.ValidateDIDFormat(did); err != nil {
+		return nil, err
+	}
+
+	if m.mempool == nil {
+		return []plc.PLCOperation{}, nil
+	}
+
+	allMempoolOps, err := m.GetMempoolOperations()
+	if err != nil {
+		return nil, err
+	}
+
+	var matchingOps []plc.PLCOperation
+	for _, op := range allMempoolOps {
+		if op.DID == did {
+			matchingOps = append(matchingOps, op)
+		}
+	}
+
+	return matchingOps, nil
+}
+
+// GetDIDOperations retrieves all operations for a DID (bundles + mempool combined)
+func (m *Manager) GetDIDOperations(ctx context.Context, did string, verbose bool) ([]plc.PLCOperation, error) {
+	if err := plc.ValidateDIDFormat(did); err != nil {
+		return nil, err
+	}
+
+	// Get bundled operations
+	bundledOps, err := m.GetDIDOperationsBundledOnly(ctx, did, verbose)
+	if err != nil {
+		return nil, err
+	}
+
+	// Get mempool operations
+	mempoolOps, err := m.GetDIDOperationsFromMempool(did)
+	if err != nil {
+		return nil, err
+	}
+
+	if len(mempoolOps) > 0 && verbose {
+		m.logger.Printf("DEBUG: Found %d operations in mempool", len(mempoolOps))
+	}
+
+	// Combine and sort
+	allOps := append(bundledOps, mempoolOps...)
+
+	sort.Slice(allOps, func(i, j int) bool {
+		return allOps[i].CreatedAt.Before(allOps[j].CreatedAt)
+	})
+
+	return allOps, nil
+}
+
+// getDIDOperationsIndexed uses index for fast lookup (PRIVATE - bundles only)
+func (m *Manager) getDIDOperationsIndexed(ctx context.Context, did string, verbose bool) ([]plc.PLCOperation, error) {
+	locations, err := m.didIndex.GetDIDLocations(did)
+	if err != nil {
+		return nil, err
+	}
+
+	if len(locations) == 0 {
+		return []plc.PLCOperation{}, nil
+	}
+
+	// Filter nullified at index level (save loading those bundles!)
+	var validLocations []OpLocation
+	for _, loc := range locations {
+		if !loc.Nullified {
+			validLocations = append(validLocations, loc)
+		}
+	}
+
+	if verbose {
+		m.logger.Printf("DEBUG: Filtered %d valid locations (from %d total)",
+			len(validLocations), len(locations))
+	}
+
+	// Group by bundle
+	bundleMap := make(map[uint16][]uint16)
+	for _, loc := range validLocations {
+		bundleMap[loc.Bundle] = append(bundleMap[loc.Bundle], loc.Position)
+	}
+
+	if verbose {
+		m.logger.Printf("DEBUG: Loading %d bundles", len(bundleMap))
+	}
+
+	// Load operations
+	var allOps []plc.PLCOperation
+	for bundleNum, positions := range bundleMap {
+		bundle, err := m.LoadBundle(ctx, int(bundleNum))
+		if err != nil {
+			m.logger.Printf("Warning: failed to load bundle %d: %v", bundleNum, err)
+			continue
+		}
+
+		for _, pos := range positions {
+			if int(pos) < len(bundle.Operations) {
+				allOps = append(allOps, bundle.Operations[pos])
+			}
+		}
+	}
+
+	if verbose {
+		m.logger.Printf("DEBUG: Loaded %d total operations", len(allOps))
+	}
+
+	sort.Slice(allOps, func(i, j int) bool {
+		return allOps[i].CreatedAt.Before(allOps[j].CreatedAt)
+	})
+
+	return allOps, nil
+}
+
+// getDIDOperationsScan falls back to full scan (slow) (PRIVATE - bundles only)
+func (m *Manager) getDIDOperationsScan(ctx context.Context, did string) ([]plc.PLCOperation, error) {
+	var allOps []plc.PLCOperation
+	bundles := m.index.GetBundles()
+
+	for _, meta := range bundles {
+		select {
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		default:
+		}
+
+		bundle, err := m.LoadBundle(ctx, meta.BundleNumber)
+		if err != nil {
+			m.logger.Printf("Warning: failed to load bundle %d: %v", meta.BundleNumber, err)
+			continue
+		}
+
+		for _, op := range bundle.Operations {
+			if op.DID == did {
+				allOps = append(allOps, op)
+			}
+		}
+	}
+
+	sort.Slice(allOps, func(i, j int) bool {
+		return allOps[i].CreatedAt.Before(allOps[j].CreatedAt)
+	})
+
+	return allOps, nil
+}
+
+// GetLatestDIDOperation returns only the most recent non-nullified operation
+func (m *Manager) GetLatestDIDOperation(ctx context.Context, did string) (*plc.PLCOperation, error) {
+	if err := plc.ValidateDIDFormat(did); err != nil {
+		return nil, err
+	}
+
+	// Check mempool first (most recent operations)
+	mempoolOps, err := m.GetDIDOperationsFromMempool(did)
+	if err == nil && len(mempoolOps) > 0 {
+		// Find latest non-nullified in mempool
+		for i := len(mempoolOps) - 1; i >= 0; i-- {
+			if !mempoolOps[i].IsNullified() {
+				// Found in mempool - but still verify nothing newer in bundles
+				// (shouldn't happen with chronological ordering, but be safe)
+				bundledLatest, _ := m.getLatestDIDOperationIndexed(ctx, did)
+				if bundledLatest == nil || mempoolOps[i].CreatedAt.After(bundledLatest.CreatedAt) {
+					return &mempoolOps[i], nil
+				}
+				return bundledLatest, nil
+			}
+		}
+	}
+
+	// Not in mempool - use index/scan
+	if m.didIndex != nil && m.didIndex.Exists() {
+		return m.getLatestDIDOperationIndexed(ctx, did)
+	}
+
+	// Fallback to full lookup
+	ops, err := m.GetDIDOperationsBundledOnly(ctx, did, false)
+	if err != nil {
+		return nil, err
+	}
+
+	// Find latest non-nullified
+	for i := len(ops) - 1; i >= 0; i-- {
+		if !ops[i].IsNullified() {
+			return &ops[i], nil
+		}
+	}
+
+	return nil, fmt.Errorf("no valid operations found")
+}
+
+// getLatestDIDOperationIndexed uses index to find only the latest operation (PRIVATE)
+func (m *Manager) getLatestDIDOperationIndexed(ctx context.Context, did string) (*plc.PLCOperation, error) {
+	// Get all locations from index
+	locations, err := m.didIndex.GetDIDLocations(did)
+	if err != nil {
+		return nil, err
+	}
+
+	if len(locations) == 0 {
+		return nil, fmt.Errorf("DID not found")
+	}
+
+	// Filter non-nullified and find the latest
+	var latestLoc *OpLocation
+
+	for i := range locations {
+		if locations[i].Nullified {
+			continue
+		}
+
+		// Check if this is later than current latest
+		if latestLoc == nil {
+			latestLoc = &locations[i]
+		} else {
+			// Compare by bundle, then position
+			if locations[i].Bundle > latestLoc.Bundle ||
+				(locations[i].Bundle == latestLoc.Bundle && locations[i].Position > latestLoc.Position) {
+				latestLoc = &locations[i]
+			}
+		}
+	}
+
+	if latestLoc == nil {
+		return nil, fmt.Errorf("no valid operations found (all nullified)")
+	}
+
+	// ✨ Load ONLY that ONE operation (not the whole bundle!)
+	op, err := m.LoadOperation(ctx, int(latestLoc.Bundle), int(latestLoc.Position))
+	if err != nil {
+		return nil, fmt.Errorf("failed to load operation at bundle %d position %d: %w",
+			latestLoc.Bundle, latestLoc.Position, err)
+	}
+
+	return op, nil
+}
+
+// BuildDIDIndex builds the complete DID index
+func (m *Manager) BuildDIDIndex(ctx context.Context, progressCallback func(current, total int)) error {
+	if m.didIndex == nil {
+		m.didIndex = NewDIDIndexManager(m.config.BundleDir, m.logger)
+	}
+
+	return m.didIndex.BuildIndexFromScratch(ctx, m, progressCallback)
+}
+
+// UpdateDIDIndexForBundle updates index when a new bundle is added
+func (m *Manager) UpdateDIDIndexForBundle(ctx context.Context, bundle *Bundle) error {
+	if m.didIndex == nil {
+		return nil // Index not initialized
+	}
+
+	return m.didIndex.UpdateIndexForBundle(ctx, bundle)
+}
+
+// GetDIDIndexStats returns DID index statistics
+func (m *Manager) GetDIDIndexStats() map[string]interface{} {
+	if m.didIndex == nil {
+		return map[string]interface{}{
+			"enabled": false,
+		}
+	}
+
+	stats := m.didIndex.GetStats()
+	stats["enabled"] = true
+	stats["exists"] = m.didIndex.Exists()
+
+	return stats
+}

bundle/manager.go

···
 	plcClient  *plc.Client
 	logger     Logger
 	mempool    *Mempool
+	didIndex   *DIDIndexManager
 }
 
 // NewManager creates a new bundle manager
···
 		return nil, fmt.Errorf("failed to initialize mempool: %w", err)
 	}
 
+	// Initialize DID index manager
+	didIndex := NewDIDIndexManager(config.BundleDir, config.Logger)
+
 	return &Manager{
 		config:     config,
 		operations: ops,
···
 		plcClient:  plcClient,
 		logger:     config.Logger,
 		mempool:    mempool,
+		didIndex:   didIndex,
 	}, nil
 }
 
···
 		if err := m.mempool.Save(); err != nil {
 			m.logger.Printf("Warning: failed to save mempool: %v", err)
 		}
+	}
+	if m.didIndex != nil { // ← ADD THIS
+		m.didIndex.Close()
 	}
 }
 
···
 	}
 
 	m.mempool = newMempool
+
+	// Update DID index if enabled
+	if m.didIndex != nil && m.didIndex.Exists() {
+		if err := m.UpdateDIDIndexForBundle(ctx, bundle); err != nil {
+			m.logger.Printf("Warning: failed to update DID index: %v", err)
+		}
+	}
 
 	return nil
 }
···
 
 	return cursor
 }
+
+// GetDIDIndex returns the DID index manager
+func (m *Manager) GetDIDIndex() *DIDIndexManager {
+	return m.didIndex
+}
+
+// LoadOperation loads a single operation from a bundle efficiently
+// This is much faster than LoadBundle() when you only need one operation
+func (m *Manager) LoadOperation(ctx context.Context, bundleNumber int, position int) (*plc.PLCOperation, error) {
+	// Validate bundle exists in index
+	meta, err := m.index.GetBundle(bundleNumber)
+	if err != nil {
+		return nil, fmt.Errorf("bundle not in index: %w", err)
+	}
+
+	// Validate position
+	if position < 0 || position >= BUNDLE_SIZE {
+		return nil, fmt.Errorf("invalid position: %d (must be 0-%d)", position, BUNDLE_SIZE-1)
+	}
+
+	// Build file path
+	path := filepath.Join(m.config.BundleDir, fmt.Sprintf("%06d.jsonl.zst", bundleNumber))
+	if !m.operations.FileExists(path) {
+		return nil, fmt.Errorf("bundle file not found: %s", path)
+	}
+
+	// Verify hash if enabled (same as LoadBundle)
+	if m.config.VerifyOnLoad {
+		valid, actualHash, err := m.operations.VerifyHash(path, meta.CompressedHash)
+		if err != nil {
+			return nil, fmt.Errorf("failed to verify hash: %w", err)
+		}
+		if !valid {
+			return nil, fmt.Errorf("hash mismatch: expected %s, got %s", meta.CompressedHash, actualHash)
+		}
+	}
+
+	// Load just the one operation (efficient!)
+	return m.operations.LoadOperationAtPosition(path, position)
+}

bundle/operations.go

···
 	return contentHash, compressedHash, contentSize, compressedSize, nil
 }
 
+// LoadOperationAtPosition loads a single operation from a bundle without loading the entire bundle
+// This is much more efficient for single-operation lookups
+func (op *Operations) LoadOperationAtPosition(path string, position int) (*plc.PLCOperation, error) {
+	if position < 0 {
+		return nil, fmt.Errorf("invalid position: %d", position)
+	}
+
+	// Open compressed file
+	file, err := os.Open(path)
+	if err != nil {
+		return nil, fmt.Errorf("failed to open file: %w", err)
+	}
+	defer file.Close()
+
+	// Create zstd decompression reader (streaming, no full decompress)
+	reader := gozstd.NewReader(file)
+	defer reader.Close()
+
+	// Use scanner to skip to target line
+	scanner := bufio.NewScanner(reader)
+	buf := make([]byte, 0, 64*1024)
+	scanner.Buffer(buf, 1024*1024)
+
+	lineNum := 0
+	for scanner.Scan() {
+		if lineNum == position {
+			// Found target line!
+			line := scanner.Bytes()
+
+			var operation plc.PLCOperation
+			if err := json.UnmarshalNoEscape(line, &operation); err != nil {
+				return nil, fmt.Errorf("failed to parse operation at position %d: %w", position, err)
+			}
+
+			// Store raw JSON
+			operation.RawJSON = make([]byte, len(line))
+			copy(operation.RawJSON, line)
+
+			return &operation, nil
+		}
+		lineNum++
+	}
+
+	if err := scanner.Err(); err != nil {
+		return nil, fmt.Errorf("scanner error: %w", err)
+	}
+
+	return nil, fmt.Errorf("position %d not found (bundle has %d operations)", position, lineNum)
+}
+
 // ========================================
 // STREAMING
 // ========================================

cmd/plcbundle/did_index.go

···
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"os"
+	"time"
+
+	"github.com/goccy/go-json"
+	"tangled.org/atscan.net/plcbundle/bundle"
+	"tangled.org/atscan.net/plcbundle/plc"
+)
+
+func cmdDIDIndex() {
+	if len(os.Args) < 3 {
+		printDIDIndexUsage()
+		os.Exit(1)
+	}
+
+	subcommand := os.Args[2]
+
+	switch subcommand {
+	case "build":
+		cmdDIDIndexBuild()
+	case "stats":
+		cmdDIDIndexStats()
+	case "lookup":
+		cmdDIDIndexLookup()
+	case "resolve":
+		cmdDIDIndexResolve()
+	default:
+		fmt.Fprintf(os.Stderr, "Unknown index subcommand: %s\n", subcommand)
+		printDIDIndexUsage()
+		os.Exit(1)
+	}
+}
+
+func printDIDIndexUsage() {
+	fmt.Printf(`Usage: plcbundle index <command> [options]
+
+Commands:
+  build     Build DID index from bundles
+  stats     Show index statistics
+  lookup    Lookup a specific DID
+  resolve   Resolve DID to current document
+
+Examples:
+  plcbundle index build
+  plcbundle index stats
+  plcbundle index lookup -v did:plc:524tuhdhh3m7li5gycdn6boe
+  plcbundle index resolve did:plc:524tuhdhh3m7li5gycdn6boe
+`)
+}
+
+func cmdDIDIndexBuild() {
+	fs := flag.NewFlagSet("index build", flag.ExitOnError)
+	force := fs.Bool("force", false, "rebuild even if index exists")
+	fs.Parse(os.Args[3:])
+
+	mgr, dir, err := getManager("")
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
+	defer mgr.Close()
+
+	// Check if index exists
+	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
+	}
+
+	fmt.Printf("Building DID index in: %s\n", dir)
+
+	index := mgr.GetIndex()
+	bundleCount := index.Count()
+
+	if bundleCount == 0 {
+		fmt.Printf("No bundles to index\n")
+		return
+	}
+
+	fmt.Printf("Indexing %d bundles...\n\n", bundleCount)
+
+	progress := NewProgressBar(bundleCount)
+
+	start := time.Now()
+	ctx := context.Background()
+
+	err = mgr.BuildDIDIndex(ctx, func(current, total int) {
+		progress.Set(current)
+	})
+
+	progress.Finish()
+
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "\nError building index: %v\n", err)
+		os.Exit(1)
+	}
+
+	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)
+}
+
+func cmdDIDIndexStats() {
+	mgr, dir, err := getManager("")
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
+	defer mgr.Close()
+
+	stats := mgr.GetDIDIndexStats()
+
+	if !stats["exists"].(bool) {
+		fmt.Printf("DID index does not exist\n")
+		fmt.Printf("Run: plcbundle index build\n")
+		return
+	}
+
+	fmt.Printf("\nDID Index Statistics\n")
+	fmt.Printf("════════════════════\n\n")
+	fmt.Printf("  Location:      %s/.plcbundle/\n", dir)
+	fmt.Printf("  Total DIDs:    %s\n", formatNumber(int(stats["total_dids"].(int64))))
+	fmt.Printf("  Shard count:   %d\n", stats["shard_count"])
+	fmt.Printf("  Last bundle:   %06d\n", stats["last_bundle"])
+	fmt.Printf("  Updated:       %s\n", stats["updated_at"].(time.Time).Format("2006-01-02 15:04:05"))
+	fmt.Printf("\n")
+	fmt.Printf("  Cached shards: %d / %d\n", stats["cached_shards"], stats["cache_limit"])
+
+	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")
+	}
+
+	fmt.Printf("\n")
+}
+
+func cmdDIDIndexLookup() {
+	if len(os.Args) < 4 {
+		fmt.Fprintf(os.Stderr, "Usage: plcbundle index lookup <did> [-v]\n")
+		os.Exit(1)
+	}
+
+	fs := flag.NewFlagSet("index lookup", flag.ExitOnError)
+	verbose := fs.Bool("v", false, "verbose debug output")
+	fs.Parse(os.Args[3:])
+
+	if fs.NArg() < 1 {
+		fmt.Fprintf(os.Stderr, "Usage: plcbundle index lookup <did> [-v]\n")
+		os.Exit(1)
+	}
+
+	did := fs.Arg(0)
+
+	mgr, _, err := getManager("")
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
+	defer mgr.Close()
+
+	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")
+	}
+
+	fmt.Printf("Looking up: %s\n", did)
+	if *verbose {
+		fmt.Printf("Verbose mode: enabled\n")
+	}
+	fmt.Printf("\n")
+
+	start := time.Now()
+	ctx := context.Background()
+
+	// Get bundled operations only
+	bundledOps, err := mgr.GetDIDOperationsBundledOnly(ctx, did, *verbose)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
+
+	// Get mempool operations separately
+	mempoolOps, err := mgr.GetDIDOperationsFromMempool(did)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error checking mempool: %v\n", err)
+		os.Exit(1)
+	}
+
+	elapsed := time.Since(start)
+
+	if len(bundledOps) == 0 && len(mempoolOps) == 0 {
+		fmt.Printf("DID not found (searched in %s)\n", elapsed)
+		return
+	}
+
+	// Count nullified operations
+	nullifiedCount := 0
+	for _, op := range bundledOps {
+		if op.IsNullified() {
+			nullifiedCount++
+		}
+	}
+
+	// Display summary
+	totalOps := len(bundledOps) + len(mempoolOps)
+	fmt.Printf("Found %d total operations in %s\n", totalOps, elapsed)
+	if len(bundledOps) > 0 {
+		fmt.Printf("  Bundled: %d (%d active, %d nullified)\n", len(bundledOps), len(bundledOps)-nullifiedCount, nullifiedCount)
+	}
+	if len(mempoolOps) > 0 {
+		fmt.Printf("  Mempool: %d (not yet bundled)\n", len(mempoolOps))
+	}
+	fmt.Printf("\n")
+
+	// Show bundled operations
+	if len(bundledOps) > 0 {
+		fmt.Printf("Bundled operations:\n")
+		for i, op := range bundledOps {
+			status := "✓"
+			if op.IsNullified() {
+				status = "✗"
+			}
+
+			fmt.Printf("  %s %d. CID: %s\n", status, i+1, op.CID)
+			fmt.Printf("       Time: %s\n", op.CreatedAt.Format("2006-01-02 15:04:05"))
+
+			if op.IsNullified() {
+				if nullCID := op.GetNullifyingCID(); nullCID != "" {
+					fmt.Printf("       Nullified by: %s\n", nullCID)
+				} else {
+					fmt.Printf("       Nullified: true\n")
+				}
+			}
+		}
+		fmt.Printf("\n")
+	}
+
+	// Show mempool operations
+	if len(mempoolOps) > 0 {
+		fmt.Printf("Mempool operations (not yet bundled):\n")
+		for i, op := range mempoolOps {
+			status := "✓"
+			if op.IsNullified() {
+				status = "✗"
+			}
+
+			fmt.Printf("  %s %d. CID: %s\n", status, i+1, op.CID)
+			fmt.Printf("       Time: %s\n", op.CreatedAt.Format("2006-01-02 15:04:05"))
+		}
+	}
+}
+
+func cmdDIDIndexResolve() {
+	if len(os.Args) < 4 {
+		fmt.Fprintf(os.Stderr, "Usage: plcbundle index resolve <did> [-v]\n")
+		os.Exit(1)
+	}
+
+	fs := flag.NewFlagSet("index resolve", flag.ExitOnError)
+	//verbose := fs.Bool("v", false, "verbose debug output")
+	fs.Parse(os.Args[3:])
+
+	if fs.NArg() < 1 {
+		fmt.Fprintf(os.Stderr, "Usage: plcbundle index resolve <did> [-v]\n")
+		os.Exit(1)
+	}
+
+	did := fs.Arg(0)
+
+	mgr, _, err := getManager("")
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
+	defer mgr.Close()
+
+	ctx := context.Background()
+	fmt.Fprintf(os.Stderr, "Resolving: %s\n", did)
+
+	start := time.Now()
+
+	// ✨ STEP 0: Check mempool first (most recent data)
+	mempoolStart := time.Now()
+	var latestOp *plc.PLCOperation
+	foundInMempool := false
+
+	if mgr.GetMempool() != nil {
+		mempoolOps, err := mgr.GetMempoolOperations()
+		if err == nil && len(mempoolOps) > 0 {
+			// Search backward for this DID
+			for i := len(mempoolOps) - 1; i >= 0; i-- {
+				if mempoolOps[i].DID == did && !mempoolOps[i].IsNullified() {
+					latestOp = &mempoolOps[i]
+					foundInMempool = true
+					break
+				}
+			}
+		}
+	}
+	mempoolTime := time.Since(mempoolStart)
+
+	if foundInMempool {
+		fmt.Fprintf(os.Stderr, "Mempool check: %s (✓ found in mempool)\n", mempoolTime)
+
+		// Build document from mempool operation
+		ops := []plc.PLCOperation{*latestOp}
+		doc, err := plc.ResolveDIDDocument(did, ops)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Build document failed: %v\n", err)
+			os.Exit(1)
+		}
+
+		totalTime := time.Since(start)
+		fmt.Fprintf(os.Stderr, "Total: %s (resolved from mempool)\n\n", totalTime)
+
+		// Output to stdout
+		data, _ := json.MarshalIndent(doc, "", "  ")
+		fmt.Println(string(data))
+		return
+	}
+
+	fmt.Fprintf(os.Stderr, "Mempool check: %s (not found)\n", mempoolTime)
+
+	// Not in mempool - check index
+	stats := mgr.GetDIDIndexStats()
+	if !stats["exists"].(bool) {
+		fmt.Fprintf(os.Stderr, "⚠️  DID index does not exist. Run: plcbundle index build\n\n")
+		os.Exit(1)
+	}
+
+	// STEP 1: Index lookup timing
+	indexStart := time.Now()
+	locations, err := mgr.GetDIDIndex().GetDIDLocations(did)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+		os.Exit(1)
+	}
+	indexTime := time.Since(indexStart)
+
+	if len(locations) == 0 {
+		fmt.Fprintf(os.Stderr, "DID not found in index or mempool\n")
+		os.Exit(1)
+	}
+
+	// Find latest non-nullified location
+	var latestLoc *bundle.OpLocation
+	for i := range locations {
+		if locations[i].Nullified {
+			continue
+		}
+		if latestLoc == nil ||
+			locations[i].Bundle > latestLoc.Bundle ||
+			(locations[i].Bundle == latestLoc.Bundle && locations[i].Position > latestLoc.Position) {
+			latestLoc = &locations[i]
+		}
+	}
+
+	if latestLoc == nil {
+		fmt.Fprintf(os.Stderr, "No valid operations (all nullified)\n")
+		os.Exit(1)
+	}
+
+	fmt.Fprintf(os.Stderr, "Index lookup: %s (shard access)\n", indexTime)
+
+	// STEP 2: Bundle loading timing
+	bundleStart := time.Now()
+	bndl, err := mgr.LoadBundle(ctx, int(latestLoc.Bundle))
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error loading bundle: %v\n", err)
+		os.Exit(1)
+	}
+	bundleTime := time.Since(bundleStart)
+
+	if int(latestLoc.Position) >= len(bndl.Operations) {
+		fmt.Fprintf(os.Stderr, "Invalid position\n")
+		os.Exit(1)
+	}
+
+	op := bndl.Operations[latestLoc.Position]
+
+	fmt.Fprintf(os.Stderr, "Bundle load: %s (bundle %d, pos %d)\n",
+		bundleTime, latestLoc.Bundle, latestLoc.Position)
+
+	// STEP 3: Build DID document
+	ops := []plc.PLCOperation{op}
+	doc, err := plc.ResolveDIDDocument(did, ops)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Build document failed: %v\n", err)
+		os.Exit(1)
+	}
+
+	totalTime := time.Since(start)
+	fmt.Fprintf(os.Stderr, "Total: %s\n\n", totalTime)
+
+	// Output to stdout
+	data, _ := json.MarshalIndent(doc, "", "  ")
+	fmt.Println(string(data))
+}

cmd/plcbundle/main.go

···
 		cmdCompare()
 	case "detector":
 		cmdDetector()
+	case "index":
+		cmdDIDIndex()
 	case "version":
 		fmt.Printf("plcbundle version %s\n", version)
 		fmt.Printf("  commit: %s\n", gitCommit)
···
   mempool    Show mempool status and operations
   serve      Start HTTP server to serve bundle data
   compare    Compare local index with target index
-  detector
+  detector   Run spam detectors
+  index      Manage DID position index
   version    Show version
 
 Security Model:

cmd/plcbundle/server.go

···
 	}
 	fmt.Fprintf(w, "\n")
 
+	if didStats := mgr.GetDIDIndexStats(); didStats["exists"].(bool) {
+		fmt.Fprintf(w, "\nDID Index\n")
+		fmt.Fprintf(w, "━━━━━━━━━\n")
+		fmt.Fprintf(w, "  Status:        enabled\n")
+		fmt.Fprintf(w, "  Total DIDs:    %d\n", didStats["total_dids"])
+		fmt.Fprintf(w, "  Cached shards: %d / %d\n",
+			didStats["cached_shards"], didStats["cache_limit"])
+		fmt.Fprintf(w, "\n")
+	}
+
 	fmt.Fprintf(w, "Server Stats\n")
 	fmt.Fprintf(w, "━━━━━━━━━━━━\n")
 	fmt.Fprintf(w, "  Version:       %s\n", version)
···
 	fmt.Fprintf(w, "  GET  /jsonl/:number       Decompressed JSONL stream\n")
 	fmt.Fprintf(w, "  GET  /status              Server status\n")
 	fmt.Fprintf(w, "  GET  /mempool             Mempool operations (JSONL)\n")
+
+	fmt.Fprintf(w, "\nDID Resolution\n")
+	fmt.Fprintf(w, "━━━━━━━━━━━━━━\n")
+	fmt.Fprintf(w, "  GET  /:did                    DID Document (W3C format)\n")
+	fmt.Fprintf(w, "  GET  /:did/data               PLC State (raw format)\n")
+	fmt.Fprintf(w, "  GET  /:did/log/audit          Operation history\n")
+	fmt.Fprintf(w, "\n")
 
 	if wsEnabled {
 		fmt.Fprintf(w, "\nWebSocket Endpoints\n")
···
 
 	// Root - ASCII art + info
 	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != "/" {
-			http.NotFound(w, r)
+		path := r.URL.Path
+
+		// DID Resolution - delegate to specific handler
+		if strings.HasPrefix(path, "/did:plc:") {
+			handleDIDEndpoint(w, r, mgr)
+			return
+		}
+
+		if path == "/" {
+			handleRoot(w, r, mgr, syncMode, wsEnabled)
 			return
 		}
-		handleRoot(w, r, mgr, syncMode, wsEnabled)
+
+		http.NotFound(w, r)
 	})
 
 	// Index JSON (reload from disk each time for fresh data during rebuild)
···
 		time.Sleep(500 * time.Millisecond)
 	}
 }
+
+// handleDIDEndpoint routes DID-related requests
+func handleDIDEndpoint(w http.ResponseWriter, r *http.Request, mgr *bundle.Manager) {
+	path := r.URL.Path
+
+	// Parse DID and sub-path
+	// Examples:
+	//   /did:plc:abc... -> DID document
+	//   /did:plc:abc.../data -> PLC state
+	//   /did:plc:abc.../log/audit -> Audit log
+
+	parts := strings.SplitN(strings.TrimPrefix(path, "/"), "/", 2)
+	did := parts[0]
+
+	// Validate DID format
+	if err := plc.ValidateDIDFormat(did); err != nil {
+		http.Error(w, "Invalid DID format: "+err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	// Route based on sub-path
+	if len(parts) == 1 {
+		// /did:plc:xxx -> DID document
+		handleDIDDocument(w, r, mgr, did)
+	} else if parts[1] == "data" {
+		// /did:plc:xxx/data -> PLC state
+		handleDIDData(w, r, mgr, did)
+	} else if parts[1] == "log/audit" {
+		// /did:plc:xxx/log/audit -> Audit log
+		handleDIDAuditLog(w, r, mgr, did)
+	} else {
+		http.NotFound(w, r)
+	}
+}
+
+// handleDIDDocument resolves and returns DID document
+func handleDIDDocument(w http.ResponseWriter, r *http.Request, mgr *bundle.Manager, did string) {
+	ctx := r.Context()
+
+	// Bundle package: just get the operations
+	operations, err := mgr.GetDIDOperations(ctx, did, false)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	if len(operations) == 0 {
+		http.NotFound(w, r)
+		return
+	}
+
+	// PLC package: resolve to DID document
+	doc, err := plc.ResolveDIDDocument(did, operations)
+	if err != nil {
+		if strings.Contains(err.Error(), "deactivated") {
+			http.Error(w, "DID has been deactivated", http.StatusGone)
+		} else {
+			http.Error(w, fmt.Sprintf("Resolution failed: %v", err), http.StatusInternalServerError)
+		}
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/did+ld+json")
+	w.Header().Set("Access-Control-Allow-Origin", "*")
+
+	data, err := json.MarshalIndent(doc, "", "  ")
+	if err != nil {
+		http.Error(w, "Failed to encode document", http.StatusInternalServerError)
+		return
+	}
+
+	w.Write(data)
+}
+
+// handleDIDData returns PLC-specific state data
+func handleDIDData(w http.ResponseWriter, r *http.Request, mgr *bundle.Manager, did string) {
+	ctx := r.Context()
+
+	// Bundle package: get operations
+	operations, err := mgr.GetDIDOperations(ctx, did, false)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	if len(operations) == 0 {
+		http.NotFound(w, r)
+		return
+	}
+
+	// PLC package: build state
+	state, err := plc.BuildDIDState(did, operations)
+	if err != nil {
+		if strings.Contains(err.Error(), "deactivated") {
+			http.Error(w, "DID has been deactivated", http.StatusGone)
+		} else {
+			http.Error(w, err.Error(), http.StatusInternalServerError)
+		}
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("Access-Control-Allow-Origin", "*")
+
+	json.NewEncoder(w).Encode(state)
+}
+
+// handleDIDAuditLog returns the operation log for a DID
+func handleDIDAuditLog(w http.ResponseWriter, r *http.Request, mgr *bundle.Manager, did string) {
+	ctx := r.Context()
+
+	// Bundle package: just retrieve operations
+	operations, err := mgr.GetDIDOperations(ctx, did, false)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	if len(operations) == 0 {
+		http.NotFound(w, r)
+		return
+	}
+
+	// PLC package: format audit log
+	auditLog := plc.FormatAuditLog(operations)
+
+	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("Access-Control-Allow-Origin", "*")
+
+	json.NewEncoder(w).Encode(auditLog)
+}

plc/resolver.go

···
+package plc
+
+import (
+	"fmt"
+	"strings"
+)
+
+// DIDState represents the current state of a DID (PLC-specific format)
+type DIDState struct {
+	DID                 string                       `json:"did"`
+	RotationKeys        []string                     `json:"rotationKeys"`
+	VerificationMethods map[string]string            `json:"verificationMethods"`
+	AlsoKnownAs         []string                     `json:"alsoKnownAs"`
+	Services            map[string]ServiceDefinition `json:"services"`
+}
+
+// ServiceDefinition represents a service endpoint
+type ServiceDefinition struct {
+	Type     string `json:"type"`
+	Endpoint string `json:"endpoint"`
+}
+
+// AuditLogEntry represents a single entry in the audit log
+type AuditLogEntry struct {
+	DID       string      `json:"did"`
+	Operation interface{} `json:"operation"` // The parsed operation data
+	CID       string      `json:"cid"`
+	Nullified interface{} `json:"nullified,omitempty"`
+	CreatedAt string      `json:"createdAt"`
+}
+
+// ResolveDIDDocument constructs a DID document from operation log
+// This is the main entry point for DID resolution
+func ResolveDIDDocument(did string, operations []PLCOperation) (*DIDDocument, error) {
+	if len(operations) == 0 {
+		return nil, fmt.Errorf("no operations found for DID")
+	}
+
+	// Build current state from operations
+	state, err := BuildDIDState(did, operations)
+	if err != nil {
+		return nil, err
+	}
+
+	// Convert to DID document format
+	return StateToDIDDocument(state), nil
+}
+
+// BuildDIDState applies operations in order to build current DID state
+func BuildDIDState(did string, operations []PLCOperation) (*DIDState, error) {
+	var state *DIDState
+
+	for _, op := range operations {
+		// Skip nullified operations
+		if op.IsNullified() {
+			continue
+		}
+
+		// Parse operation data
+		opData, err := op.GetOperationData()
+		if err != nil {
+			return nil, fmt.Errorf("failed to parse operation: %w", err)
+		}
+
+		if opData == nil {
+			continue
+		}
+
+		// Check operation type
+		opType, _ := opData["type"].(string)
+
+		// Handle tombstone (deactivated DID)
+		if opType == "plc_tombstone" {
+			return nil, fmt.Errorf("DID has been deactivated")
+		}
+
+		// Initialize state on first operation
+		if state == nil {
+			state = &DIDState{DID: did}
+		}
+
+		// Apply operation to state
+		applyOperationToState(state, opData)
+	}
+
+	if state == nil {
+		return nil, fmt.Errorf("no valid operations found")
+	}
+
+	return state, nil
+}
+
+// applyOperationToState updates state with data from an operation
+func applyOperationToState(state *DIDState, opData map[string]interface{}) {
+	// Update rotation keys
+	if rotKeys, ok := opData["rotationKeys"].([]interface{}); ok {
+		state.RotationKeys = make([]string, 0, len(rotKeys))
+		for _, k := range rotKeys {
+			if keyStr, ok := k.(string); ok {
+				state.RotationKeys = append(state.RotationKeys, keyStr)
+			}
+		}
+	}
+
+	// Update verification methods
+	if vm, ok := opData["verificationMethods"].(map[string]interface{}); ok {
+		state.VerificationMethods = make(map[string]string)
+		for key, val := range vm {
+			if valStr, ok := val.(string); ok {
+				state.VerificationMethods[key] = valStr
+			}
+		}
+	}
+
+	// Handle legacy signingKey format
+	if signingKey, ok := opData["signingKey"].(string); ok {
+		if state.VerificationMethods == nil {
+			state.VerificationMethods = make(map[string]string)
+		}
+		state.VerificationMethods["atproto"] = signingKey
+	}
+
+	// Update alsoKnownAs
+	if aka, ok := opData["alsoKnownAs"].([]interface{}); ok {
+		state.AlsoKnownAs = make([]string, 0, len(aka))
+		for _, a := range aka {
+			if akaStr, ok := a.(string); ok {
+				state.AlsoKnownAs = append(state.AlsoKnownAs, akaStr)
+			}
+		}
+	}
+
+	// Handle legacy handle format
+	if handle, ok := opData["handle"].(string); ok {
+		if len(state.AlsoKnownAs) == 0 {
+			state.AlsoKnownAs = []string{"at://" + handle}
+		}
+	}
+
+	// Update services
+	if services, ok := opData["services"].(map[string]interface{}); ok {
+		state.Services = make(map[string]ServiceDefinition)
+		for key, svc := range services {
+			if svcMap, ok := svc.(map[string]interface{}); ok {
+				svcType, _ := svcMap["type"].(string)
+				endpoint, _ := svcMap["endpoint"].(string)
+				state.Services[key] = ServiceDefinition{
+					Type:     svcType,
+					Endpoint: normalizeServiceEndpoint(endpoint),
+				}
+			}
+		}
+	}
+
+	// Handle legacy service format
+	if service, ok := opData["service"].(string); ok {
+		if state.Services == nil {
+			state.Services = make(map[string]ServiceDefinition)
+		}
+		state.Services["atproto_pds"] = ServiceDefinition{
+			Type:     "AtprotoPersonalDataServer",
+			Endpoint: normalizeServiceEndpoint(service),
+		}
+	}
+}
+
+// StateToDIDDocument converts internal PLC state to W3C DID document format
+func StateToDIDDocument(state *DIDState) *DIDDocument {
+	// Detect key types to determine correct @context
+	contexts := []string{"https://www.w3.org/ns/did/v1"}
+
+	hasMultikey := false
+	hasSecp256k1 := false
+	hasP256 := false
+
+	// Check verification method key types
+	for _, didKey := range state.VerificationMethods {
+		keyType := detectKeyType(didKey)
+		switch keyType {
+		case "secp256k1":
+			hasSecp256k1 = true
+		case "p256":
+			hasP256 = true
+		default:
+			hasMultikey = true
+		}
+	}
+
+	// Add appropriate context URLs
+	if hasMultikey || hasSecp256k1 || hasP256 {
+		contexts = append(contexts, "https://w3id.org/security/multikey/v1")
+	}
+	if hasSecp256k1 {
+		contexts = append(contexts, "https://w3id.org/security/suites/secp256k1-2019/v1")
+	}
+	if hasP256 {
+		contexts = append(contexts, "https://w3id.org/security/suites/ecdsa-2019/v1")
+	}
+
+	doc := &DIDDocument{
+		Context:     contexts,
+		ID:          state.DID,
+		AlsoKnownAs: state.AlsoKnownAs,
+	}
+
+	// Convert services
+	for id, svc := range state.Services {
+		doc.Service = append(doc.Service, Service{
+			ID:              "#" + id, // ← Just fragment (matching plc.directory)
+			Type:            svc.Type,
+			ServiceEndpoint: svc.Endpoint,
+		})
+	}
+
+	// Keep verification methods with full DID (they're correct):
+	for id, didKey := range state.VerificationMethods {
+		doc.VerificationMethod = append(doc.VerificationMethod, VerificationMethod{
+			ID:                 state.DID + "#" + id, // ← Keep this as-is
+			Type:               "Multikey",
+			Controller:         state.DID,
+			PublicKeyMultibase: ExtractMultibaseFromDIDKey(didKey),
+		})
+	}
+
+	return doc
+}
+
+// detectKeyType detects the key type from did:key encoding
+func detectKeyType(didKey string) string {
+	multibase := ExtractMultibaseFromDIDKey(didKey)
+
+	if len(multibase) < 3 {
+		return "unknown"
+	}
+
+	// The 'z' is the base58btc multibase prefix
+	// Actual key starts at position 1
+	switch {
+	case multibase[1] == 'Q' && multibase[2] == '3': // ← Fixed: was [0] and [1]
+		return "secp256k1" // Starts with zQ3s
+	case multibase[1] == 'D' && multibase[2] == 'n': // ← Fixed
+		return "p256" // Starts with zDn
+	case multibase[1] == '6' && multibase[2] == 'M': // ← Fixed
+		return "ed25519" // Starts with z6Mk
+	default:
+		return "unknown"
+	}
+}
+
+// ExtractMultibaseFromDIDKey extracts the multibase string from did:key: format
+func ExtractMultibaseFromDIDKey(didKey string) string {
+	return strings.TrimPrefix(didKey, "did:key:")
+}
+
+// ValidateDIDFormat validates did:plc format
+func ValidateDIDFormat(did string) error {
+	if !strings.HasPrefix(did, "did:plc:") {
+		return fmt.Errorf("invalid DID method: must start with 'did:plc:'")
+	}
+
+	if len(did) != 32 {
+		return fmt.Errorf("invalid DID length: expected 32 chars, got %d", len(did))
+	}
+
+	// Validate identifier part (24 chars, base32 alphabet)
+	identifier := strings.TrimPrefix(did, "did:plc:")
+	if len(identifier) != 24 {
+		return fmt.Errorf("invalid identifier length: expected 24 chars, got %d", len(identifier))
+	}
+
+	// Check base32 alphabet (a-z, 2-7, no 0189)
+	for _, c := range identifier {
+		if !((c >= 'a' && c <= 'z') || (c >= '2' && c <= '7')) {
+			return fmt.Errorf("invalid character in identifier: %c (must be base32: a-z, 2-7)", c)
+		}
+	}
+
+	return nil
+}
+
+// FormatAuditLog formats operations as an audit log
+func FormatAuditLog(operations []PLCOperation) []AuditLogEntry {
+	log := make([]AuditLogEntry, 0, len(operations))
+
+	for _, op := range operations {
+		// Parse operation for the log
+		opData, _ := op.GetOperationData()
+
+		entry := AuditLogEntry{
+			DID:       op.DID,
+			Operation: opData,
+			CID:       op.CID,
+			Nullified: op.Nullified,
+			CreatedAt: op.CreatedAt.Format("2006-01-02T15:04:05.000Z"),
+		}
+
+		log = append(log, entry)
+	}
+
+	return log
+}
+
+func normalizeServiceEndpoint(endpoint string) string {
+	// If already has protocol, return as-is
+	if strings.HasPrefix(endpoint, "http://") || strings.HasPrefix(endpoint, "https://") {
+		return endpoint
+	}
+
+	// Legacy format: add https:// prefix
+	return "https://" + endpoint
+}

scripts/test-did-resolution.sh

···
+#!/bin/bash
+# test-did-resolution.sh
+# Compares local DID resolution with plc.directory
+
+set -e
+
+BUNDLE_RANGE="${1:-1}"
+PLC_URL="https://plc.wtf"
+TEMP_DIR=$(mktemp -d)
+trap "rm -rf $TEMP_DIR" EXIT
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+echo "Testing DID resolution for bundle(s): $BUNDLE_RANGE"
+echo "Temp directory: $TEMP_DIR"
+echo ""
+
+# Extract unique DIDs from bundle(s)
+echo "Extracting DIDs from bundles..."
+DIDS=$(plcbundle export --bundles "$BUNDLE_RANGE" | jq -r '.did' | sort -u)
+DID_COUNT=$(echo "$DIDS" | wc -l | tr -d ' ')
+
+echo "Found $DID_COUNT unique DIDs"
+echo ""
+
+# Test counters
+TOTAL=0
+PASSED=0
+FAILED=0
+ERRORS=0
+
+# Test each DID
+while IFS= read -r DID; do
+    TOTAL=$((TOTAL + 1))
+    
+    # Progress
+    echo -ne "\r[$TOTAL/$DID_COUNT] Testing $DID..."
+    
+    # Resolve locally
+    LOCAL_FILE="$TEMP_DIR/local.json"
+    if ! plcbundle index resolve "$DID" 2>/dev/null | jq --sort-keys . > "$LOCAL_FILE" 2>/dev/null; then
+        echo -e "\r[$TOTAL/$DID_COUNT] ${RED}ERROR${NC} $DID (local resolution failed)"
+        ERRORS=$((ERRORS + 1))
+        continue
+    fi
+    
+    # Resolve remotely
+    REMOTE_FILE="$TEMP_DIR/remote.json"
+    if ! curl -s "$PLC_URL/$DID" | jq --sort-keys . > "$REMOTE_FILE" 2>/dev/null; then
+        echo -e "\r[$TOTAL/$DID_COUNT] ${YELLOW}SKIP${NC} $DID (remote fetch failed)"
+        ERRORS=$((ERRORS + 1))
+        continue
+    fi
+    
+    # Compare
+    if diff -q "$LOCAL_FILE" "$REMOTE_FILE" > /dev/null 2>&1; then
+        echo -e "\r[$TOTAL/$DID_COUNT] ${GREEN}✓${NC} $DID"
+        PASSED=$((PASSED + 1))
+    else
+        echo -e "\r[$TOTAL/$DID_COUNT] ${RED}✗${NC} $DID"
+        echo ""
+        echo "Differences found:"
+        diff -u "$REMOTE_FILE" "$LOCAL_FILE" | head -20
+        echo ""
+        FAILED=$((FAILED + 1))
+        
+        # Ask to continue
+        if [ $FAILED -ge 3 ]; then
+            echo ""
+            read -p "Continue testing? (y/N) " -n 1 -r
+            echo
+            if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+                break
+            fi
+        fi
+    fi
+    
+    # Rate limit
+    sleep 0.1
+    
+done <<< "$DIDS"
+
+# Summary
+echo ""
+echo "========================================="
+echo "Test Results"
+echo "========================================="
+echo -e "Total:   $TOTAL"
+echo -e "${GREEN}Passed:  $PASSED${NC}"
+echo -e "${RED}Failed:  $FAILED${NC}"
+echo -e "${YELLOW}Errors:  $ERRORS${NC}"
+echo ""
+
+if [ $FAILED -eq 0 ] && [ $ERRORS -eq 0 ]; then
+    echo -e "${GREEN}✓ All tests passed!${NC}"
+    exit 0
+else
+    echo -e "${RED}✗ Some tests failed${NC}"
+    exit 1
+fi