raftengine: add legacy boltdb and nil-safety tests, document offline migration requirement

Address @claude review (Test Coverage + Data Loss):
- Add TestRejectLegacyBoltDB: verify factory rejects dirs with legacy files
- Add TestEngineCloseNilSafe: verify nil engine/raft Close does not panic
- Document that MigrateFSMStore requires the source engine to be stopped

Author: bootjp

internal/raftengine/hashicorp/engine_test.go

@@ -1,11 +1,15 @@
 package hashicorp_test
 
 import (
+	"os"
+	"path/filepath"
 	"testing"
 	"time"
 
+	"github.com/bootjp/elastickv/internal/raftengine"
 	hashicorpraftengine "github.com/bootjp/elastickv/internal/raftengine/hashicorp"
 	"github.com/bootjp/elastickv/internal/raftengine/raftenginetest"
+	"github.com/stretchr/testify/require"
 )
 
 func TestConformance(t *testing.T) {
@@ -18,3 +22,46 @@ func TestConformance(t *testing.T) {
 	})
 	raftenginetest.RunConformanceSuite(t, factory)
 }
+
+func TestEngineCloseNilSafe(t *testing.T) {
+	t.Parallel()
+
+	t.Run("nil_engine", func(t *testing.T) {
+		var e *hashicorpraftengine.Engine
+		require.NoError(t, e.Close())
+	})
+
+	t.Run("nil_raft_via_New", func(t *testing.T) {
+		e := hashicorpraftengine.New(nil)
+		require.Nil(t, e)
+	})
+}
+
+func TestRejectLegacyBoltDB(t *testing.T) {
+	t.Parallel()
+
+	factory := hashicorpraftengine.NewFactory(hashicorpraftengine.FactoryConfig{
+		CommitTimeout:       50 * time.Millisecond,
+		HeartbeatTimeout:    200 * time.Millisecond,
+		ElectionTimeout:     2000 * time.Millisecond,
+		LeaderLeaseTimeout:  100 * time.Millisecond,
+		SnapshotRetainCount: 3,
+	})
+
+	for _, legacy := range []string{"logs.dat", "stable.dat"} {
+		t.Run(legacy, func(t *testing.T) {
+			dir := t.TempDir()
+			require.NoError(t, os.WriteFile(filepath.Join(dir, legacy), []byte("legacy"), 0o600))
+
+			_, err := factory.Create(raftengine.FactoryConfig{
+				LocalID:      "n1",
+				LocalAddress: "127.0.0.1:0",
+				DataDir:      dir,
+				Bootstrap:    true,
+				StateMachine: &raftenginetest.TestStateMachine{},
+			})
+			require.Error(t, err)
+			require.Contains(t, err.Error(), "legacy boltdb")
+		})
+	}
+}

internal/raftengine/hashicorp/migrate.go

@@ -68,6 +68,10 @@ func ParsePeers(raw string) ([]MigrationPeer, error) {
 //
 // The source FSM store (fsm.db) is read-only and shared between both engines;
 // this function only creates the hashicorp-specific artifacts.
+//
+// IMPORTANT: The source engine must be fully stopped before running this
+// tool. Running it against a live engine may produce an inconsistent
+// snapshot that is missing recently applied entries.
 func MigrateFSMStore(storePath string, destDataDir string, peers []MigrationPeer) (*MigrationStats, error) {
 	destDataDir, tempDir, err := prepareMigrationDest(storePath, destDataDir, peers)
 	if err != nil {