zstd frames update

bundle/bundle_test.go

···
 		path := filepath.Join(tmpDir, "test_bundle.jsonl.zst")
 
 		// Save
-		uncompHash, compHash, uncompSize, compSize, err := ops.SaveBundle(path, operations)
+		uncompHash, compHash, uncompSize, compSize, err := ops.SaveBundle(path, operations, nil)
 		if err != nil {
 			t.Fatalf("SaveBundle failed: %v", err)
 		}

bundle/manager.go

···
 	"os"
 	"path/filepath"
 	"runtime"
+	"runtime/debug"
 	"sort"
 	"strings"
 	"sync"
···
 }
 
 // SaveBundle saves a bundle to disk and updates the index
-// Returns the DID index update duration
 func (m *Manager) SaveBundle(ctx context.Context, bundle *Bundle, quiet bool) (time.Duration, error) {
 	if err := bundle.ValidateForSave(); err != nil {
 		return 0, fmt.Errorf("bundle validation failed: %w", err)
···
 
 	path := filepath.Join(m.config.BundleDir, fmt.Sprintf("%06d.jsonl.zst", bundle.BundleNumber))
 
-	// Save to disk
-	uncompressedHash, compressedHash, uncompressedSize, compressedSize, err := m.operations.SaveBundle(path, bundle.Operations)
-	if err != nil {
-		return 0, fmt.Errorf("failed to save bundle: %w", err)
-	}
-
-	bundle.ContentHash = uncompressedHash
-	bundle.CompressedHash = compressedHash
-	bundle.UncompressedSize = uncompressedSize
-	bundle.CompressedSize = compressedSize
-	bundle.CreatedAt = time.Now().UTC()
-
 	// Get parent
 	var parent string
 	if bundle.BundleNumber > 1 {
···
 			}
 		}
 	}
+	bundle.Parent = parent
 
-	bundle.Parent = parent
+	// Get origin
+	origin := m.index.Origin
+	if m.plcClient != nil {
+		origin = m.plcClient.GetBaseURL()
+	}
+
+	// Get version
+	version := "dev"
+	if info, ok := debug.ReadBuildInfo(); ok && info.Main.Version != "" && info.Main.Version != "(devel)" {
+		version = info.Main.Version
+	}
+
+	// Get hostname
+	hostname, _ := os.Hostname()
+
+	// ✅ Create BundleInfo
+	bundleInfo := &storage.BundleInfo{
+		BundleNumber: bundle.BundleNumber,
+		Origin:       origin,
+		ParentHash:   parent,
+		Cursor:       bundle.Cursor,
+		CreatedBy:    fmt.Sprintf("plcbundle/%s", version),
+		Hostname:     hostname,
+	}
+
+	m.logger.Printf("DEBUG: Calling operations.SaveBundle with bundle=%d", bundleInfo.BundleNumber)
+
+	// ✅ Save to disk with 3 parameters
+	uncompressedHash, compressedHash, uncompressedSize, compressedSize, err := m.operations.SaveBundle(path, bundle.Operations, bundleInfo)
+	if err != nil {
+		m.logger.Printf("DEBUG: SaveBundle FAILED: %v", err)
+		return 0, fmt.Errorf("failed to save bundle: %w", err)
+	}
+
+	m.logger.Printf("DEBUG: SaveBundle SUCCESS, setting bundle fields")
+
+	bundle.ContentHash = uncompressedHash
+	bundle.CompressedHash = compressedHash
+	bundle.UncompressedSize = uncompressedSize
+	bundle.CompressedSize = compressedSize
+	bundle.CreatedAt = time.Now().UTC()
 	bundle.Hash = m.operations.CalculateChainHash(parent, bundle.ContentHash)
+
+	m.logger.Printf("DEBUG: Adding bundle %d to index", bundle.BundleNumber)
 
 	// Add to index
 	m.index.AddBundle(bundle.ToMetadata())
 
+	m.logger.Printf("DEBUG: Index now has %d bundles", m.index.Count())
+
 	// Save index
 	if err := m.SaveIndex(); err != nil {
+		m.logger.Printf("DEBUG: SaveIndex FAILED: %v", err)
 		return 0, fmt.Errorf("failed to save index: %w", err)
 	}
 
+	m.logger.Printf("DEBUG: Index saved, last bundle = %d", m.index.GetLastBundle().BundleNumber)
+
 	// Clean up old mempool
 	oldMempoolFile := m.mempool.GetFilename()
 	if err := m.mempool.Delete(); err != nil && !quiet {
···
 		return 0, fmt.Errorf("failed to create new mempool: %w", err)
 	}
 
-	oldMempool := m.mempool
 	m.mempool = newMempool
 
