fix(storage): move BatchCreateOptions to storage package for backend-agnostic batch creation

Fixes the leaky abstraction where molecules and importer packages directly used
sqlite.BatchCreateOptions and type-asserted to *sqlite.SQLiteStorage.

Changes:
- Add storage.BatchCreateOptions and storage.OrphanHandling as backend-agnostic types
- Add CreateIssuesWithFullOptions to Storage interface
- Implement for SQLite, Dolt, and Memory backends
- Update molecules.go to use Storage interface method instead of sqlite type assertion
- Update importer.go to use storage types instead of sqlite-specific interface
- Update cook.go to use storage interface method
- Add deprecated aliases in sqlite package for backward compatibility

This enables batch create optimizations for all backends including Dolt.

Closes: bd-nrcp

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Executed-By: beads/jasper
Rig: beads
Role: polecat

Author: steveyegge

cmd/bd/cook.go

@@ -11,7 +11,6 @@ import (
 	"github.com/spf13/cobra"
 	"github.com/steveyegge/beads/internal/formula"
 	"github.com/steveyegge/beads/internal/storage"
-	"github.com/steveyegge/beads/internal/storage/sqlite"
 	"github.com/steveyegge/beads/internal/types"
 	"github.com/steveyegge/beads/internal/ui"
 )
@@ -783,12 +782,6 @@ func cookFormula(ctx context.Context, s storage.Storage, f *formula.Formula, pro
 		return nil, fmt.Errorf("no database connection")
 	}
 
-	// Check for SQLite store (needed for batch create with skip prefix)
-	sqliteStore, ok := s.(*sqlite.SQLiteStorage)
-	if !ok {
-		return nil, fmt.Errorf("cook requires SQLite storage")
-	}
-
 	// Map step ID -> created issue ID
 	idMapping := make(map[string]string)
 
@@ -838,10 +831,11 @@ func cookFormula(ctx context.Context, s storage.Storage, f *formula.Formula, pro
 	}
 
 	// Create all issues using batch with skip prefix validation
