feat(storage): add VersionedStorage interface with history/diff/branch operations

Extends Storage interface with Dolt-specific version control capabilities:

- New VersionedStorage interface in storage/versioned.go with:
  - History queries: History(), AsOf(), Diff()
  - Branch operations: Branch(), Merge(), CurrentBranch(), ListBranches()
  - Commit operations: Commit(), GetCurrentCommit()
  - Conflict resolution: GetConflicts(), ResolveConflicts()
  - Helper types: HistoryEntry, DiffEntry, Conflict

- DoltStore implements VersionedStorage interface

- New CLI commands:
  - bd history <id> - Show issue version history
  - bd diff <from> <to> - Show changes between commits/branches
  - bd branch [name] - List or create branches
  - bd vc merge <branch> - Merge branch to current
  - bd vc commit -m <msg> - Create a commit
  - bd vc status - Show current branch/commit

- Added --as-of flag to bd show for time-travel queries

- IsVersioned() helper for graceful SQLite backend detection

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

internal/storage/dolt/history.go

@@ -288,8 +288,9 @@ type IssueDiff struct {
 	ToDescription   string
 }
 
-// GetConflicts returns any merge conflicts in the current state
-func (s *DoltStore) GetConflicts(ctx context.Context) ([]*Conflict, error) {
+// GetInternalConflicts returns any merge conflicts in the current state (internal format).
+// For the public interface, use GetConflicts which returns storage.Conflict.
+func (s *DoltStore) GetInternalConflicts(ctx context.Context) ([]*TableConflict, error) {
 	rows, err := s.db.QueryContext(ctx, `
 		SELECT table_name, num_conflicts FROM dolt_conflicts
 	`)
@@ -298,9 +299,9 @@ func (s *DoltStore) GetConflicts(ctx context.Context) ([]*Conflict, error) {
 	}
 	defer rows.Close()
 
-	var conflicts []*Conflict
+	var conflicts []*TableConflict
 	for rows.Next() {
-		var c Conflict
+		var c TableConflict
 		if err := rows.Scan(&c.TableName, &c.NumConflicts); err != nil {
 			return nil, fmt.Errorf("failed to scan conflict: %w", err)
 		}
@@ -310,8 +311,8 @@ func (s *DoltStore) GetConflicts(ctx context.Context) ([]*Conflict, error) {
 	return conflicts, rows.Err()
 }
 
-// Conflict represents a merge conflict
-type Conflict struct {
+// TableConflict represents a Dolt table-level merge conflict (internal representation).
+type TableConflict struct {
 	TableName    string
 	NumConflicts int
 }

internal/storage/dolt/store.go

@@ -28,6 +28,8 @@ import (
 
 	// Import Dolt driver
 	_ "github.com/dolthub/driver"
+
+	"github.com/steveyegge/beads/internal/storage"
 )
 
 // DoltStore implements the Storage interface using Dolt
@@ -342,13 +344,19 @@ func (s *DoltStore) Checkout(ctx context.Context, branch string) error {
 	return nil
 }
 
-// Merge merges the specified branch into the current branch
-func (s *DoltStore) Merge(ctx context.Context, branch string) error {
+// Merge merges the specified branch into the current branch.
+// Returns any merge conflicts if present. Implements storage.VersionedStorage.
+func (s *DoltStore) Merge(ctx context.Context, branch string) ([]storage.Conflict, error) {
 	_, err := s.db.ExecContext(ctx, "CALL DOLT_MERGE(?)", branch)
 	if err != nil {
-		return fmt.Errorf("failed to merge branch %s: %w", branch, err)
+		// Check if the error is due to conflicts
+		conflicts, conflictErr := s.GetConflicts(ctx)
+		if conflictErr == nil && len(conflicts) > 0 {
+			return conflicts, nil
+		}
+		return nil, fmt.Errorf("failed to merge branch %s: %w", branch, err)
 	}
-	return nil
+	return nil, nil
 }
 
 // CurrentBranch returns the current branch name

internal/storage/dolt/versioned.go

@@ -0,0 +1,188 @@
+package dolt
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/steveyegge/beads/internal/storage"
+	"github.com/steveyegge/beads/internal/types"
+)
+
+// Ensure DoltStore implements VersionedStorage at compile time.
+var _ storage.VersionedStorage = (*DoltStore)(nil)
+
+// History returns the complete version history for an issue.
+// Implements storage.VersionedStorage.
+func (s *DoltStore) History(ctx context.Context, issueID string) ([]*storage.HistoryEntry, error) {
+	internal, err := s.GetIssueHistory(ctx, issueID)
+	if err != nil {
+		return nil, err
+	}
+
+	// Convert internal representation to interface type
+	entries := make([]*storage.HistoryEntry, len(internal))
+	for i, h := range internal {
+		entries[i] = &storage.HistoryEntry{
+			CommitHash: h.CommitHash,
+			Committer:  h.Committer,
+			CommitDate: h.CommitDate,
+			Issue:      h.Issue,
+		}
+	}
+	return entries, nil
+}
+
+// AsOf returns the state of an issue at a specific commit hash or branch ref.
+// Implements storage.VersionedStorage.
+func (s *DoltStore) AsOf(ctx context.Context, issueID string, ref string) (*types.Issue, error) {
+	return s.GetIssueAsOf(ctx, issueID, ref)
+}
+
+// Diff returns changes between two commits/branches.
+// Implements storage.VersionedStorage.
+func (s *DoltStore) Diff(ctx context.Context, fromRef, toRef string) ([]*storage.DiffEntry, error) {
+	// Validate refs to prevent SQL injection
+	if err := validateRef(fromRef); err != nil {
+		return nil, fmt.Errorf("invalid fromRef: %w", err)
+	}
+	if err := validateRef(toRef); err != nil {
+		return nil, fmt.Errorf("invalid toRef: %w", err)
+	}
+
+	// Query issue-level diffs directly
+	// Note: refs are validated above
+	// nolint:gosec // G201: refs validated by validateRef()
+	query := fmt.Sprintf(`
+		SELECT
+			COALESCE(from_id, '') as from_id,
+			COALESCE(to_id, '') as to_id,
+			diff_type,
+			from_title, to_title,
+			from_description, to_description,
+			from_status, to_status,
+			from_priority, to_priority
+		FROM dolt_diff_issues('%s', '%s')
+	`, fromRef, toRef)
+
+	rows, err := s.db.QueryContext(ctx, query)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get diff: %w", err)
+	}
+	defer rows.Close()
+
+	var entries []*storage.DiffEntry
+	for rows.Next() {
+		var fromID, toID, diffType string
+		var fromTitle, toTitle, fromDesc, toDesc, fromStatus, toStatus *string
+		var fromPriority, toPriority *int
+
+		if err := rows.Scan(&fromID, &toID, &diffType,
+			&fromTitle, &toTitle,
+			&fromDesc, &toDesc,
+			&fromStatus, &toStatus,
+			&fromPriority, &toPriority); err != nil {
+			return nil, fmt.Errorf("failed to scan diff: %w", err)
+		}
+
+		entry := &storage.DiffEntry{
+			DiffType: diffType,
+		}
+
+		// Determine issue ID (use to_id for added, from_id for removed, either for modified)
+		if toID != "" {
+			entry.IssueID = toID
+		} else {
+			entry.IssueID = fromID
+		}
+
+		// Build old value for modified/removed
+		if diffType != "added" && fromID != "" {
+			entry.OldValue = &types.Issue{
+				ID: fromID,
+			}
+			if fromTitle != nil {
+				entry.OldValue.Title = *fromTitle
+			}
+			if fromDesc != nil {
+				entry.OldValue.Description = *fromDesc
+			}
+			if fromStatus != nil {
+				entry.OldValue.Status = types.Status(*fromStatus)
+			}
+			if fromPriority != nil {
+				entry.OldValue.Priority = *fromPriority
+			}
+		}
+
+		// Build new value for modified/added
+		if diffType != "removed" && toID != "" {
+			entry.NewValue = &types.Issue{
+				ID: toID,
+			}
+			if toTitle != nil {
+				entry.NewValue.Title = *toTitle
+			}
+			if toDesc != nil {
+				entry.NewValue.Description = *toDesc
+			}
+			if toStatus != nil {
+				entry.NewValue.Status = types.Status(*toStatus)
+			}
+			if toPriority != nil {
+				entry.NewValue.Priority = *toPriority
+			}
+		}
+
+		entries = append(entries, entry)
+	}
+
+	return entries, rows.Err()
+}
+
+// ListBranches returns the names of all branches.
+// Implements storage.VersionedStorage.
+func (s *DoltStore) ListBranches(ctx context.Context) ([]string, error) {
+	rows, err := s.db.QueryContext(ctx, "SELECT name FROM dolt_branches ORDER BY name")
+	if err != nil {
+		return nil, fmt.Errorf("failed to list branches: %w", err)
+	}
+	defer rows.Close()
+
+	var branches []string
+	for rows.Next() {
+		var name string
+		if err := rows.Scan(&name); err != nil {
+			return nil, fmt.Errorf("failed to scan branch: %w", err)
+		}
+		branches = append(branches, name)
+	}
+	return branches, rows.Err()
+}
+
+// GetCurrentCommit returns the hash of the current HEAD commit.
+// Implements storage.VersionedStorage.
+func (s *DoltStore) GetCurrentCommit(ctx context.Context) (string, error) {
+	var hash string
+	err := s.db.QueryRowContext(ctx, "SELECT DOLT_HASHOF('HEAD')").Scan(&hash)
+	if err != nil {
+		return "", fmt.Errorf("failed to get current commit: %w", err)
+	}
+	return hash, nil
+}
+
+// GetConflicts returns any merge conflicts in the current state.
+// Implements storage.VersionedStorage.
+func (s *DoltStore) GetConflicts(ctx context.Context) ([]storage.Conflict, error) {
+	internal, err := s.GetInternalConflicts(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	conflicts := make([]storage.Conflict, 0, len(internal))
+	for _, c := range internal {
+		conflicts = append(conflicts, storage.Conflict{
+			Field: c.TableName,
+		})
+	}
+	return conflicts, nil
+}

internal/storage/dolt/versioned_test.go

@@ -0,0 +1,24 @@
+package dolt
+
+import (
+	"testing"
+
+	"github.com/steveyegge/beads/internal/storage"
+)
+
+// TestDoltStoreImplementsVersionedStorage verifies DoltStore implements VersionedStorage.
+// This is a compile-time check.
+func TestDoltStoreImplementsVersionedStorage(t *testing.T) {
+	// The var _ declaration in versioned.go already ensures this at compile time.
+	// This test just documents the expectation.
+
+	var _ storage.VersionedStorage = (*DoltStore)(nil)
+}
+
+// TestVersionedStorageMethodsExist ensures all required methods are defined.
+// This is mostly a documentation test since Go's type system enforces this.
+func TestVersionedStorageMethodsExist(t *testing.T) {
+	// If DoltStore doesn't implement all VersionedStorage methods,
+	// this file won't compile. This test exists for documentation.
+	t.Log("DoltStore implements all VersionedStorage methods")
+}

internal/storage/versioned.go

@@ -0,0 +1,119 @@
+// Package storage defines the interface for issue storage backends.
+package storage
+
+import (
+	"context"
+	"time"
+
+	"github.com/steveyegge/beads/internal/types"
+)
+
+// VersionedStorage extends Storage with version control capabilities.
+// This interface is implemented by storage backends that support history,
+// branching, and merging (e.g., Dolt).
+//
+// Not all storage backends support versioning. Use IsVersioned() to check
+// if a storage instance supports these operations before calling them.
+type VersionedStorage interface {
+	Storage // Embed base interface
+
+	// History queries
+
+	// History returns the complete version history for an issue.
+	// Results are ordered by commit date, most recent first.
+	History(ctx context.Context, issueID string) ([]*HistoryEntry, error)
+
+	// AsOf returns the state of an issue at a specific commit hash or branch ref.
+	// Returns nil if the issue didn't exist at that point in time.
+	AsOf(ctx context.Context, issueID string, ref string) (*types.Issue, error)
+
+	// Diff returns changes between two commits/branches.
+	// Shows which issues were added, modified, or removed.
+	Diff(ctx context.Context, fromRef, toRef string) ([]*DiffEntry, error)
+
+	// Branch operations
+
+	// Branch creates a new branch from the current state.
+	Branch(ctx context.Context, name string) error
+
+	// Merge merges the specified branch into the current branch.
+	// Returns a list of conflicts if any exist.
+	Merge(ctx context.Context, branch string) ([]Conflict, error)
+
+	// CurrentBranch returns the name of the currently active branch.
+	CurrentBranch(ctx context.Context) (string, error)
+
+	// ListBranches returns the names of all branches.
+	ListBranches(ctx context.Context) ([]string, error)
+
+	// Commit operations
+
+	// Commit creates a new commit with all staged changes.
+	Commit(ctx context.Context, message string) error
+
+	// GetCurrentCommit returns the hash of the current HEAD commit.
+	GetCurrentCommit(ctx context.Context) (string, error)
+
+	// Conflict resolution
+
+	// GetConflicts returns any merge conflicts in the current state.
+	GetConflicts(ctx context.Context) ([]Conflict, error)
+
+	// ResolveConflicts resolves conflicts using the specified strategy.
+	// Strategy must be "ours" or "theirs".
+	ResolveConflicts(ctx context.Context, table string, strategy string) error
+}
+
+// HistoryEntry represents an issue at a specific point in history.
+type HistoryEntry struct {
+	CommitHash string       // The commit hash at this point
+	Committer  string       // Who made the commit
+	CommitDate time.Time    // When the commit was made
+	Issue      *types.Issue // The issue state at that commit
+}
+
+// DiffEntry represents a change between two commits.
+type DiffEntry struct {
+	IssueID  string       // The ID of the affected issue
+	DiffType string       // "added", "modified", or "removed"
+	OldValue *types.Issue // State before (nil for "added")
+	NewValue *types.Issue // State after (nil for "removed")
+}
+
+// Conflict represents a merge conflict.
+type Conflict struct {
+	IssueID     string      // The ID of the conflicting issue
+	Field       string      // Which field has the conflict (empty for table-level)
+	OursValue   interface{} // Value on current branch
+	TheirsValue interface{} // Value on merged branch
+}
+
+// IsVersioned checks if a storage instance supports version control operations.
+// Returns true if the storage implements VersionedStorage.
+//
+// Example usage:
+//
+//	if !storage.IsVersioned(store) {
+//	    return fmt.Errorf("history requires Dolt backend")
+//	}
+//	vs := store.(storage.VersionedStorage)
+//	history, err := vs.History(ctx, issueID)
+func IsVersioned(s Storage) bool {
+	_, ok := s.(VersionedStorage)
+	return ok
+}
+
+// AsVersioned attempts to cast a Storage to VersionedStorage.
+// Returns the VersionedStorage and true if successful, nil and false otherwise.
+//
+// Example usage:
+//
+//	vs, ok := storage.AsVersioned(store)
+//	if !ok {
+//	    return fmt.Errorf("history requires Dolt backend")
+//	}
+//	history, err := vs.History(ctx, issueID)
+func AsVersioned(s Storage) (VersionedStorage, bool) {
+	vs, ok := s.(VersionedStorage)
+	return vs, ok
+}

internal/storage/versioned_test.go

@@ -0,0 +1,86 @@
+package storage_test
+
+import (
+	"testing"
+
+	"github.com/steveyegge/beads/internal/storage"
+	"github.com/steveyegge/beads/internal/storage/memory"
+)
+
+// TestIsVersioned verifies the IsVersioned type detection helper.
+func TestIsVersioned(t *testing.T) {
+	// Memory storage is NOT versioned
+	memStore := memory.New("")
+
+	if storage.IsVersioned(memStore) {
+		t.Error("IsVersioned should return false for memory storage")
+	}
+
+	// Test AsVersioned returns false for non-versioned storage
+	vs, ok := storage.AsVersioned(memStore)
+	if ok {
+		t.Error("AsVersioned should return false for memory storage")
+	}
+	if vs != nil {
+		t.Error("AsVersioned should return nil for memory storage")
+	}
+}
+
+// TestVersionedStorageInterface ensures the interface is correctly defined.
+func TestVersionedStorageInterface(t *testing.T) {
+	// This test verifies that the interface types exist and have the expected methods.
+	// Actual implementation testing would be done in the dolt package.
+
+	// HistoryEntry should have the expected fields
+	entry := storage.HistoryEntry{
+		CommitHash: "abc123",
+		Committer:  "test",
+	}
+	if entry.CommitHash != "abc123" {
+		t.Error("HistoryEntry.CommitHash not working")
+	}
+
+	// DiffEntry should have the expected fields
+	diff := storage.DiffEntry{
+		IssueID:  "bd-123",
+		DiffType: "modified",
+	}
+	if diff.IssueID != "bd-123" {
+		t.Error("DiffEntry.IssueID not working")
+	}
+	if diff.DiffType != "modified" {
+		t.Error("DiffEntry.DiffType not working")
+	}
+
+	// Conflict should have the expected fields
+	conflict := storage.Conflict{
+		IssueID: "bd-456",
+		Field:   "title",
+	}
+	if conflict.IssueID != "bd-456" {
+		t.Error("Conflict.IssueID not working")
+	}
+	if conflict.Field != "title" {
+		t.Error("Conflict.Field not working")
+	}
+}
+
+// TestVersionedStorageTypes verifies type values work as expected.
+func TestVersionedStorageTypes(t *testing.T) {
+	// Test DiffEntry types
+	testCases := []struct {
+		diffType string
+		valid    bool
+	}{
+		{"added", true},
+		{"modified", true},
+		{"removed", true},
+	}
+
+	for _, tc := range testCases {
+		entry := storage.DiffEntry{DiffType: tc.diffType}
+		if entry.DiffType != tc.diffType {
+			t.Errorf("DiffEntry.DiffType mismatch: expected %s, got %s", tc.diffType, entry.DiffType)
+		}
+	}
+}