-	oldMempool.Clear()
-
-	// ✨ Update DID index if enabled and track timing
+	// DID index update (if enabled)
 	var indexUpdateDuration time.Duration
 	if m.didIndex != nil && m.didIndex.Exists() {
 		indexUpdateStart := time.Now()
-
 		if err := m.updateDIDIndexForBundle(ctx, bundle); err != nil {
 			m.logger.Printf("Warning: failed to update DID index: %v", err)
 		} else {
 			indexUpdateDuration = time.Since(indexUpdateStart)
-
 			if !quiet {
 				m.logger.Printf("  [DID Index] Updated in %s", indexUpdateDuration)
 			}

cmd/plcbundle/commands/inspect.go

···
 	result.FileSize = info.Size()
 
 	// Check for frame index
-	indexPath := bundlePath + ".idx"
-	if _, err := os.Stat(indexPath); err == nil {
-		result.HasFrameIndex = true
+	ops := &storage.Operations{}
+	if _, err := ops.ExtractBundleMetadata(bundlePath); err == nil {
+		result.HasFrameIndex = true // Has embedded index
+	} else {
+		// Check for external .idx file (legacy)
+		indexPath := bundlePath + ".idx"
+		if _, err := os.Stat(indexPath); err == nil {
+			result.HasFrameIndex = true
+		}
 	}
 
 	fmt.Fprintf(os.Stderr, "Inspecting: %s\n", filepath.Base(bundlePath))
···
 // DISPLAY FUNCTIONS
 // ============================================================================
 
-func displayInspectHuman(result *inspectResult, analysis *bundleAnalysis, opts inspectOptions) error {
+func displayInspectHuman(result *inspectResult, _ *bundleAnalysis, opts inspectOptions) error {
 	fmt.Printf("\n")
 	fmt.Printf("═══════════════════════════════════════════════════════════════\n")
 	fmt.Printf("                    Bundle Deep Inspection\n")
···
 		meta := result.Metadata
 		fmt.Printf("📋 Embedded Metadata (Skippable Frame)\n")
 		fmt.Printf("──────────────────────────────────────\n")
+		fmt.Printf("  Format:              %s (v%d)\n", meta.Format, meta.Version)
+		if meta.SpecURL != "" {
+			fmt.Printf("  Specification:       %s\n", meta.SpecURL)
+		}
 		fmt.Printf("  Bundle Number:       %06d\n", meta.BundleNumber)
 		if meta.Origin != "" {
 			fmt.Printf("  Origin:              %s\n", meta.Origin)
 		}
-		fmt.Printf("  Operations:          %s\n", formatNumber(meta.OperationCount))
-		fmt.Printf("  DIDs:                %s unique\n", formatNumber(meta.DIDCount))
-		fmt.Printf("  Frames:              %d\n", meta.FrameCount)
-		fmt.Printf("  Uncompressed:        %s\n", formatBytes(meta.UncompressedSize))
-		fmt.Printf("  Compressed:          %s (%.2fx)\n",
-			formatBytes(meta.CompressedSize),
-			float64(meta.UncompressedSize)/float64(meta.CompressedSize))
-		fmt.Printf("  Timespan:            %s → %s\n",
+		if meta.CreatedBy != "" {
+			fmt.Printf("  Created by:          %s\n", meta.CreatedBy)
+		}
+		if meta.CreatedByHost != "" {
+			fmt.Printf("  Created on:          %s\n", meta.CreatedByHost)
+		}
+		fmt.Printf("  Created at:          %s\n", meta.CreatedAt.Format("2006-01-02 15:04:05 MST"))
+
+		fmt.Printf("\n  Content:\n")
+		fmt.Printf("    Operations:        %s\n", formatNumber(meta.OperationCount))
+		fmt.Printf("    Unique DIDs:       %s\n", formatNumber(meta.DIDCount))
+		fmt.Printf("    Frames:            %d × %d ops\n", meta.FrameCount, meta.FrameSize)
+		fmt.Printf("    Timespan:          %s → %s\n",
 			meta.StartTime.Format("2006-01-02 15:04:05"),
 			meta.EndTime.Format("2006-01-02 15:04:05"))
-		fmt.Printf("  Duration:            %s\n",
+		fmt.Printf("    Duration:          %s\n",
 			formatDuration(meta.EndTime.Sub(meta.StartTime)))
 
-		if meta.ContentHash != "" {
-			fmt.Printf("\n  Hashes:\n")
-			fmt.Printf("    Content:           %s\n", meta.ContentHash[:16]+"...")
-			fmt.Printf("    Compressed:        %s\n", meta.CompressedHash[:16]+"...")
-			if meta.ParentHash != "" {
-				fmt.Printf("    Parent:            %s\n", meta.ParentHash[:16]+"...")
-			}
+		fmt.Printf("\n  Integrity:\n")
+		fmt.Printf("    Content hash:      %s\n", meta.ContentHash)
+		if meta.ParentHash != "" {
+			fmt.Printf("    Parent hash:       %s\n", meta.ParentHash)
+		}
+
+		if len(meta.FrameOffsets) > 0 {
+			fmt.Printf("\n  Frame Index:         %d offsets (embedded)\n", len(meta.FrameOffsets))
+			firstDataOffset := meta.FrameOffsets[0]
+			fmt.Printf("    Metadata size:     %s\n", formatBytes(firstDataOffset))
+			fmt.Printf("    First data frame:  offset %d\n", firstDataOffset)
 		}
 		fmt.Printf("\n")
 	}
···
 func verifyCrypto(cmd *cobra.Command, path string, meta *storage.BundleMetadata, bundleNum int, verbose bool) (contentValid, compressedValid, metadataValid bool) {
 	ops := &storage.Operations{}
 
-	// Calculate actual hashes
+	// Calculate actual hashes from file
 	compHash, compSize, contentHash, contentSize, err := ops.CalculateFileHashes(path)
 	if err != nil {
 		if verbose {
···
 	compressedValid = true
 	metadataValid = true
 
-	// Verify against embedded metadata if available
+	// ✅ Verify against embedded metadata if available
 	if meta != nil {
+		// Check content hash (this is in the metadata)
 		if meta.ContentHash != "" && meta.ContentHash != contentHash {
 			contentValid = false
 			if verbose {
···
 			}
 		}
 
-		if meta.CompressedHash != "" && meta.CompressedHash != compHash {
-			compressedValid = false
-			if verbose {
-				fmt.Fprintf(os.Stderr, "  ✗ Compressed hash mismatch!\n")
-			}
+		if meta.OperationCount > 0 {
+			// We can't verify this without loading, so skip
+			metadataValid = true
 		}
 
-		if meta.UncompressedSize != contentSize {
-			metadataValid = false
-			if verbose {
-				fmt.Fprintf(os.Stderr, "  ✗ Uncompressed size mismatch: meta=%d, actual=%d\n",
-					meta.UncompressedSize, contentSize)
-			}
-		}
+		// ✅ Note: We don't check compressed hash/size because they're not in metadata
+		// (The file IS the compressed data, so it's redundant)
 
-		if meta.CompressedSize != compSize {
-			metadataValid = false
-			if verbose {
-				fmt.Fprintf(os.Stderr, "  ✗ Compressed size mismatch: meta=%d, actual=%d\n",
-					meta.CompressedSize, compSize)
-			}
+		if verbose {
+			fmt.Fprintf(os.Stderr, "  Embedded metadata:\n")
+			fmt.Fprintf(os.Stderr, "    Content hash: %s\n", meta.ContentHash[:16]+"...")
+			fmt.Fprintf(os.Stderr, "    Operations: %d\n", meta.OperationCount)
+			fmt.Fprintf(os.Stderr, "    DIDs: %d\n", meta.DIDCount)
 		}
 	}
 
-	// Also verify against repository index if bundle number is known
+	// ✅ Also verify against repository index if bundle number is known
 	if bundleNum > 0 {
-		mgr, _, err := getManager(nil)
+		mgr, _, err := getManager(&ManagerOptions{Cmd: cmd})
 		if err == nil {
 			defer mgr.Close()
 
 			ctx := context.Background()
 			vr, err := mgr.VerifyBundle(ctx, bundleNum)
-			if err == nil {
-				contentValid = contentValid && vr.Valid
-				compressedValid = compressedValid && vr.HashMatch
+			if err == nil && vr != nil {
+				// Index verification
+				indexContentValid := vr.Valid
+				indexHashMatch := vr.HashMatch
+
+				if verbose {
+					fmt.Fprintf(os.Stderr, "  Repository index:\n")
+					fmt.Fprintf(os.Stderr, "    Content valid: %v\n", indexContentValid)
+					fmt.Fprintf(os.Stderr, "    Hash match: %v\n", indexHashMatch)
+				}
+
+				contentValid = contentValid && indexContentValid
+				compressedValid = compressedValid && indexHashMatch
 			}
 		}
+	}
+
+	if verbose {
+		fmt.Fprintf(os.Stderr, "  Calculated hashes:\n")
+		fmt.Fprintf(os.Stderr, "    Content: %s (%s)\n", contentHash[:16]+"...", formatBytes(contentSize))
+		fmt.Fprintf(os.Stderr, "    Compressed: %s (%s)\n", compHash[:16]+"...", formatBytes(compSize))
 	}
 
 	return contentValid, compressedValid, metadataValid

cmd/plcbundle/commands/migrate.go

···
 
 	"github.com/spf13/cobra"
 	"tangled.org/atscan.net/plcbundle/cmd/plcbundle/ui"
+	"tangled.org/atscan.net/plcbundle/internal/bundleindex"
 	"tangled.org/atscan.net/plcbundle/internal/storage"
 )
 
···
 func runMigration(mgr BundleManager, dir string, opts migrationOptions) error {
 	fmt.Printf("Scanning for legacy bundles in: %s\n\n", dir)
 
-	// Find bundles needing migration
 	index := mgr.GetIndex()
 	bundles := index.GetBundles()
 
···
 		return nil
 	}
 
+	// Get plcbundle version
+	version := GetVersion()
+
 	var needsMigration []int
 	var totalSize int64
 
+	ops := &storage.Operations{}
 	for _, meta := range bundles {
 		bundlePath := filepath.Join(dir, fmt.Sprintf("%06d.jsonl.zst", meta.BundleNumber))
-		idxPath := bundlePath + ".idx"
 
-		// Check if .idx file exists
-		if _, err := os.Stat(idxPath); os.IsNotExist(err) || opts.force {
+		// Check if already has embedded metadata
+		_, err := ops.ExtractBundleMetadata(bundlePath)
+
+		if err != nil || opts.force {
 			needsMigration = append(needsMigration, meta.BundleNumber)
 			totalSize += meta.CompressedSize
 		}
···
 		return nil
 	}
 
-	// Display migration plan
+	// Display plan
 	fmt.Printf("Migration Plan\n")
 	fmt.Printf("══════════════\n\n")
 	fmt.Printf("  Bundles to migrate: %d\n", len(needsMigration))
 	fmt.Printf("  Total size:         %s\n", formatBytes(totalSize))
 	fmt.Printf("  Workers:            %d\n", opts.workers)
+	fmt.Printf("  plcbundle version:  %s\n", version)
 	fmt.Printf("\n")
 
-	if len(needsMigration) <= 20 {
-		fmt.Printf("  Bundles: ")
-		for i, num := range needsMigration {
-			if i > 0 {
-				fmt.Printf(", ")
-			}
-			fmt.Printf("%06d", num)
-		}
-		fmt.Printf("\n\n")
-	} else {
-		fmt.Printf("  Range: %06d - %06d\n\n", needsMigration[0], needsMigration[len(needsMigration)-1])
-	}
-
 	if opts.dryRun {
 		fmt.Printf("💡 This is a dry-run. No files will be modified.\n")
-		fmt.Printf("   Run without --dry-run to perform migration.\n")
 		return nil
 	}
 
···
 	success := 0
 	failed := 0
 	var firstError error
+	hashChanges := make([]int, 0, len(needsMigration))
 
 	for i, bundleNum := range needsMigration {
-		if err := migrateBundle(dir, bundleNum, opts.verbose); err != nil {
+		// ✅ Pass version to migrateBundle
+		if err := migrateBundle(dir, bundleNum, index, version, opts.verbose); err != nil {
 			failed++
 			if firstError == nil {
 				firstError = err
···
 			}
 		} else {
 			success++
+			hashChanges = append(hashChanges, bundleNum)
+
 			if opts.verbose {
 				fmt.Fprintf(os.Stderr, "✓ Migrated bundle %06d\n", bundleNum)
 			}
···
 	progress.Finish()
 	elapsed := time.Since(start)
 
+	// ✅ Update index with new compressed hashes
+	if len(hashChanges) > 0 {
+		fmt.Printf("\nUpdating bundle index...\n")
+		updateStart := time.Now()
+
+		updated := 0
+		for _, bundleNum := range hashChanges {
+			bundlePath := filepath.Join(dir, fmt.Sprintf("%06d.jsonl.zst", bundleNum))
+
+			// Recalculate hashes
+			compHash, compSize, contentHash, contentSize, err := ops.CalculateFileHashes(bundlePath)
+			if err != nil {
+				fmt.Fprintf(os.Stderr, "  ⚠️  Failed to hash bundle %06d: %v\n", bundleNum, err)
+				continue
+			}
+
+			// Get and update metadata
+			bundleMeta, err := index.GetBundle(bundleNum)
+			if err != nil {
+				continue
+			}
+
+			// Verify content hash unchanged
+			if bundleMeta.ContentHash != contentHash {
+				fmt.Fprintf(os.Stderr, "  ⚠️  Content hash changed for %06d (unexpected!)\n", bundleNum)
+			}
+
+			// Update compressed info (this changed due to skippable frames)
+			bundleMeta.CompressedHash = compHash
+			bundleMeta.CompressedSize = compSize
+			bundleMeta.UncompressedSize = contentSize
+
+			index.AddBundle(bundleMeta)
+			updated++
+		}
+
+		// Save index
+		if err := mgr.SaveIndex(); err != nil {
+			fmt.Fprintf(os.Stderr, "  ⚠️  Failed to save index: %v\n", err)
+		} else {
+			fmt.Printf("  ✓ Updated %d entries in %s\n", updated, time.Since(updateStart).Round(time.Millisecond))
+		}
+	}
+
 	// Summary
 	fmt.Printf("\n")
 	if failed == 0 {
 		fmt.Printf("✓ Migration complete in %s\n", elapsed.Round(time.Millisecond))
-		fmt.Printf("  Migrated: %d bundles\n", success)
-		fmt.Printf("  Speed:    %.1f bundles/sec\n", float64(success)/elapsed.Seconds())
+		fmt.Printf("  Migrated:     %d bundles\n", success)
+		fmt.Printf("  Index updated: %d entries\n", len(hashChanges))
+		fmt.Printf("  Speed:        %.1f bundles/sec\n\n", float64(success)/elapsed.Seconds())
+
+		fmt.Printf("✨ New bundle format features:\n")
+		fmt.Printf("   • Embedded metadata (JSON in skippable frame)\n")
+		fmt.Printf("   • Frame offsets for instant random access\n")
+		fmt.Printf("   • Multi-frame compression (100 ops/frame)\n")
+		fmt.Printf("   • Self-contained (no .idx files)\n")
+		fmt.Printf("   • Provenance tracking (version, origin, creator)\n")
+		fmt.Printf("   • Compatible with standard zstd tools\n")
 	} else {
 		fmt.Printf("⚠️  Migration completed with errors\n")
 		fmt.Printf("  Success:  %d bundles\n", success)
···
 	return nil
 }
 
-func migrateBundle(dir string, bundleNum int, verbose bool) error {
+func migrateBundle(dir string, bundleNum int, index *bundleindex.Index, version string, verbose bool) error {
 	bundlePath := filepath.Join(dir, fmt.Sprintf("%06d.jsonl.zst", bundleNum))
-	idxPath := bundlePath + ".idx"
 	backupPath := bundlePath + ".bak"
 
-	// 1. Load the bundle using legacy method (full decompression)
+	// 1. Get metadata from index
+	meta, err := index.GetBundle(bundleNum)
+	if err != nil {
+		return fmt.Errorf("bundle not in index: %w", err)
+	}
+
+	// 2. Load the bundle using old format
 	ops := &storage.Operations{}
 	operations, err := ops.LoadBundle(bundlePath)
 	if err != nil {
···
 		fmt.Fprintf(os.Stderr, "  Loaded %d operations\n", len(operations))
 	}
 
-	// 2. Backup original file
+	// 3. Backup original file
 	if err := os.Rename(bundlePath, backupPath); err != nil {
 		return fmt.Errorf("failed to backup: %w", err)
 	}
 
-	// 3. Save using new multi-frame format
-	contentHash, compHash, contentSize, compSize, err := ops.SaveBundle(bundlePath, operations)
+	// 4. Get hostname (optional)
+	hostname, _ := os.Hostname()
+
+	// 5. ✅ Create BundleInfo for new format
+	bundleInfo := &storage.BundleInfo{
+		BundleNumber: meta.BundleNumber,
+		Origin:       index.Origin, // From index
+		ParentHash:   meta.Parent,
+		Cursor:       meta.Cursor,
+		CreatedBy:    fmt.Sprintf("plcbundle/%s", version),
+		Hostname:     hostname,
+	}
+
+	// 6. Save using new format (with skippable frame metadata)
+	contentHash, compHash, contentSize, compSize, err := ops.SaveBundle(bundlePath, operations, bundleInfo)
 	if err != nil {
 		// Restore backup on failure
 		os.Rename(backupPath, bundlePath)
 		return fmt.Errorf("failed to save: %w", err)
 	}
 
-	// 4. Verify .idx file was created
-	if _, err := os.Stat(idxPath); os.IsNotExist(err) {
-		// Restore backup if .idx wasn't created
+	// 7. Verify embedded metadata was created
+	embeddedMeta, err := ops.ExtractBundleMetadata(bundlePath)
+	if err != nil {
+		os.Remove(bundlePath)
+		os.Rename(backupPath, bundlePath)
+		return fmt.Errorf("embedded metadata not created: %w", err)
+	}
+
+	// 8. Verify frame offsets are present
+	if len(embeddedMeta.FrameOffsets) == 0 {
 		os.Remove(bundlePath)
 		os.Rename(backupPath, bundlePath)
-		return fmt.Errorf("frame index not created")
+		return fmt.Errorf("frame offsets missing in metadata")
 	}
 
-	// 5. Cleanup backup
+	// 9. Verify content hash matches (should be unchanged)
+	if contentHash != meta.ContentHash {
+		fmt.Fprintf(os.Stderr, "  ⚠️  Content hash changed (unexpected): %s → %s\n",
+			meta.ContentHash[:12], contentHash[:12])
+	}
+
+	// 10. Cleanup backup
 	os.Remove(backupPath)
 
 	if verbose {
-		fmt.Fprintf(os.Stderr, "  Content: %s (%s)\n", contentHash[:12], formatBytes(contentSize))
-		fmt.Fprintf(os.Stderr, "  Compressed: %s (%s)\n", compHash[:12], formatBytes(compSize))
+		fmt.Fprintf(os.Stderr, "  Content hash: %s (%s)\n", contentHash[:12], formatBytes(contentSize))
+		fmt.Fprintf(os.Stderr, "  New compressed hash: %s (%s)\n", compHash[:12], formatBytes(compSize))
+		fmt.Fprintf(os.Stderr, "  Frames: %d (embedded in metadata)\n", len(embeddedMeta.FrameOffsets)-1)
 	}
 
 	return nil

internal/storage/storage.go

···
 	"tangled.org/atscan.net/plcbundle/internal/plcclient"
 )
 
+const (
+	MetadataFormatVersion = 1
+)
+
+// BundleMetadata - Self-describing bundle (content-focused, not container)
+type BundleMetadata struct {
+	// === Format Info ===
+	Version int    `json:"version"`  // Metadata schema version (1)
+	Format  string `json:"format"`   // "plcbundle-v1"
+	SpecURL string `json:"spec_url"` // "https://github.com/atscan-net/plcbundle"
+
+	// === Bundle Identity ===
+	BundleNumber int    `json:"bundle_number"` // Sequential bundle number
+	Origin       string `json:"origin"`        // Source PLC directory URL
+
+	// === Creation Provenance ===
+	CreatedAt     time.Time `json:"created_at"`                // When bundle was created
+	CreatedBy     string    `json:"created_by"`                // "plcbundle/v1.2.3"
+	CreatedByHost string    `json:"created_by_host,omitempty"` // Optional: hostname that created it
+
+	// === Content Integrity ===
+	ContentHash string `json:"content_hash"`          // SHA256 of uncompressed JSONL content
+	ParentHash  string `json:"parent_hash,omitempty"` // Hash of previous bundle (chain)
+
+	// === Content Description ===
+	OperationCount int       `json:"operation_count"` // Always 10000 for complete bundles
+	DIDCount       int       `json:"did_count"`       // Unique DIDs in this bundle
+	StartTime      time.Time `json:"start_time"`      // First operation timestamp
+	EndTime        time.Time `json:"end_time"`        // Last operation timestamp
+
+	// === Frame Structure (for random access) ===
+	FrameCount   int     `json:"frame_count"`   // Number of zstd frames (usually 100)
+	FrameSize    int     `json:"frame_size"`    // Operations per frame (100)
+	FrameOffsets []int64 `json:"frame_offsets"` // Byte offsets of each frame
+
+	// === Optional Context ===
+	Cursor string `json:"cursor,omitempty"` // PLC export cursor for this bundle
+	Notes  string `json:"notes,omitempty"`  // Optional description
+}
+
 // Operations handles low-level bundle file operations
 type Operations struct {
 	logger Logger
···
 
 func (op *Operations) Close() {
 	// Nothing to close
+}
+
+// BundleInfo contains info needed to create metadata
+type BundleInfo struct {
+	BundleNumber int
+	Origin       string
+	ParentHash   string
+	Cursor       string
+	CreatedBy    string // "plcbundle/v1.2.3"
+	Hostname     string // Optional
 }
 
 // ========================================
···
 // FILE OPERATIONS (using zstd abstraction)
 // ========================================
 
-// SaveBundle saves operations to disk with embedded metadata
-func (op *Operations) SaveBundle(path string, operations []plcclient.PLCOperation) (string, string, int64, int64, error) {
-	// 1. Serialize all operations once
+// SaveBundle saves operations with metadata containing RELATIVE frame offsets
+func (op *Operations) SaveBundle(path string, operations []plcclient.PLCOperation, bundleInfo *BundleInfo) (string, string, int64, int64, error) {
+	// 1. Calculate content
 	jsonlData := op.SerializeJSONL(operations)
 	contentSize := int64(len(jsonlData))
 	contentHash := op.Hash(jsonlData)
+	dids := op.ExtractUniqueDIDs(operations)
 
-	// 2. Create the destination file
-	bundleFile, err := os.Create(path)
-	if err != nil {
-		return "", "", 0, 0, fmt.Errorf("could not create bundle file: %w", err)
+	hostnameHash := ""
+	if bundleInfo.Hostname != "" {
+		hostnameHash = op.Hash([]byte(bundleInfo.Hostname))[:16] // First 16 chars (64 bits)
 	}
-	defer bundleFile.Close()
 
-	// ✅ 3. Write metadata as skippable frame FIRST (placeholder - will update later)
-	// We write a placeholder now and update after we know the compressed size
-	placeholderMeta := &BundleMetadata{
-		Version:          1,
-		BundleNumber:     0, // Will be set by caller
-		UncompressedSize: contentSize,
-		OperationCount:   len(operations),
-		FrameCount:       (len(operations) + FrameSize - 1) / FrameSize,
-		CreatedAt:        time.Now().UTC(),
-	}
+	// 2. Compress all frames
+	compressedFrames := make([][]byte, 0)
 
-	metadataStart, err := WriteMetadataFrame(bundleFile, placeholderMeta)
-	if err != nil {
-		return "", "", 0, 0, fmt.Errorf("failed to write metadata frame: %w", err)
-	}
-
-	frameOffsets := []int64{metadataStart} // First data frame starts after metadata
-
-	// 4. Write data frames
 	for i := 0; i < len(operations); i += FrameSize {
 		end := i + FrameSize
 		if end > len(operations) {
···
 		opChunk := operations[i:end]
 		chunkJsonlData := op.SerializeJSONL(opChunk)
 
-		// Compress this chunk
 		compressedChunk, err := CompressFrame(chunkJsonlData)
 		if err != nil {
 			return "", "", 0, 0, fmt.Errorf("failed to compress frame: %w", err)
 		}
 
-		// Write frame to file
-		_, err = bundleFile.Write(compressedChunk)
-		if err != nil {
-			return "", "", 0, 0, fmt.Errorf("failed to write frame: %w", err)
-		}
+		compressedFrames = append(compressedFrames, compressedChunk)
+	}
 
-		// Get current offset for next frame
-		currentOffset, err := bundleFile.Seek(0, io.SeekCurrent)
-		if err != nil {
-			return "", "", 0, 0, fmt.Errorf("failed to get file offset: %w", err)
-		}
+	// 3. ✅ Calculate RELATIVE offsets (relative to first data frame)
+	relativeOffsets := make([]int64, len(compressedFrames)+1)
+	relativeOffsets[0] = 0
 
-		if end < len(operations) {
-			frameOffsets = append(frameOffsets, currentOffset)
-		}
+	cumulative := int64(0)
+	for i, frame := range compressedFrames {
+		cumulative += int64(len(frame))
+		relativeOffsets[i+1] = cumulative
 	}
 
-	// 5. Get final file size
-	finalSize, _ := bundleFile.Seek(0, io.SeekCurrent)
-	frameOffsets = append(frameOffsets, finalSize)
+	// 4. ✅ Build metadata with RELATIVE offsets
+	metadata := &BundleMetadata{
+		Version:        MetadataFormatVersion,
+		Format:         "plcbundle-v1",
+		SpecURL:        "https://github.com/atscan-net/plcbundle",
+		BundleNumber:   bundleInfo.BundleNumber,
+		Origin:         bundleInfo.Origin,
+		CreatedAt:      time.Now().UTC(),
+		CreatedBy:      bundleInfo.CreatedBy,
+		CreatedByHost:  hostnameHash,
+		ContentHash:    contentHash,
+		ParentHash:     bundleInfo.ParentHash,
+		OperationCount: len(operations),
+		DIDCount:       len(dids),
+		FrameCount:     len(compressedFrames),
+		FrameSize:      FrameSize,
+		Cursor:         bundleInfo.Cursor,
+		FrameOffsets:   relativeOffsets, // ✅ RELATIVE to data start!
+	}
 
-	// 6. Sync to disk
-	if err := bundleFile.Sync(); err != nil {
-		return "", "", 0, 0, fmt.Errorf("failed to sync file: %w", err)
+	if len(operations) > 0 {
+		metadata.StartTime = operations[0].CreatedAt
+		metadata.EndTime = operations[len(operations)-1].CreatedAt
 	}
 
-	// 7. Save frame index (still useful for random access)
-	indexPath := path + ".idx"
-	indexData, _ := json.Marshal(frameOffsets)
-	if err := os.WriteFile(indexPath, indexData, 0644); err != nil {
-		os.Remove(path)
-		return "", "", 0, 0, fmt.Errorf("failed to write frame index: %w", err)
+	// 5. Write final file
+	finalFile, err := os.Create(path)
+	if err != nil {
+		return "", "", 0, 0, fmt.Errorf("failed to create file: %w", err)
 	}
+	defer func() {
+		finalFile.Close()
+		if err != nil {
+			os.Remove(path)
+		}
+	}()
 
-	// 8. Calculate compressed hash
+	// Write metadata frame
+	if _, err := WriteMetadataFrame(finalFile, metadata); err != nil {
+		return "", "", 0, 0, fmt.Errorf("failed to write metadata: %w", err)
+	}
+
+	// Write all data frames
+	for _, frame := range compressedFrames {
+		if _, err := finalFile.Write(frame); err != nil {
+			return "", "", 0, 0, fmt.Errorf("failed to write frame: %w", err)
+		}
+	}
+
+	finalFile.Sync()
+	finalFile.Close()
+
+	// 6. Hash
 	compressedData, err := os.ReadFile(path)
 	if err != nil {
-		return "", "", 0, 0, fmt.Errorf("failed to re-read bundle for hashing: %w", err)
+		return "", "", 0, 0, err
 	}
 	compressedHash := op.Hash(compressedData)
 
-	return contentHash, compressedHash, contentSize, finalSize, nil
+	os.Remove(path + ".idx")
+
+	return contentHash, compressedHash, contentSize, int64(len(compressedData)), nil
 }
 
 // LoadBundle loads a compressed bundle
···
 		return nil, fmt.Errorf("invalid position: %d", position)
 	}
 
-	indexPath := path + ".idx"
+	// ✅ Try multiple sources for frame index (no goto!)
+	frameOffsets, err := op.loadFrameIndex(path)
+	if err != nil {
+		// No frame index available - use legacy full scan
+		if op.logger != nil {
+			op.logger.Printf("No frame index found for %s, using legacy scan", filepath.Base(path))
+		}
+		return op.loadOperationAtPositionLegacy(path, position)
+	}
+
+	// We have frame index - use it for fast random access
+	return op.loadOperationFromFrame(path, position, frameOffsets)
+}
 
-	// 1. Try to load frame index
+// loadFrameIndex loads frame offsets and converts to absolute positions
+func (op *Operations) loadFrameIndex(path string) ([]int64, error) {
+	// Try embedded metadata first
+	meta, err := ExtractMetadataFromFile(path)
+	if err == nil && len(meta.FrameOffsets) > 0 {
+		// ✅ Convert relative offsets to absolute
+		// First, get metadata frame size by re-reading
+		file, _ := os.Open(path)
+		if file != nil {
+			defer file.Close()
+
+			// Read metadata frame to find where data starts
+			magic, data, readErr := ReadSkippableFrame(file)
+			if readErr == nil && magic == SkippableMagicMetadata {
+				// Metadata frame size = 4 (magic) + 4 (size) + len(data)
+				metadataFrameSize := int64(8 + len(data))
+
+				// Convert relative to absolute
+				absoluteOffsets := make([]int64, len(meta.FrameOffsets))
+				for i, relOffset := range meta.FrameOffsets {
+					absoluteOffsets[i] = metadataFrameSize + relOffset
+				}
+
+				return absoluteOffsets, nil
+			}
+		}
+	}
+
+	// Fallback to external .idx file
+	indexPath := path + ".idx"
 	indexData, err := os.ReadFile(indexPath)
 	if err != nil {
-		if os.IsNotExist(err) {
-			// Fallback to legacy full scan
-			if op.logger != nil {
-				op.logger.Printf("Frame index not found for %s, using legacy scan", filepath.Base(path))
-			}
-			return op.loadOperationAtPositionLegacy(path, position)
-		}
-		return nil, fmt.Errorf("could not read frame index: %w", err)
+		return nil, fmt.Errorf("no frame index available: %w", err)
 	}
 
-	var frameOffsets []int64
-	if err := json.Unmarshal(indexData, &frameOffsets); err != nil {
-		return nil, fmt.Errorf("could not parse frame index: %w", err)
+	var offsets []int64
+	if err := json.Unmarshal(indexData, &offsets); err != nil {
+		return nil, fmt.Errorf("invalid frame index: %w", err)
 	}
 
-	// 2. Calculate target frame
+	return offsets, nil
+}
+
+// loadOperationFromFrame loads operation using frame index
+func (op *Operations) loadOperationFromFrame(path string, position int, frameOffsets []int64) (*plcclient.PLCOperation, error) {
 	frameIndex := position / FrameSize
 	lineInFrame := position % FrameSize
 
···
 			position, frameIndex, len(frameOffsets)-1)
 	}
 
-	// 3. Read the specific frame from file
 	startOffset := frameOffsets[frameIndex]
 	endOffset := frameOffsets[frameIndex+1]
 	frameLength := endOffset - startOffset
 
-	if frameLength <= 0 {
-		return nil, fmt.Errorf("invalid frame length: %d", frameLength)
+	// ✅ DEBUG
+	if op.logger != nil {
+		op.logger.Printf("DEBUG: Frame %d: offset %d-%d, length %d bytes",
+			frameIndex, startOffset, endOffset, frameLength)
+	}
+
+	if frameLength <= 0 || frameLength > 10*1024*1024 {
+		return nil, fmt.Errorf("invalid frame length: %d (offsets: %d-%d)",
+			frameLength, startOffset, endOffset)
 	}
 
 	bundleFile, err := os.Open(path)
···
 	defer bundleFile.Close()
 
 	compressedFrame := make([]byte, frameLength)
-	_, err = bundleFile.ReadAt(compressedFrame, startOffset)
+	n, err := bundleFile.ReadAt(compressedFrame, startOffset)
 	if err != nil {
-		return nil, fmt.Errorf("failed to read frame %d: %w", frameIndex, err)
+		return nil, fmt.Errorf("failed to read frame %d (offset %d, length %d): %w",
+			frameIndex, startOffset, frameLength, err)
 	}
 
-	// 4. ✅ Decompress this single frame
+	if op.logger != nil {
+		op.logger.Printf("DEBUG: Read %d bytes from offset %d", n, startOffset)
+	}
+
+	// Decompress
 	decompressed, err := DecompressFrame(compressedFrame)
 	if err != nil {
+		// ✅ DEBUG: Show first few bytes to diagnose
+		if op.logger != nil {
+			preview := compressedFrame
+			if len(preview) > 16 {
+				preview = preview[:16]
+			}
+			op.logger.Printf("DEBUG: Failed frame data (first 16 bytes): % x", preview)
+		}
 		return nil, fmt.Errorf("failed to decompress frame %d: %w", frameIndex, err)
 	}
 
-	// 5. Scan the decompressed data to find the target line
+	// Scan to find the line
 	scanner := bufio.NewScanner(bytes.NewReader(decompressed))
 	lineNum := 0
 

internal/storage/storage_test.go

···
 				path := filepath.Join(tmpDir, tt.name+".jsonl.zst")
 
 				// Save
-				_, _, _, _, err := ops.SaveBundle(path, original)
+				_, _, _, _, err := ops.SaveBundle(path, original, nil)
 				if err != nil {
 					t.Fatalf("SaveBundle failed: %v", err)
 				}
···
 		operations := makeTestOperations(10000)
 		path := filepath.Join(tmpDir, "compression_test.jsonl.zst")
 
-		_, _, uncompSize, compSize, err := ops.SaveBundle(path, operations)
+		_, _, uncompSize, compSize, err := ops.SaveBundle(path, operations, nil)
 		if err != nil {
 			t.Fatalf("SaveBundle failed: %v", err)
 		}
···
 		operations := makeTestOperations(100)
 		path := filepath.Join(tmpDir, "integrity_test.jsonl.zst")
 
-		contentHash, compHash, _, _, err := ops.SaveBundle(path, operations)
+		contentHash, compHash, _, _, err := ops.SaveBundle(path, operations, nil)
 		if err != nil {
 			t.Fatalf("SaveBundle failed: %v", err)
 		}
···
 		// Create test bundle
 		operations := makeTestOperations(10000)
 		path := filepath.Join(tmpDir, "parallel_test.jsonl.zst")
-		_, _, _, _, err := ops.SaveBundle(path, operations)
+		_, _, _, _, err := ops.SaveBundle(path, operations, nil)
 		if err != nil {
 			t.Fatalf("SaveBundle failed: %v", err)
 		}
···
 		// Critical test - this is heavily used by DID lookups
 		operations := makeTestOperations(10000)
 		path := filepath.Join(tmpDir, "position_test.jsonl.zst")
-		_, _, _, _, err := ops.SaveBundle(path, operations)
+		_, _, _, _, err := ops.SaveBundle(path, operations, nil)
 		if err != nil {
 			t.Fatalf("SaveBundle failed: %v", err)
 		}
···
 	t.Run("ConcurrentHashVerification", func(t *testing.T) {
 		operations := makeTestOperations(1000)
 		path := filepath.Join(tmpDir, "verify_test.jsonl.zst")
-		_, compHash, _, _, err := ops.SaveBundle(path, operations)
+		_, compHash, _, _, err := ops.SaveBundle(path, operations, nil)
 		if err != nil {
 			t.Fatalf("SaveBundle failed: %v", err)
 		}
···
 	t.Run("TruncatedFile", func(t *testing.T) {
 		operations := makeTestOperations(100)
 		path := filepath.Join(tmpDir, "truncated.jsonl.zst")
-		ops.SaveBundle(path, operations)
+		ops.SaveBundle(path, operations, nil)
 
 		// Read and truncate
 		data, _ := os.ReadFile(path)
···
 
 		// Manually compress invalid data
 		operations := makeTestOperations(10)
-		ops.SaveBundle(path, operations) // Create valid file first
+		ops.SaveBundle(path, operations, nil) // Create valid file first
 
 		// Now corrupt it with invalid JSON
 		// This is hard to test properly since SaveBundle enforces valid data
···
 	t.Run("InvalidPosition", func(t *testing.T) {
 		operations := makeTestOperations(100)
 		path := filepath.Join(tmpDir, "position_test.jsonl.zst")
-		ops.SaveBundle(path, operations)
+		ops.SaveBundle(path, operations, nil)
 
 		// Negative position
 		_, err := ops.LoadOperationAtPosition(path, -1)
···
 	t.Run("StreamRaw", func(t *testing.T) {
 		operations := makeTestOperations(100)
 		path := filepath.Join(tmpDir, "stream_raw.jsonl.zst")
-		_, _, _, _, err := ops.SaveBundle(path, operations)
+		_, _, _, _, err := ops.SaveBundle(path, operations, nil)
 		if err != nil {
 			t.Fatalf("SaveBundle failed: %v", err)
 		}
···
 	t.Run("StreamDecompressed", func(t *testing.T) {
 		operations := makeTestOperations(100)
 		path := filepath.Join(tmpDir, "stream_decomp.jsonl.zst")
-		ops.SaveBundle(path, operations)
+		ops.SaveBundle(path, operations, nil)
 
 		reader, err := ops.StreamDecompressed(path)
 		if err != nil {
···
 	b.Run("SaveBundle", func(b *testing.B) {
 		for i := 0; i < b.N; i++ {
 			path := filepath.Join(tmpDir, fmt.Sprintf("bench_%d.jsonl.zst", i))
-			ops.SaveBundle(path, operations)
+			ops.SaveBundle(path, operations, nil)
 		}
 	})
 
 	// Create bundle for read benchmarks
 	testPath := filepath.Join(tmpDir, "bench_read.jsonl.zst")
-	ops.SaveBundle(testPath, operations)
+	ops.SaveBundle(testPath, operations, nil)
 
 	b.Run("LoadBundle", func(b *testing.B) {
 		for i := 0; i < b.N; i++ {

internal/storage/zstd.go

···
 package storage
 
 import (
+	"bytes"
 	"encoding/binary"
 	"encoding/json"
 	"fmt"
 	"io"
 	"os"
-	"time"
+	"path/filepath"
 
 	"github.com/valyala/gozstd"
 )
···
 // ============================================================================
 
 const (
-	CompressionLevel = 3
+	CompressionLevel = 2
 	FrameSize        = 100
 
-	// Skippable frame magic numbers (0x184D2A50 to 0x184D2A5F)
-	// We use 0x184D2A50 for bundle metadata
 	SkippableMagicMetadata = 0x184D2A50
 )
 
-// BundleMetadata is stored in skippable frame at start of bundle file
-type BundleMetadata struct {
-	Version      int    `json:"version"` // Metadata format version
-	BundleNumber int    `json:"bundle_number"`
-	Origin       string `json:"origin,omitempty"`
-
-	// Hashes
-	ContentHash    string `json:"content_hash"`
-	CompressedHash string `json:"compressed_hash"`
-	ParentHash     string `json:"parent_hash,omitempty"`
-
-	// Sizes
-	UncompressedSize int64 `json:"uncompressed_size"`
-	CompressedSize   int64 `json:"compressed_size"`
-
-	// Timestamps
-	StartTime time.Time `json:"start_time"`
-	EndTime   time.Time `json:"end_time"`
-	CreatedAt time.Time `json:"created_at"`
-
-	// Counts
-	OperationCount int `json:"operation_count"`
-	DIDCount       int `json:"did_count"`
-	FrameCount     int `json:"frame_count"`
-
-	// Additional info
-	Cursor string `json:"cursor,omitempty"`
-}
-
 // ============================================================================
 // SKIPPABLE FRAME FUNCTIONS
 // ============================================================================
 
 // WriteSkippableFrame writes a skippable frame with the given data
-// Returns the number of bytes written
 func WriteSkippableFrame(w io.Writer, magicNumber uint32, data []byte) (int64, error) {
-	// Skippable frame format:
-	// [4 bytes] Magic Number (0x184D2A5X)
-	// [4 bytes] Frame Size (little-endian uint32)
-	// [N bytes] Frame Data
-
 	frameSize := uint32(len(data))
 
-	// Write magic number
+	// Write magic number (little-endian)
 	if err := binary.Write(w, binary.LittleEndian, magicNumber); err != nil {
 		return 0, err
 	}
 
-	// Write frame size
+	// Write frame size (little-endian)
 	if err := binary.Write(w, binary.LittleEndian, frameSize); err != nil {
 		return 0, err
 	}
···
 	return totalBytes, nil
 }
 
-// ReadSkippableFrame reads a skippable frame from the reader
-// Returns the magic number and data, or error if not a skippable frame
+// ReadSkippableFrame with debug
 func ReadSkippableFrame(r io.Reader) (uint32, []byte, error) {
-	// Read magic number
 	var magic uint32
 	if err := binary.Read(r, binary.LittleEndian, &magic); err != nil {
-		return 0, nil, err
+		return 0, nil, fmt.Errorf("failed to read magic: %w", err)
 	}
 
-	// Verify it's a skippable frame (0x184D2A50 to 0x184D2A5F)
+	fmt.Fprintf(os.Stderr, "DEBUG: Read magic number: 0x%08X\n", magic)
+
 	if magic < 0x184D2A50 || magic > 0x184D2A5F {
-		return 0, nil, fmt.Errorf("not a skippable frame: magic=0x%08X", magic)
+		return 0, nil, fmt.Errorf("not a skippable frame: magic=0x%08X (expected 0x184D2A50-0x184D2A5F)", magic)
 	}
 
-	// Read frame size
 	var frameSize uint32
 	if err := binary.Read(r, binary.LittleEndian, &frameSize); err != nil {
-		return 0, nil, err
+		return 0, nil, fmt.Errorf("failed to read frame size: %w", err)
 	}
 
-	// Read frame data
+	fmt.Fprintf(os.Stderr, "DEBUG: Frame size: %d bytes\n", frameSize)
+
 	data := make([]byte, frameSize)
 	if _, err := io.ReadFull(r, data); err != nil {
-		return 0, nil, err
+		return 0, nil, fmt.Errorf("failed to read frame data: %w", err)
 	}
 
+	fmt.Fprintf(os.Stderr, "DEBUG: Read %d bytes of frame data\n", len(data))
+
 	return magic, data, nil
 }
 
-// WriteMetadataFrame writes bundle metadata as a skippable frame
+// WriteMetadataFrame writes bundle metadata as skippable frame (compact JSON)
 func WriteMetadataFrame(w io.Writer, meta *BundleMetadata) (int64, error) {
-	// Serialize metadata to JSON
 	jsonData, err := json.Marshal(meta)
 	if err != nil {
 		return 0, fmt.Errorf("failed to marshal metadata: %w", err)
 	}
-
-	// Write as skippable frame
 	return WriteSkippableFrame(w, SkippableMagicMetadata, jsonData)
 }
 
···
 	return &meta, nil
 }
 
-// ExtractMetadataFromFile reads just the metadata without decompressing the bundle
+// ExtractMetadataFromFile reads metadata without decompressing
 func ExtractMetadataFromFile(path string) (*BundleMetadata, error) {
 	file, err := os.Open(path)
 	if err != nil {
···
 	}
 	defer file.Close()
 
-	// Try to read skippable frame at start
+	// ✅ DEBUG: Check first bytes
+	header := make([]byte, 8)
+	if _, err := file.Read(header); err != nil {
+		return nil, fmt.Errorf("failed to read header: %w", err)
+	}
+
+	fmt.Fprintf(os.Stderr, "DEBUG: First 8 bytes: % x\n", header)
+
+	// Seek back to start
+	file.Seek(0, io.SeekStart)
+
 	meta, err := ReadMetadataFrame(file)
 	if err != nil {
 		return nil, fmt.Errorf("no metadata frame found: %w", err)
···
 	return meta, nil
 }
 
+// ExtractFrameIndexFromFile now just reads from metadata
+func ExtractFrameIndexFromFile(path string) ([]int64, error) {
+	meta, err := ExtractMetadataFromFile(path)
+	if err != nil {
+		return nil, err
+	}
+
+	if len(meta.FrameOffsets) == 0 {
+		return nil, fmt.Errorf("metadata has no frame offsets")
+	}
+
+	return meta.FrameOffsets, nil
+}
+
+// DebugFrameOffsets extracts and displays frame offset information
+func DebugFrameOffsets(path string) error {
+	meta, err := ExtractMetadataFromFile(path)
+	if err != nil {
+		return fmt.Errorf("failed to extract metadata: %w", err)
+	}
+
+	fmt.Printf("Frame Offset Debug for: %s\n\n", filepath.Base(path))
+	fmt.Printf("Metadata:\n")
+	fmt.Printf("  Bundle: %d\n", meta.BundleNumber)
+	fmt.Printf("  Frames: %d\n", meta.FrameCount)
+	fmt.Printf("  Frame size: %d ops\n", meta.FrameSize)
+	fmt.Printf("  Total ops: %d\n", meta.OperationCount)
+
+	fmt.Printf("\nFrame Offsets (%d total):\n", len(meta.FrameOffsets))
+	for i, offset := range meta.FrameOffsets {
+		if i < len(meta.FrameOffsets)-1 {
+			nextOffset := meta.FrameOffsets[i+1]
+			frameSize := nextOffset - offset
+			fmt.Printf("  Frame %3d: offset %10d, size %10d bytes\n", i, offset, frameSize)
+		} else {
+			fmt.Printf("  End mark: offset %10d\n", offset)
+		}
+	}
+
+	// Try to verify first frame
+	fmt.Printf("\nVerifying first frame...\n")
+	file, err := os.Open(path)
+	if err != nil {
+		return err
+	}
+	defer file.Close()
+
+	if len(meta.FrameOffsets) < 2 {
+		return fmt.Errorf("not enough frame offsets")
+	}
+
+	startOffset := meta.FrameOffsets[0]
+	endOffset := meta.FrameOffsets[1]
+	frameLength := endOffset - startOffset
+
+	fmt.Printf("  Start: %d, End: %d, Length: %d\n", startOffset, endOffset, frameLength)
+
+	compressedFrame := make([]byte, frameLength)
+	_, err = file.ReadAt(compressedFrame, startOffset)
+	if err != nil {
+		return fmt.Errorf("failed to read: %w", err)
+	}
+
+	decompressed, err := DecompressFrame(compressedFrame)
+	if err != nil {
+		return fmt.Errorf("failed to decompress: %w", err)
+	}
+
+	fmt.Printf("  ✓ Decompressed: %d bytes\n", len(decompressed))
+
+	// Count lines
+	lines := bytes.Count(decompressed, []byte("\n"))
+	fmt.Printf("  ✓ Lines: %d\n", lines)
+
+	return nil
+}
+
 // ============================================================================
 // COMPRESSION/DECOMPRESSION
 // ============================================================================
 
-// CompressFrame compresses a single chunk of data into a zstd frame
 func CompressFrame(data []byte) ([]byte, error) {
 	compressed := gozstd.Compress(nil, data)
 	return compressed, nil
 }
 
-// DecompressAll decompresses all frames in the compressed data
 func DecompressAll(compressed []byte) ([]byte, error) {
 	decompressed, err := gozstd.Decompress(nil, compressed)
 	if err != nil {
···
 	return decompressed, nil
 }
 
-// DecompressFrame decompresses a single frame
 func DecompressFrame(compressedFrame []byte) ([]byte, error) {
 	return gozstd.Decompress(nil, compressedFrame)
 }
 
-// NewStreamingReader creates a streaming decompressor
 func NewStreamingReader(r io.Reader) (StreamReader, error) {
 	reader := gozstd.NewReader(r)
 	return &gozstdReader{reader: reader}, nil
 }
 
-// NewStreamingWriter creates a streaming compressor at default level
 func NewStreamingWriter(w io.Writer) (StreamWriter, error) {
 	writer := gozstd.NewWriterLevel(w, CompressionLevel)
 	return &gozstdWriter{writer: writer}, nil

server/server_test.go

···
 		path := filepath.Join(tmpDir, fmt.Sprintf("%06d.jsonl.zst", i))
 		ops := makeMinimalTestOperations(10000, i*10000) // Unique ops per bundle
 
-		contentHash, compHash, uncompSize, compSize, err := storageOps.SaveBundle(path, ops)
+		contentHash, compHash, uncompSize, compSize, err := storageOps.SaveBundle(path, ops, nil)
 		if err != nil {
 			t.Fatalf("failed to save test bundle %d: %v", i, err)
 		}