-	opts := sqlite.BatchCreateOptions{
+	opts := storage.BatchCreateOptions{
 		SkipPrefixValidation: true, // Molecules use mol-* prefix
+		OrphanHandling:       storage.OrphanAllow,
 	}
-	if err := sqliteStore.CreateIssuesWithFullOptions(ctx, issues, actor, opts); err != nil {
+	if err := s.CreateIssuesWithFullOptions(ctx, issues, actor, opts); err != nil {
 		return nil, fmt.Errorf("failed to create issues: %w", err)
 	}
 

cmd/bd/deletion_tracking_test.go

@@ -8,6 +8,7 @@ import (
 	"testing"
 
 	"github.com/steveyegge/beads/internal/config"
+	"github.com/steveyegge/beads/internal/storage"
 	"github.com/steveyegge/beads/internal/storage/sqlite"
 	"github.com/steveyegge/beads/internal/types"
 )
@@ -908,7 +909,7 @@ func TestMultiRepoFlushPrefixFiltering(t *testing.T) {
 
 	// Use batch create with SkipPrefixValidation to simulate multi-repo hydration
 	// (in real multi-repo mode, issues from other repos are imported with prefix validation skipped)
-	if err := store.CreateIssuesWithFullOptions(ctx, []*types.Issue{primaryIssue, additionalIssue}, "test", sqlite.BatchCreateOptions{SkipPrefixValidation: true}); err != nil {
+	if err := store.CreateIssuesWithFullOptions(ctx, []*types.Issue{primaryIssue, additionalIssue}, "test", storage.BatchCreateOptions{SkipPrefixValidation: true, OrphanHandling: storage.OrphanAllow}); err != nil {
 		t.Fatalf("Failed to batch create issues: %v", err)
 	}
 

internal/importer/importer.go

@@ -15,24 +15,21 @@ import (
 	"github.com/steveyegge/beads/internal/linear"
 	"github.com/steveyegge/beads/internal/routing"
 	"github.com/steveyegge/beads/internal/storage"
-	"github.com/steveyegge/beads/internal/storage/sqlite"
 	"github.com/steveyegge/beads/internal/types"
 	"github.com/steveyegge/beads/internal/utils"
 )
 
-// OrphanHandling defines how to handle hierarchical child issues whose parents are missing.
-// This mirrors the string values historically used by the SQLite backend config.
-type OrphanHandling string
+// OrphanHandling is an alias for storage.OrphanHandling for backward compatibility.
+// Deprecated: Use storage.OrphanHandling directly.
+type OrphanHandling = storage.OrphanHandling
 
+// Orphan handling constants - aliases for storage package constants.
+// Deprecated: Use storage.OrphanStrict, etc. directly.
 const (
-	// OrphanStrict fails import on missing parent (safest)
-	OrphanStrict OrphanHandling = "strict"
-	// OrphanResurrect auto-resurrects missing parents from JSONL history
-	OrphanResurrect OrphanHandling = "resurrect"
-	// OrphanSkip skips orphaned issues with warning
-	OrphanSkip OrphanHandling = "skip"
-	// OrphanAllow imports orphans without validation (default, works around bugs)
-	OrphanAllow OrphanHandling = "allow"
+	OrphanStrict    = storage.OrphanStrict
+	OrphanResurrect = storage.OrphanResurrect
+	OrphanSkip      = storage.OrphanSkip
+	OrphanAllow     = storage.OrphanAllow
 )
 
 // Options contains import configuration
@@ -908,25 +905,13 @@ func upsertIssues(ctx context.Context, store storage.Storage, issues []*types.Is
 				}
 			}
 			if len(batchForDepth) > 0 {
-				// Prefer a backend-specific import/batch API when available, so we can honor
-				// options like SkipPrefixValidation (multi-repo mode) without requiring the
-				// entire importer to be SQLite-specific.
-				type importBatchCreator interface {
-					CreateIssuesWithFullOptions(ctx context.Context, issues []*types.Issue, actor string, opts sqlite.BatchCreateOptions) error
+				// Use the backend-agnostic batch creation API with full options.
+				batchOpts := storage.BatchCreateOptions{
+					OrphanHandling:       opts.OrphanHandling,
+					SkipPrefixValidation: opts.SkipPrefixValidation,
 				}
-				if bc, ok := store.(importBatchCreator); ok {
-					batchOpts := sqlite.BatchCreateOptions{
-						OrphanHandling:       sqlite.OrphanHandling(opts.OrphanHandling),
-						SkipPrefixValidation: opts.SkipPrefixValidation,
-					}
-					if err := bc.CreateIssuesWithFullOptions(ctx, batchForDepth, "import", batchOpts); err != nil {
-						return fmt.Errorf("error creating depth-%d issues: %w", depth, err)
-					}
-				} else {
-					// Generic fallback. OrphanSkip and OrphanStrict are enforced above.
-					if err := store.CreateIssues(ctx, batchForDepth, "import"); err != nil {
-						return fmt.Errorf("error creating depth-%d issues: %w", depth, err)
-					}
+				if err := store.CreateIssuesWithFullOptions(ctx, batchForDepth, "import", batchOpts); err != nil {
+					return fmt.Errorf("error creating depth-%d issues: %w", depth, err)
 				}
 				result.Created += len(batchForDepth)
 			}

internal/molecules/molecules.go

@@ -31,7 +31,6 @@ import (
 
 	"github.com/steveyegge/beads/internal/debug"
 	"github.com/steveyegge/beads/internal/storage"
-	"github.com/steveyegge/beads/internal/storage/sqlite"
 	"github.com/steveyegge/beads/internal/types"
 )
 
@@ -149,27 +148,14 @@ func (l *Loader) loadMolecules(ctx context.Context, molecules []*types.Issue) (i
 
 	// Use batch creation with prefix validation skipped.
 	// Molecules have their own ID namespace (mol-*) independent of project prefix.
-	if sqliteStore, ok := l.store.(*sqlite.SQLiteStorage); ok {
-		opts := sqlite.BatchCreateOptions{
-			SkipPrefixValidation: true, // Molecules use their own prefix
-		}
-		if err := sqliteStore.CreateIssuesWithFullOptions(ctx, newMolecules, "molecules-loader", opts); err != nil {
-			return 0, fmt.Errorf("batch create molecules: %w", err)
-		}
-		return len(newMolecules), nil
+	opts := storage.BatchCreateOptions{
+		SkipPrefixValidation: true, // Molecules use their own prefix
+		OrphanHandling:       storage.OrphanAllow,
 	}
-
-	// Fallback for non-SQLite stores (e.g., memory storage in tests)
-	loaded := 0
-	for _, mol := range newMolecules {
-		if err := l.store.CreateIssue(ctx, mol, "molecules-loader"); err != nil {
-			debug.Logf("failed to load molecule %s: %v", mol.ID, err)
-			continue
-		}
-		loaded++
+	if err := l.store.CreateIssuesWithFullOptions(ctx, newMolecules, "molecules-loader", opts); err != nil {
+		return 0, fmt.Errorf("batch create molecules: %w", err)
 	}
-
-	return loaded, nil
+	return len(newMolecules), nil
 }
 
 // loadMoleculesFromFile loads molecules from a JSONL file.

internal/molecules/molecules_test.go

@@ -6,6 +6,7 @@ import (
 	"path/filepath"
 	"testing"
 
+	"github.com/steveyegge/beads/internal/storage"
 	"github.com/steveyegge/beads/internal/storage/sqlite"
 	"github.com/steveyegge/beads/internal/types"
 )
@@ -168,7 +169,7 @@ func TestLoader_SkipExistingMolecules(t *testing.T) {
 		Status:     types.StatusOpen,
 		IsTemplate: true,
 	}
-	opts := sqlite.BatchCreateOptions{SkipPrefixValidation: true}
+	opts := storage.BatchCreateOptions{SkipPrefixValidation: true, OrphanHandling: storage.OrphanAllow}
 	if err := store.CreateIssuesWithFullOptions(ctx, []*types.Issue{existingMol}, "test", opts); err != nil {
 		t.Fatalf("Failed to create existing molecule: %v", err)
 	}

internal/storage/batch.go

@@ -0,0 +1,25 @@
+// Package storage defines the interface for issue storage backends.
+package storage
+
+// OrphanHandling specifies how to handle issues with missing parent references.
+type OrphanHandling string
+
+const (
+	// OrphanStrict fails import on missing parent (safest)
+	OrphanStrict OrphanHandling = "strict"
+	// OrphanResurrect auto-resurrects missing parents from JSONL history
+	OrphanResurrect OrphanHandling = "resurrect"
+	// OrphanSkip skips orphaned issues with warning
+	OrphanSkip OrphanHandling = "skip"
+	// OrphanAllow imports orphans without validation (default, works around bugs)
+	OrphanAllow OrphanHandling = "allow"
+)
+
+// BatchCreateOptions contains options for batch issue creation.
+// This is a backend-agnostic type that can be used by any storage implementation.
+type BatchCreateOptions struct {
+	// OrphanHandling specifies how to handle issues with missing parent references
+	OrphanHandling OrphanHandling
+	// SkipPrefixValidation skips prefix validation for existing IDs (used during import)
+	SkipPrefixValidation bool
+}

internal/storage/dolt/issues.go

@@ -9,6 +9,7 @@ import (
 	"time"
 
 	"github.com/steveyegge/beads/internal/idgen"
+	"github.com/steveyegge/beads/internal/storage"
 	"github.com/steveyegge/beads/internal/types"
 )
 
@@ -116,6 +117,16 @@ func (s *DoltStore) CreateIssue(ctx context.Context, issue *types.Issue, actor s
 
 // CreateIssues creates multiple issues in a single transaction
 func (s *DoltStore) CreateIssues(ctx context.Context, issues []*types.Issue, actor string) error {
+	return s.CreateIssuesWithFullOptions(ctx, issues, actor, storage.BatchCreateOptions{
+		OrphanHandling:       storage.OrphanAllow,
+		SkipPrefixValidation: false,
+	})
+}
+
+// CreateIssuesWithFullOptions creates multiple issues with full options control.
+// This is the backend-agnostic batch creation method that supports orphan handling
+// and prefix validation options.
+func (s *DoltStore) CreateIssuesWithFullOptions(ctx context.Context, issues []*types.Issue, actor string, opts storage.BatchCreateOptions) error {
 	if len(issues) == 0 {
 		return nil
 	}
@@ -136,6 +147,15 @@ func (s *DoltStore) CreateIssues(ctx context.Context, issues []*types.Issue, act
 	}
 	defer func() { _ = tx.Rollback() }()
 
+	// Get prefix from config for validation
+	var configPrefix string
+	err = tx.QueryRowContext(ctx, "SELECT value FROM config WHERE `key` = ?", "issue_prefix").Scan(&configPrefix)
+	if err == sql.ErrNoRows || configPrefix == "" {
+		return fmt.Errorf("database not initialized: issue_prefix config is missing (run 'bd init --prefix <prefix>' first)")
+	} else if err != nil {
+		return fmt.Errorf("failed to get config: %w", err)
+	}
+
 	for _, issue := range issues {
 		now := time.Now().UTC()
 		if issue.CreatedAt.IsZero() {
@@ -174,6 +194,35 @@ func (s *DoltStore) CreateIssues(ctx context.Context, issues []*types.Issue, act
 			issue.ContentHash = issue.ComputeContentHash()
 		}
 
+		// Validate prefix if not skipped (for imports with different prefixes)
+		if !opts.SkipPrefixValidation && issue.ID != "" {
+			if err := validateIssueIDPrefix(issue.ID, configPrefix); err != nil {
+				return fmt.Errorf("prefix validation failed for %s: %w", issue.ID, err)
+			}
+		}
+
+		// Handle orphan checking for hierarchical IDs
+		if issue.ID != "" {
+			if parentID, _, ok := parseHierarchicalID(issue.ID); ok {
+				var parentCount int
+				err := tx.QueryRowContext(ctx, `SELECT COUNT(*) FROM issues WHERE id = ?`, parentID).Scan(&parentCount)
+				if err != nil {
+					return fmt.Errorf("failed to check parent existence: %w", err)
+				}
+				if parentCount == 0 {
+					switch opts.OrphanHandling {
+					case storage.OrphanStrict:
+						return fmt.Errorf("parent issue %s does not exist (strict mode)", parentID)
+					case storage.OrphanSkip:
+						// Skip this issue
+						continue
+					case storage.OrphanResurrect, storage.OrphanAllow:
+						// Allow orphan - continue with insert
+					}
+				}
+			}
+		}
+
 		if err := insertIssue(ctx, tx, issue); err != nil {
 			return fmt.Errorf("failed to insert issue %s: %w", issue.ID, err)
 		}
@@ -188,6 +237,35 @@ func (s *DoltStore) CreateIssues(ctx context.Context, issues []*types.Issue, act
 	return tx.Commit()
 }
 
+// validateIssueIDPrefix validates that the issue ID has the correct prefix
+func validateIssueIDPrefix(id, prefix string) error {
+	if !strings.HasPrefix(id, prefix+"-") {
+		return fmt.Errorf("issue ID %s does not match configured prefix %s", id, prefix)
+	}
+	return nil
+}
+
+// parseHierarchicalID checks if an ID is hierarchical (e.g., "bd-abc.1") and returns the parent ID and child number
+func parseHierarchicalID(id string) (parentID string, childNum int, ok bool) {
+	// Find the last dot that separates parent from child number
+	lastDot := strings.LastIndex(id, ".")
+	if lastDot == -1 {
+		return "", 0, false
+	}
+
+	parentID = id[:lastDot]
+	suffix := id[lastDot+1:]
+
+	// Parse child number
+	var num int
+	_, err := fmt.Sscanf(suffix, "%d", &num)
+	if err != nil {
+		return "", 0, false
+	}
+
+	return parentID, num, true
+}
+
 // GetIssue retrieves an issue by ID
 func (s *DoltStore) GetIssue(ctx context.Context, id string) (*types.Issue, error) {
 	s.mu.RLock()

internal/storage/memory/memory.go

@@ -322,6 +322,15 @@ func (m *MemoryStorage) CreateIssues(ctx context.Context, issues []*types.Issue,
 	return nil
 }
 
+// CreateIssuesWithFullOptions creates multiple issues with full options control.
+// For MemoryStorage, this delegates to CreateIssues as the options (orphan handling,
+// prefix validation) are primarily relevant for persistent storage backends.
+func (m *MemoryStorage) CreateIssuesWithFullOptions(ctx context.Context, issues []*types.Issue, actor string, opts storage.BatchCreateOptions) error {
+	// MemoryStorage doesn't enforce prefix validation or orphan handling
+	// as it's primarily used for testing and no-db mode
+	return m.CreateIssues(ctx, issues, actor)
+}
+
 // GetIssue retrieves an issue by ID
 func (m *MemoryStorage) GetIssue(ctx context.Context, id string) (*types.Issue, error) {
 	m.mu.RLock()

internal/storage/sqlite/batch_ops.go

@@ -7,6 +7,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/steveyegge/beads/internal/storage"
 	"github.com/steveyegge/beads/internal/types"
 )
 
@@ -231,11 +232,9 @@ func (s *SQLiteStorage) CreateIssues(ctx context.Context, issues []*types.Issue,
 	return s.CreateIssuesWithOptions(ctx, issues, actor, OrphanResurrect)
 }
 
-// BatchCreateOptions contains options for batch issue creation
-type BatchCreateOptions struct {
-	OrphanHandling       OrphanHandling // How to handle missing parent issues
-	SkipPrefixValidation bool           // Skip prefix validation for existing IDs (used during import)
-}
+// BatchCreateOptions is an alias for storage.BatchCreateOptions for backward compatibility.
+// Deprecated: Use storage.BatchCreateOptions directly.
+type BatchCreateOptions = storage.BatchCreateOptions
 
 // CreateIssuesWithOptions creates multiple issues with configurable orphan handling
 func (s *SQLiteStorage) CreateIssuesWithOptions(ctx context.Context, issues []*types.Issue, actor string, orphanHandling OrphanHandling) error {

internal/storage/sqlite/config.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 
 	"github.com/steveyegge/beads/internal/config"
+	"github.com/steveyegge/beads/internal/storage"
 )
 
 // SetConfig sets a configuration value
@@ -74,14 +75,17 @@ func (s *SQLiteStorage) DeleteConfig(ctx context.Context, key string) error {
 	return wrapDBError("delete config", err)
 }
 
-// OrphanHandling defines how to handle orphan issues during import
-type OrphanHandling string
+// OrphanHandling is an alias for storage.OrphanHandling for backward compatibility.
+// Deprecated: Use storage.OrphanHandling directly.
+type OrphanHandling = storage.OrphanHandling
 
+// Orphan handling constants - aliases for storage package constants.
+// Deprecated: Use storage.OrphanStrict, etc. directly.
 const (
-	OrphanStrict    OrphanHandling = "strict"     // Reject imports with orphans
-	OrphanResurrect OrphanHandling = "resurrect"  // Auto-resurrect parents from JSONL
-	OrphanSkip      OrphanHandling = "skip"       // Skip orphans silently
-	OrphanAllow     OrphanHandling = "allow"      // Allow orphans (default)
+	OrphanStrict    = storage.OrphanStrict    // Reject imports with orphans
+	OrphanResurrect = storage.OrphanResurrect // Auto-resurrect parents from JSONL
+	OrphanSkip      = storage.OrphanSkip      // Skip orphans silently
+	OrphanAllow     = storage.OrphanAllow     // Allow orphans (default)
 )
 
 // GetOrphanHandling gets the import.orphan_handling config value