Migration.lua

-- Schema migration for Enhanced Cooldown Manager
-- Handles versioned SavedVariable namespacing and profile migrations.

local _, ns = ...
local Migration = {}
ns.Migration = Migration

-- Legacy free-mode bars used implicit default positions when offset fields were
-- absent from SavedVariables. Keep these migration-local so the historical
-- fallback data stays coupled to the schema upgrade that needs it.
local LEGACY_FREE_POSITION_DEFAULTS = {
    powerBar = { point = "CENTER", x = 0, y = -275 },
    resourceBar = { point = "CENTER", x = 0, y = -300 },
    runeBar = { point = "CENTER", x = 0, y = -325 },
    buffBars = { point = "CENTER", x = 0, y = -350 },
}

--- Migration log buffer. Entries are collected during migration and persisted
--- into the new version's SV slot so they survive across sessions.
---@type string[]
local migrationLog = {}

--- Appends a timestamped message to the migration log buffer and sends it to
--- the normal debug log.
---@param message string
local function log(message)
    migrationLog[#migrationLog + 1] = date("%Y-%m-%d %H:%M:%S") .. "  " .. message
    ns.Log("Migration", message)
end

--------------------------------------------------------------------------------
-- Helpers
--------------------------------------------------------------------------------

--- Aligns copied profile schemaVersion values with the slot they came from.
--- The versioned slot key is the source of truth during reseeding; older slots
--- may contain profiles that were previously migrated forward in-place.
---@param slot table|nil
---@param schemaVersion number
local function alignSlotProfileSchemas(slot, schemaVersion)
    if type(slot) ~= "table" or type(slot.profiles) ~= "table" then
        return
    end

    for _, profile in pairs(slot.profiles) do
        if type(profile) == "table" then
            profile.schemaVersion = schemaVersion
        end
    end
end

local function normalizeLegacyColor(color, defaultAlpha)
    if color == nil then
        return nil
    end

    if type(color) ~= "table" then
        return nil
    end

    if color.r ~= nil or color.g ~= nil or color.b ~= nil then
        return {
            r = color.r or 0,
            g = color.g or 0,
            b = color.b or 0,
            a = color.a or defaultAlpha or 1,
        }
    end

    if color[1] ~= nil then
        return {
            r = color[1],
            g = color[2],
            b = color[3],
            a = color[4] or defaultAlpha or 1,
        }
    end

    return nil
end

--- Returns true when the color matches the expected RGBA values.
---@param color ECM_Color|table|nil
---@param r number
---@param g number
---@param b number
---@param a number|nil
---@return boolean
local function isColorMatch(color, r, g, b, a)
    if type(color) ~= "table" then
        return false
    end

    local resolved = normalizeLegacyColor(color, a)
    if not resolved then
        return false
    end

    if resolved.r ~= r or resolved.g ~= g or resolved.b ~= b then
        return false
    end

    if a == nil then
        return true
    end

    return resolved.a == a
end

local function normalizeColorTable(colorTable, defaultAlpha)
    if type(colorTable) ~= "table" then
        return
    end

    for key, value in pairs(colorTable) do
        colorTable[key] = normalizeLegacyColor(value, defaultAlpha)
    end
end

-- Migration loads before ECM.lua during normal addon startup, so the canonical
-- clone helper may not exist yet when PrepareDatabase reseeds versioned slots.
local function cloneValue(value)
    if ns.CloneValue then
        return ns.CloneValue(value)
    end

    if type(value) ~= "table" then
        return value
    end

    local copy = {}
    for k, v in pairs(value) do
        copy[k] = cloneValue(v)
    end
    return copy
end

local function normalizeBarConfig(cfg)
    if not cfg then
        return
    end

    cfg.bgColor = normalizeLegacyColor(cfg.bgColor, 1)
    if cfg.border and cfg.border.color then
        cfg.border.color = normalizeLegacyColor(cfg.border.color, 1)
    end
    if cfg.colors then
        normalizeColorTable(cfg.colors, 1)
    end
    if cfg.color then
        cfg.color = normalizeLegacyColor(cfg.color, 1)
    end
end

local function forEachClassSpecEntry(store, fn)
    if type(store) ~= "table" then
        return
    end

    for classID, classMap in pairs(store) do
        if type(classMap) == "table" then
            for specID, specMap in pairs(classMap) do
                if type(specMap) == "table" then
                    fn(classID, specID, specMap)
                end
            end
        end
    end
end

local function normalizeBuffBarsCache(cfg)
    if not (cfg and cfg.colors and type(cfg.colors.cache) == "table") then
        return
    end

    forEachClassSpecEntry(cfg.colors.cache, function(_, _, specMap)
        for index, entry in pairs(specMap) do
            if type(entry) ~= "table" then
                specMap[index] = nil
            else
                entry.color = nil
                local spellName = entry.spellName
                if type(spellName) ~= "string" then
                    specMap[index] = nil
                else
                    spellName = strtrim(spellName)
                    if spellName == "" or spellName == "Unknown" then
                        specMap[index] = nil
                    else
                        entry.spellName = spellName
                    end
                end
            end
        end
    end)
end

local FrameUtil = ns.FrameUtil

-- Built-in Edit Mode layout indices (frozen for migration stability).
local EDIT_MODE_BUILTIN_NAMES = { "Modern", "Classic" }

---@return string[]|nil names All layout names, or nil if unavailable.
local function resolveAllLayoutNames()
    local layoutInfo = C_EditMode.GetLayouts()
    if not layoutInfo then
        return nil
    end

    local names = {}
    for i, builtin in ipairs(EDIT_MODE_BUILTIN_NAMES) do
        names[i] = builtin
    end

    local customs = layoutInfo.layouts
    if customs then
        for i = 1, #customs do
            local name = customs[i].layoutName
            if type(name) == "string" and name ~= "" then
                names[#names + 1] = name
            end
        end
    end

    return #names > 0 and names or nil
end

local normalizeEditModePosition = FrameUtil.NormalizePosition

--- Migrates profiles from the per-bar color settings to per-spell.
---@param profile table The profile to migrate
local function migrateToPerSpellColors(profile)
    local cfg = profile.buffBars
    if not cfg then
        return
    end

    local perBar = cfg.colors.perBar
    local cache = cfg.colors.cache

    if not perBar then
        return
    end

    if not cfg.colors.perSpell then
        cfg.colors.perSpell = {}
    end

    local perSpell = cfg.colors.perSpell

    local function doSpellMigration(perBarStore, perSpellStore, cacheStore)
        for i, v in ipairs(cacheStore) do
            if not v.color and v.spellName then
                local bc = perBarStore[i]
                if bc then
                    perSpellStore[v.spellName] = bc
                    cacheStore[i] = {
                        lastSeen = v.lastSeen,
                        spellName = v.spellName,
                    }
                end
            end
        end
    end

    forEachClassSpecEntry(perBar, function(classID, specID, perBarStore)
        perSpell[classID] = perSpell[classID] or {}
        perSpell[classID][specID] = perSpell[classID][specID] or {}
        if cache[classID] and cache[classID][specID] then
            doSpellMigration(perBarStore, perSpell[classID][specID], cache[classID][specID])
        end
    end)

    cfg.colors.perBar = nil
end

--- Repairs spell-color metadata and fallback tier links for all class/spec stores.
--- This migration runs once and replaces the previous runtime-only repair path.
---@param profile table The profile to repair
local function repairSpellColorStores(profile)
    local buffBars = profile.buffBars
    if not (buffBars and type(buffBars.colors) == "table") then
        return
    end

    local colors = buffBars.colors
    if type(colors.byName) ~= "table" then
        colors.byName = {}
    end
    if type(colors.bySpellID) ~= "table" then
        colors.bySpellID = {}
    end
    if type(colors.byCooldownID) ~= "table" then
        colors.byCooldownID = {}
    end
    if type(colors.byTexture) ~= "table" then
        colors.byTexture = {}
    end

    local tierDefs = {
        { storeKey = "byName", keyType = "spellName" },
        { storeKey = "bySpellID", keyType = "spellID", idField = "spellID" },
        { storeKey = "byCooldownID", keyType = "cooldownID", idField = "cooldownID" },
        { storeKey = "byTexture", keyType = "textureFileID", idField = "textureId" },
    }

    -- Normalize metadata per stored tier so options/runtime no longer need to infer.
    for _, tier in ipairs(tierDefs) do
        forEachClassSpecEntry(colors[tier.storeKey], function(_, _, specMap)
            for key, entry in pairs(specMap) do
                if type(entry) == "table" and type(entry.value) == "table" then
                    local value = entry.value
                    if not value.keyType then
                        value.keyType = tier.keyType
                    end
                    if tier.idField and type(key) == "number" and value[tier.idField] == nil then
                        value[tier.idField] = key
                    end
                end
            end
        end)
    end

    local function ensureClassSpecStore(store, classID, specID)
        if type(store[classID]) ~= "table" then
            store[classID] = {}
        end
        if type(store[classID][specID]) ~= "table" then
            store[classID][specID] = {}
        end
        return store[classID][specID]
    end

    -- Backfill fallback tiers from byName entries carrying embedded IDs.
    forEachClassSpecEntry(colors.byName, function(classID, specID, specMap)
        local bySpellIDSpec = ensureClassSpecStore(colors.bySpellID, classID, specID)
        local byCooldownIDSpec = ensureClassSpecStore(colors.byCooldownID, classID, specID)
        local byTextureSpec = ensureClassSpecStore(colors.byTexture, classID, specID)

        for _, entry in pairs(specMap) do
            if type(entry) == "table" and type(entry.value) == "table" then
                local value = entry.value

                if type(value.spellID) == "number" and bySpellIDSpec[value.spellID] == nil then
                    bySpellIDSpec[value.spellID] = entry
                end
                if type(value.cooldownID) == "number" and byCooldownIDSpec[value.cooldownID] == nil then
                    byCooldownIDSpec[value.cooldownID] = entry
                end
                if type(value.textureId) == "number" and byTextureSpec[value.textureId] == nil then
                    byTextureSpec[value.textureId] = entry
                end
            end
        end
    end)
end

--- Normalizes spell-color wrapper metadata and collapses duplicate entries.
--- Stored color payloads become color-only (r/g/b/a); identifiers move to entry.meta.
---@param profile table The profile to repair
local function normalizeSpellColorStoresV10(profile)
    local stats = {
        skipped = false,
        skipReason = nil,
        tierStoresCreated = {},
        tierStoresCreatedCount = 0,
        classesProcessed = 0,
        specsProcessed = 0,
        entriesScanned = 0,
        validEntries = 0,
        invalidEntries = 0,
        canonicalEntries = 0,
        aliasLinksMerged = 0,
        invalidRetained = 0,
        invalidKeyCollisions = 0,
        entriesMetaNormalized = 0,
        finalEntries = 0,
        perTier = {
            byName = { scanned = 0, invalid = 0, final = 0 },
            bySpellID = { scanned = 0, invalid = 0, final = 0 },
            byCooldownID = { scanned = 0, invalid = 0, final = 0 },
            byTexture = { scanned = 0, invalid = 0, final = 0 },
        },
        anomalySpecs = {},
        anomalySpecsOverflow = 0,
    }

    local buffBars = profile.buffBars
    if not (buffBars and type(buffBars.colors) == "table") then
        stats.skipped = true
        stats.skipReason = "buffBars.colors missing"
        return stats
    end

    local colors = buffBars.colors
    local tierDefs = {
        { storeKey = "byName", keyType = "spellName" },
        { storeKey = "bySpellID", keyType = "spellID" },
        { storeKey = "byCooldownID", keyType = "cooldownID" },
        { storeKey = "byTexture", keyType = "textureFileID" },
    }
    local validKeyTypes = {
        spellName = true,
        spellID = true,
        cooldownID = true,
        textureFileID = true,
    }

    local function ensureTierStore(storeKey)
        if type(colors[storeKey]) ~= "table" then
            colors[storeKey] = {}
            if not stats.tierStoresCreated[storeKey] then
                stats.tierStoresCreated[storeKey] = true
                stats.tierStoresCreatedCount = stats.tierStoresCreatedCount + 1
            end
        end
        return colors[storeKey]
    end

    local function ensureClassSpec(store, classID, specID)
        if type(store[classID]) ~= "table" then
            store[classID] = {}
        end
        if type(store[classID][specID]) ~= "table" then
            store[classID][specID] = {}
        end
        return store[classID][specID]
    end

    local function validKey(k)
        if type(k) == "string" or type(k) == "number" then
            return k
        end
        return nil
    end

    local function validNumericKey(k)
        return type(k) == "number" and k or nil
    end

    local function countEntries(map)
        if type(map) ~= "table" then
            return 0
        end
        local n = 0
        for _ in pairs(map) do
            n = n + 1
        end
        return n
    end

    local function selectPrimary(spellName, spellID, cooldownID, textureFileID)
        if spellName ~= nil then
            return spellName, "spellName"
        end
        if spellID ~= nil then
            return spellID, "spellID"
        end
        if cooldownID ~= nil then
            return cooldownID, "cooldownID"
        end
        if textureFileID ~= nil then
            return textureFileID, "textureFileID"
        end
        return nil, nil
    end

    local function buildKey(spellName, spellID, cooldownID, textureFileID, preferredType)
        local keyType = validKeyTypes[preferredType] and preferredType or nil
        local primaryKey
        if keyType == "spellName" then
            primaryKey = spellName
        elseif keyType == "spellID" then
            primaryKey = spellID
        elseif keyType == "cooldownID" then
            primaryKey = cooldownID
        elseif keyType == "textureFileID" then
            primaryKey = textureFileID
        end
        if primaryKey == nil then
            primaryKey, keyType = selectPrimary(spellName, spellID, cooldownID, textureFileID)
        end
        if keyType == nil or primaryKey == nil then
            return nil
        end
        return {
            keyType = keyType,
            primaryKey = primaryKey,
            spellName = spellName,
            spellID = spellID,
            cooldownID = cooldownID,
            textureFileID = textureFileID,
        }
    end

    local function keysMatch(a, b)
        if not (a and b) then
            return false
        end
        if a.spellName and b.spellName and a.spellName == b.spellName then
            return true
        end
        if a.spellID and b.spellID and a.spellID == b.spellID then
            return true
        end
        if a.cooldownID and b.cooldownID and a.cooldownID == b.cooldownID then
            return true
        end
        if a.textureFileID and b.textureFileID and a.textureFileID == b.textureFileID then
            return true
        end
        return false
    end

    local function mergeKeys(a, b)
        if a == nil then
            return b
        end
        if b == nil then
            return a
        end
        if not keysMatch(a, b) then
            return nil
        end
        return buildKey(
            a.spellName or b.spellName,
            a.spellID or b.spellID,
            a.cooldownID or b.cooldownID,
            a.textureFileID or b.textureFileID,
            nil
        )
    end

    local function entryTs(entry)
        return (type(entry) == "table" and type(entry.t) == "number") and entry.t or 0
    end

    local function scrubValue(value)
        if type(value) ~= "table" then
            return
        end
        value.keyType = nil
        value.primaryKey = nil
        value.spellName = nil
        value.spellID = nil
        value.cooldownID = nil
        value.textureId = nil
        value.textureFileID = nil
        if value.a == nil then
            value.a = 1
        end
    end

    local function buildKeyFromEntry(entry, tierKeyType, rawKey)
        if type(entry) ~= "table" or type(entry.value) ~= "table" then
            return nil
        end

        local value = entry.value
        local meta = type(entry.meta) == "table" and entry.meta or nil
        local spellName = validKey((meta and meta.spellName) or value.spellName)
        local spellID = validNumericKey((meta and meta.spellID) or value.spellID)
        local cooldownID = validNumericKey((meta and meta.cooldownID) or value.cooldownID)
        local textureFileID =
            validNumericKey((meta and (meta.textureFileID or meta.textureId)) or value.textureFileID or value.textureId)
        local preferredType = (meta and meta.keyType) or value.keyType or tierKeyType
        if not validKeyTypes[preferredType] then
            preferredType = tierKeyType
        end

        local vRaw = validKey(rawKey)
        if tierKeyType == "spellName" and type(vRaw) == "string" then
            spellName = vRaw
        elseif tierKeyType == "spellID" and type(vRaw) == "number" then
            spellID = vRaw
        elseif tierKeyType == "cooldownID" and type(vRaw) == "number" then
            cooldownID = vRaw
        elseif tierKeyType == "textureFileID" and type(vRaw) == "number" then
            textureFileID = vRaw
        end

        return buildKey(spellName, spellID, cooldownID, textureFileID, preferredType)
    end

    local function setEntryMeta(entry, key)
        if type(entry) ~= "table" or type(entry.value) ~= "table" or not key then
            return
        end
        scrubValue(entry.value)
        stats.entriesMetaNormalized = stats.entriesMetaNormalized + 1
        entry.meta = {
            keyType = key.keyType,
            primaryKey = key.primaryKey,
            spellName = key.spellName,
            spellID = key.spellID,
            cooldownID = key.cooldownID,
            textureFileID = key.textureFileID,
        }
    end

    for _, tier in ipairs(tierDefs) do
        ensureTierStore(tier.storeKey)
    end

    local classIDs = {}
    for _, tier in ipairs(tierDefs) do
        local store = colors[tier.storeKey]
        for classID, classMap in pairs(store) do
            if type(classMap) == "table" then
                classIDs[classID] = true
            end
        end
    end

    for classID in pairs(classIDs) do
        stats.classesProcessed = stats.classesProcessed + 1
        local specIDs = {}
        for _, tier in ipairs(tierDefs) do
            local classMap = colors[tier.storeKey][classID]
            if type(classMap) == "table" then
                for specID, specMap in pairs(classMap) do
                    if type(specMap) == "table" then
                        specIDs[specID] = true
                    end
                end
            end
        end

        for specID in pairs(specIDs) do
            stats.specsProcessed = stats.specsProcessed + 1
            local groups = {}
            local groupByEntry = {}
            local invalidPerTier = {}
            local newPerTier = {}
            local specScanned = 0
            local specInvalid = 0
            local specInvalidByTier = {}

            for tierIndex, tier in ipairs(tierDefs) do
                invalidPerTier[tierIndex] = {}
                newPerTier[tierIndex] = {}
                specInvalidByTier[tier.storeKey] = 0

                local specStore = ensureClassSpec(colors[tier.storeKey], classID, specID)
                for rawKey, entry in pairs(specStore) do
                    stats.entriesScanned = stats.entriesScanned + 1
                    stats.perTier[tier.storeKey].scanned = stats.perTier[tier.storeKey].scanned + 1
                    specScanned = specScanned + 1
                    local key = buildKeyFromEntry(entry, tier.keyType, rawKey)
                    if not key then
                        invalidPerTier[tierIndex][rawKey] = entry
                        stats.invalidEntries = stats.invalidEntries + 1
                        stats.perTier[tier.storeKey].invalid = stats.perTier[tier.storeKey].invalid + 1
                        specInvalid = specInvalid + 1
                        specInvalidByTier[tier.storeKey] = specInvalidByTier[tier.storeKey] + 1
                    else
                        stats.validEntries = stats.validEntries + 1
                        local groupIndex = groupByEntry[entry]
                        if not groupIndex then
                            for i, group in ipairs(groups) do
                                if keysMatch(group.key, key) then
                                    groupIndex = i
                                    break
                                end
                            end
                        end

                        if not groupIndex then
                            groupIndex = #groups + 1
                            groups[groupIndex] = {
                                key = key,
                                entry = entry,
                                ts = entryTs(entry),
                                tierIndex = tierIndex,
                            }
                        else
                            local group = groups[groupIndex]
                            group.key = mergeKeys(group.key, key) or group.key
                            local t = entryTs(entry)
                            if t > group.ts or (t == group.ts and tierIndex < group.tierIndex) then
                                group.entry = entry
                                group.ts = t
                                group.tierIndex = tierIndex
                            end
                        end

                        if type(entry) == "table" then
                            groupByEntry[entry] = groupIndex
                        end
                    end
                end
            end

            stats.canonicalEntries = stats.canonicalEntries + #groups
            if specScanned > specInvalid and #groups < (specScanned - specInvalid) then
                stats.aliasLinksMerged = stats.aliasLinksMerged + ((specScanned - specInvalid) - #groups)
            end

            for _, group in ipairs(groups) do
                if group.entry and group.key then
                    setEntryMeta(group.entry, group.key)
                    if group.key.spellName ~= nil then
                        newPerTier[1][group.key.spellName] = group.entry
                    end
                    if group.key.spellID ~= nil then
                        newPerTier[2][group.key.spellID] = group.entry
                    end
                    if group.key.cooldownID ~= nil then
                        newPerTier[3][group.key.cooldownID] = group.entry
                    end
                    if group.key.textureFileID ~= nil then
                        newPerTier[4][group.key.textureFileID] = group.entry
                    end
                end
            end

            for tierIndex, tier in ipairs(tierDefs) do
                ensureClassSpec(colors[tier.storeKey], classID, specID)
                colors[tier.storeKey][classID][specID] = newPerTier[tierIndex]
                for rawKey, entry in pairs(invalidPerTier[tierIndex]) do
                    if newPerTier[tierIndex][rawKey] == nil then
                        newPerTier[tierIndex][rawKey] = entry
                        stats.invalidRetained = stats.invalidRetained + 1
                    else
                        stats.invalidKeyCollisions = stats.invalidKeyCollisions + 1
                    end
                end
                for _, entry in pairs(newPerTier[tierIndex]) do
                    if type(entry) == "table" and type(entry.value) == "table" then
                        scrubValue(entry.value)
                    end
                end
                local finalCount = countEntries(newPerTier[tierIndex])
                stats.finalEntries = stats.finalEntries + finalCount
                stats.perTier[tier.storeKey].final = stats.perTier[tier.storeKey].final + finalCount
            end

            if specInvalid > 0 or (specScanned > specInvalid and #groups < (specScanned - specInvalid)) then
                local invalidTierParts = {}
                for _, tier in ipairs(tierDefs) do
                    local invalidCount = specInvalidByTier[tier.storeKey]
                    if invalidCount and invalidCount > 0 then
                        invalidTierParts[#invalidTierParts + 1] = tier.storeKey .. "=" .. invalidCount
                    end
                end
                local aliasLinks = 0
                if specScanned > specInvalid and #groups < (specScanned - specInvalid) then
                    aliasLinks = (specScanned - specInvalid) - #groups
                end
                local msg = string.format(
                    "class=%s spec=%s scanned=%d valid=%d canonical=%d aliases=%d invalid=%d",
                    tostring(classID),
                    tostring(specID),
                    specScanned,
                    specScanned - specInvalid,
                    #groups,
                    aliasLinks,
                    specInvalid
                )
                if #invalidTierParts > 0 then
                    msg = msg .. " invalidByTier[" .. table.concat(invalidTierParts, ",") .. "]"
                end

                if #stats.anomalySpecs < 20 then
                    stats.anomalySpecs[#stats.anomalySpecs + 1] = msg
                else
                    stats.anomalySpecsOverflow = stats.anomalySpecsOverflow + 1
                end
            end
        end
    end

    return stats
end

--------------------------------------------------------------------------------
-- Schema Migrations
--------------------------------------------------------------------------------

--------------------------------------------------------------------------------
-- Schema Migrations — registered per-version steps
--------------------------------------------------------------------------------

--- Registry of migration steps, keyed by target version.
--- Each function receives the profile and returns false to defer (stop the
--- migration chain), or any other value to indicate success.
local _migrations = {}

-- V2 → V3: buffBarColors -> buffBars.colors
_migrations[3] = function(profile)
    if profile.buffBarColors then
        log("Migrating buffBarColors to buffBars.colors")

        profile.buffBars = profile.buffBars or {}
        profile.buffBars.colors = profile.buffBars.colors or {}

        local src = profile.buffBarColors
        local dst = profile.buffBars.colors

        dst.perBar = dst.perBar or src.colors or {}
        dst.cache = dst.cache or src.cache or {}
        dst.defaultColor = dst.defaultColor or src.defaultColor
        profile.buffBarColors = nil
    end

    local colorsConfig = profile.buffBars and profile.buffBars.colors
    if colorsConfig and colorsConfig.colors and not colorsConfig.perBar then
        log("Renaming buffBars.colors.colors to buffBars.colors.perBar")
        colorsConfig.perBar = colorsConfig.colors
        colorsConfig.colors = nil
    end
end

-- V3 → V4: tick colors, color normalization, powerBarTicks restructure
_migrations[4] = function(profile)
    local ticksCfg = profile.powerBarTicks
    if ticksCfg and isColorMatch(ticksCfg.defaultColor, 0, 0, 0, 0.5) then
        ticksCfg.defaultColor = { r = 1, g = 1, b = 1, a = 0.8 }
    end

    local resourceCfg = profile.resourceBar
    local colors = resourceCfg and resourceCfg.colors
    local soulsColor = colors and colors[ns.Constants.RESOURCEBAR_TYPE_VENGEANCE_SOULS]
    if isColorMatch(soulsColor, 0.46, 0.98, 1.00, nil) then
        colors[ns.Constants.RESOURCEBAR_TYPE_VENGEANCE_SOULS] = { r = 0.259, g = 0.6, b = 0.91, a = 1 }
    end

    if profile.powerBarTicks then
        profile.powerBar = profile.powerBar or {}
        if not profile.powerBar.ticks then
            profile.powerBar.ticks = profile.powerBarTicks
        end
        profile.powerBarTicks = nil
    end

    local gbl = profile.global
    if gbl then
        gbl.barBgColor = normalizeLegacyColor(gbl.barBgColor, 1)
    end

    normalizeBarConfig(profile.powerBar)
    normalizeBarConfig(profile.resourceBar)
    normalizeBarConfig(profile.runeBar)

    local powerBar = profile.powerBar
    if powerBar and powerBar.ticks then
        local tickCfg = powerBar.ticks
        tickCfg.defaultColor = normalizeLegacyColor(tickCfg.defaultColor, 1)
        if tickCfg.mappings then
            for _, specMap in pairs(tickCfg.mappings) do
                for _, ticks in pairs(specMap) do
                    for _, tick in ipairs(ticks) do
                        if tick and tick.color then
                            tick.color = normalizeLegacyColor(
                                tick.color,
                                tickCfg.defaultColor and tickCfg.defaultColor.a or 1
                            )
                        end
                    end
                end
            end
        end
    end

    local buffBars = profile.buffBars
    if buffBars and buffBars.colors then
        buffBars.colors.defaultColor = normalizeLegacyColor(buffBars.colors.defaultColor, 1)
        local perBar = buffBars.colors.perBar
        if type(perBar) == "table" then
            for _, specMap in pairs(perBar) do
                for _, bars in pairs(specMap) do
                    if type(bars) == "table" then
                        for index, color in pairs(bars) do
                            bars[index] = normalizeLegacyColor(color, 1)
                        end
                    end
                end
            end
        end
    end
end

-- V4 → V5: combatFade -> global.outOfCombatFade
_migrations[5] = function(profile)
    local legacyCombatFade = profile.combatFade
    if legacyCombatFade then
        profile.global = profile.global or {}
        profile.global.outOfCombatFade = profile.global.outOfCombatFade or {}

        local fadeConfig = profile.global.outOfCombatFade
        if legacyCombatFade.enabled ~= nil then
            fadeConfig.enabled = legacyCombatFade.enabled
        end
        if legacyCombatFade.opacity ~= nil then
            fadeConfig.opacity = legacyCombatFade.opacity
        end
        if legacyCombatFade.exceptInInstance ~= nil then
            fadeConfig.exceptInInstance = legacyCombatFade.exceptInInstance
        end
        if legacyCombatFade.exceptIfTargetCanBeAttacked ~= nil then
            fadeConfig.exceptIfTargetCanBeAttacked = legacyCombatFade.exceptIfTargetCanBeAttacked
        end

        profile.combatFade = nil
    end
end

-- V5 → V6: perBar -> perSpell colors
_migrations[6] = function(profile)
    migrateToPerSpellColors(profile)
end

-- V6 → V7: normalize buff bar cache entries
_migrations[7] = function(profile)
    local buffBars = profile.buffBars
    if buffBars then
        normalizeBuffBarsCache(buffBars)
    end
end

-- V7 → V8: split flat perSpell map into separate byName / byTexture tables
_migrations[8] = function(profile)
    local buffBars = profile.buffBars
    if buffBars and type(buffBars.colors) == "table" then
        local colors = buffBars.colors
        local perSpell = colors.perSpell

        if type(perSpell) == "table" then
            if type(colors.byName) ~= "table" then
                colors.byName = {}
            end
            if type(colors.byTexture) ~= "table" then
                colors.byTexture = {}
            end

            for classID, specTable in pairs(perSpell) do
                if type(specTable) == "table" then
                    for specID, entries in pairs(specTable) do
                        if type(entries) == "table" then
                            colors.byName[classID] = colors.byName[classID] or {}
                            colors.byName[classID][specID] = colors.byName[classID][specID] or {}
                            colors.byTexture[classID] = colors.byTexture[classID] or {}
                            colors.byTexture[classID][specID] = colors.byTexture[classID][specID] or {}

                            for key, color in pairs(entries) do
                                local wrapped = { value = color, t = 0 }
                                if type(key) == "string" then
                                    colors.byName[classID][specID][key] = wrapped
                                elseif type(key) == "number" then
                                    colors.byTexture[classID][specID][key] = wrapped
                                end
                            end
                        end
                    end
                end
            end

            colors.perSpell = nil
        end

        if type(colors.bySpellID) ~= "table" then
            colors.bySpellID = {}
        end
        if type(colors.byCooldownID) ~= "table" then
            colors.byCooldownID = {}
        end
    end
end

-- V8 → V9: repair spell color metadata and fallback tier links
_migrations[9] = function(profile)
    repairSpellColorStores(profile)
end

-- V9 → V10: normalize spell color wrapper metadata and collapse fragmented entries
_migrations[10] = function(profile)
    local v10Stats = normalizeSpellColorStoresV10(profile)
    if v10Stats and v10Stats.skipped then
        log("V10 spell color normalization skipped: " .. (v10Stats.skipReason or "unknown reason"))
    elseif v10Stats then
        local createdTiers = {}
        for _, tier in ipairs({ "byName", "bySpellID", "byCooldownID", "byTexture" }) do
            if v10Stats.tierStoresCreated[tier] then
                createdTiers[#createdTiers + 1] = tier
            end
        end

        log(
            string.format(
                "V10 spell color normalization summary: classes=%d specs=%d scanned=%d valid=%d canonical=%d aliases=%d invalid=%d invalidRetained=%d invalidKeyCollisions=%d metaNormalized=%d final=%d",
                v10Stats.classesProcessed,
                v10Stats.specsProcessed,
                v10Stats.entriesScanned,
                v10Stats.validEntries,
                v10Stats.canonicalEntries,
                v10Stats.aliasLinksMerged,
                v10Stats.invalidEntries,
                v10Stats.invalidRetained,
                v10Stats.invalidKeyCollisions,
                v10Stats.entriesMetaNormalized,
                v10Stats.finalEntries
            )
        )
        log(
            string.format(
                "V10 tier breakdown: byName(s=%d i=%d f=%d), bySpellID(s=%d i=%d f=%d), byCooldownID(s=%d i=%d f=%d), byTexture(s=%d i=%d f=%d)",
                v10Stats.perTier.byName.scanned,
                v10Stats.perTier.byName.invalid,
                v10Stats.perTier.byName.final,
                v10Stats.perTier.bySpellID.scanned,
                v10Stats.perTier.bySpellID.invalid,
                v10Stats.perTier.bySpellID.final,
                v10Stats.perTier.byCooldownID.scanned,
                v10Stats.perTier.byCooldownID.invalid,
                v10Stats.perTier.byCooldownID.final,
                v10Stats.perTier.byTexture.scanned,
                v10Stats.perTier.byTexture.invalid,
                v10Stats.perTier.byTexture.final
            )
        )
        if #createdTiers > 0 then
            log("V10 created missing tier stores: " .. table.concat(createdTiers, ", "))
        end
        for _, msg in ipairs(v10Stats.anomalySpecs) do
            log("V10 anomaly: " .. msg)
        end
        if v10Stats.anomalySpecsOverflow > 0 then
            log("V10 anomaly: additional specs omitted=" .. v10Stats.anomalySpecsOverflow)
        end
    end
end

-- V10 → V11: move legacy offsets into editModePositions.
-- V10 had a single position for all layouts; seed every known layout with the
-- same value so the bar appears correctly regardless of which layout is active.
_migrations[11] = function(profile)
    local allLayouts = resolveAllLayoutNames()
    if not allLayouts then
        log("V11 no layouts available; skipping position migration")
        return
    end

    log("V11 resolved layouts: " .. table.concat(allLayouts, ", "))

    for _, section in ipairs({ "powerBar", "resourceBar", "runeBar", "buffBars" }) do
        local cfg = profile[section]
        if type(cfg) == "table" then
            local legacyPosition = LEGACY_FREE_POSITION_DEFAULTS[section]
            local ox = cfg.offsetX
            local oy = cfg.offsetY
            local ap = cfg.anchorPoint
            local rp = cfg.relativePoint
            local isLegacyFreeMode = cfg.anchorMode == ns.Constants.ANCHORMODE_FREE
            local sourcePoint = ap or (legacyPosition and legacyPosition.point) or ns.Constants.EDIT_MODE_DEFAULT_POINT
            local sourceRelativePoint = rp or ap or (legacyPosition and legacyPosition.point) or sourcePoint
            local sourceX = ox ~= nil and ox or (legacyPosition and legacyPosition.x) or 0
            local sourceY = oy ~= nil and oy or (legacyPosition and legacyPosition.y) or 0
            local migrationSource = (ox ~= nil or oy ~= nil) and "saved-offsets"
                or ((isLegacyFreeMode and legacyPosition ~= nil) and "legacy-free-default" or "anchor-only")
            local shouldMigratePosition = ox ~= nil
                or oy ~= nil
                or (isLegacyFreeMode and legacyPosition ~= nil)
                or ap ~= nil
                or rp ~= nil
            log(
                section
                    .. ": pre-migrate state"
                    .. " anchorMode="
                    .. tostring(cfg.anchorMode)
                    .. " anchorPoint="
                    .. tostring(ap)
                    .. " relativePoint="
                    .. tostring(rp)
                    .. " offsetX="
                    .. tostring(ox)
                    .. " offsetY="
                    .. tostring(oy)
            )
            if shouldMigratePosition then
                if type(cfg.editModePositions) ~= "table" then
                    cfg.editModePositions = {}
                end
                local point, x, y = normalizeEditModePosition(
                    sourcePoint,
                    sourceRelativePoint,
                    sourceX,
                    sourceY,
                    UIParent
                )
                local didNormalize = sourcePoint ~= sourceRelativePoint
                local migrated = {
                    point = point,
                    x = x,
                    y = y,
                }
                local seeded = {}
                local preserved = {}
                for _, layoutName in ipairs(allLayouts) do
                    if cfg.editModePositions[layoutName] == nil then
                        cfg.editModePositions[layoutName] = {
                            point = migrated.point,
                            x = migrated.x,
                            y = migrated.y,
                        }
                        seeded[#seeded + 1] = layoutName
                    else
                        preserved[#preserved + 1] = layoutName
                    end
                end
                if #seeded > 0 then
                    log(
                        section
                            .. ": migrated to editModePositions["
                            .. table.concat(seeded, ", ")
                            .. "] point="
                            .. migrated.point
                            .. " x="
                            .. migrated.x
                            .. " y="
                            .. migrated.y
                            .. " source="
                            .. migrationSource
                            .. " normalized="
                            .. tostring(didNormalize)
                    )
                end
                if #preserved > 0 then
                    log(section .. ": preserved existing editModePositions[" .. table.concat(preserved, ", ") .. "]")
                end
                cfg.offsetX = nil
                cfg.offsetY = nil
            else
                log(section .. ": no legacy free-mode position found, skipping")
            end
            cfg.anchorPoint = nil
            cfg.relativePoint = nil
        else
            log(section .. ": section missing or not a table")
        end
    end
end

-- V11 → V12: convert itemIcons boolean flags to extraIcons.viewers structure.
-- Old format: itemIcons = { enabled, showTrinket1, showTrinket2, showCombatPotion, showHealthPotion, showHealthstone }
-- New format: extraIcons = { enabled, viewers = { utility = { {stackKey=...}, {kind="itemStack", itemStackId=...}, ... }, main = {} } }
-- Frozen snapshot: flag names and built-in item stack IDs are inlined constants.
_migrations[12] = function(profile)
    local old = profile.itemIcons
    if type(old) ~= "table" then
        log("V12 no itemIcons section found; ensuring default extraIcons")
        profile.extraIcons = profile.extraIcons or {
            enabled = true,
            viewers = {
                utility = {
                    { stackKey = "trinket1" },
                    { stackKey = "trinket2" },
                    { kind = "itemStack", itemStackId = "combatPotions" },
                    { kind = "itemStack", itemStackId = "healthPotions" },
                    { kind = "itemStack", itemStackId = "healthstones" },
                },
                main = {},
            },
        }
        profile.itemIcons = nil
        return
    end

    local enabled = old.enabled
    if enabled == nil then
        enabled = true
    end

    -- Map old boolean flags to viewer entries in display order.
    local FLAG_TO_ENTRY = {
        { flag = "showTrinket1",     entry = { stackKey = "trinket1" } },
        { flag = "showTrinket2",     entry = { stackKey = "trinket2" } },
        { flag = "showCombatPotion", entry = { kind = "itemStack", itemStackId = "combatPotions" } },
        { flag = "showHealthPotion", entry = { kind = "itemStack", itemStackId = "healthPotions" } },
        { flag = "showHealthstone",  entry = { kind = "itemStack", itemStackId = "healthstones" } },
    }

    local utilityEntries = {}
    for _, mapping in ipairs(FLAG_TO_ENTRY) do
        local flagValue = old[mapping.flag]
        if flagValue == nil or flagValue == true then
            utilityEntries[#utilityEntries + 1] = mapping.entry
        end
    end

    profile.extraIcons = {
        enabled = enabled,
        viewers = {
            utility = utilityEntries,
            main = {},
        },
    }

    local migrated = {}
    for _, entry in ipairs(utilityEntries) do
        migrated[#migrated + 1] = entry.stackKey or entry.itemStackId
    end
    log("V12 migrated itemIcons -> extraIcons.viewers.utility: [" .. table.concat(migrated, ", ") .. "]")

    profile.itemIcons = nil
end

local function makeDefaultItemStacks()
    return {
        nextId = 1,
        order = { "combatPotions", "healthPotions", "healthstones" },
        byId = {
            combatPotions = {
                name = "Combat Potions",
                hideInInstances = false,
                hideInRatedPvp = true,
                ids = {
                    { itemID = 245898, quality = 2 },
                    { itemID = 245897, quality = 1 },
                    { itemID = 241308, quality = 2 },
                    { itemID = 241309, quality = 1 },
                },
            },
            healthPotions = {
                name = "Health Potions",
                hideInInstances = false,
                hideInRatedPvp = true,
                ids = {
                    { itemID = 241305, quality = 2 },
                    { itemID = 241304, quality = 1 },
                    { itemID = 258138, quality = 1 },
                },
            },
            healthstones = {
                name = "Healthstones",
                hideInInstances = false,
                hideInRatedPvp = false,
                ids = {
                    { itemID = 224464 },
                    { itemID = 5512 },
                },
            },
        },
    }
end

local function ensureDefaultItemStack(itemStacks, stackId, defaults)
    if itemStacks.byId[stackId] then
        return
    end
    itemStacks.byId[stackId] = defaults.byId[stackId]
    itemStacks.order[#itemStacks.order + 1] = stackId
end

-- V12 → V13: add named item stacks referenced by Extra Icons viewer rows.
_migrations[13] = function(profile)
    profile.extraIcons = profile.extraIcons or {}
    local defaults = makeDefaultItemStacks()
    local itemStacks = profile.extraIcons.itemStacks
    if type(itemStacks) ~= "table" then
        profile.extraIcons.itemStacks = defaults
        log("V13 initialized extraIcons.itemStacks")
        return
    end

    if type(itemStacks.byId) ~= "table" then
        itemStacks.byId = {}
    end
    if type(itemStacks.order) ~= "table" then
        itemStacks.order = {}
        for stackId in pairs(itemStacks.byId) do
            itemStacks.order[#itemStacks.order + 1] = stackId
        end
        table.sort(itemStacks.order, function(a, b)
            if type(a) == "number" and type(b) == "number" then return a < b end
            return tostring(a) < tostring(b)
        end)
    end
    if type(itemStacks.nextId) ~= "number" then
        local nextId = 1
        for stackId in pairs(itemStacks.byId) do
            if type(stackId) == "number" and stackId >= nextId then
                nextId = stackId + 1
            end
        end
        itemStacks.nextId = nextId
    end
    ensureDefaultItemStack(itemStacks, "combatPotions", defaults)
    ensureDefaultItemStack(itemStacks, "healthPotions", defaults)
    ensureDefaultItemStack(itemStacks, "healthstones", defaults)
    log("V13 preserved extraIcons.itemStacks")
end

--- Runs all schema migrations on a profile from its current version to CURRENT_SCHEMA_VERSION.
---@param profile table The profile to migrate
function Migration.Run(profile)
    if not profile.schemaVersion then
        return
    end

    local startVersion = profile.schemaVersion
    if startVersion >= ns.Constants.CURRENT_SCHEMA_VERSION then
        return
    end

    log("Starting migration from V" .. startVersion .. " to V" .. ns.Constants.CURRENT_SCHEMA_VERSION)

    for version = startVersion + 1, ns.Constants.CURRENT_SCHEMA_VERSION do
        local step = _migrations[version]
        if step then
            step(profile)
            profile.schemaVersion = version
            log("Migrated to V" .. version)
        end
    end

    log("Migration complete (V" .. startVersion .. " -> V" .. profile.schemaVersion .. ")")
end

--------------------------------------------------------------------------------
-- Versioned SavedVariable Setup
--------------------------------------------------------------------------------

--- Finds the highest schema version stored in the versions sub-table.
---@param versions table The _versions sub-table.
---@param belowVersion number Only consider versions below this number.
---@return number|nil bestVersion The highest version found, or nil.
local function findBestPriorVersion(versions, belowVersion)
    local best = nil
    for k in pairs(versions) do
        if type(k) == "number" and k < belowVersion and (not best or k > best) then
            best = k
        end
    end
    return best
end

--- Prepares the versioned SavedVariable store and points a temporary global at
--- the current schema version's data for AceDB to use.
---
--- Structure of SV_NAME (persisted by WoW):
---   {
---     profiles    = {…},          -- legacy AceDB data (untouched by new code)
---     profileKeys = {…},          -- legacy AceDB data (untouched by new code)
---     _versions   = {
---       [7] = {profiles=…, profileKeys=…},
---       [8] = {…},
---       [9] = {…},
---     },
---   }
---
--- Old addon versions read the top-level profiles/profileKeys (legacy data).
--- New code reads from _versions[CURRENT_SCHEMA_VERSION] via ACTIVE_SV_KEY.
--- AceDB ignores the _versions key since it only manages known namespace keys.
---
--- Must be called BEFORE AceDB:New().
function Migration.PrepareDatabase()
    local sv = _G[ns.Constants.SV_NAME] or {}
    _G[ns.Constants.SV_NAME] = sv

    sv._versions = sv._versions or {}
    local versions = sv._versions
    local version = ns.Constants.CURRENT_SCHEMA_VERSION

    -- Seed the current version's slot if it doesn't exist yet
    if not versions[version] then
        -- Try the most recent prior version in the store
        local priorVersion = findBestPriorVersion(versions, version)
        if priorVersion and versions[priorVersion] then
            log("Copying from schema V" .. priorVersion .. " to V" .. version)
            versions[version] = cloneValue(versions[priorVersion])
            alignSlotProfileSchemas(versions[version], priorVersion)
        elseif sv.profiles then
            -- Seed from legacy top-level AceDB data (pre-versioning addon builds)
            local hasProfiles = next(sv.profiles) ~= nil

            if hasProfiles then
                log("Copying legacy profiles to versioned store V" .. version)
                versions[version] = {
                    profiles = cloneValue(sv.profiles),
                    profileKeys = sv.profileKeys and cloneValue(sv.profileKeys) or nil,
                }
            end
        end

        -- Fresh install — empty sub-table, AceDB will populate with defaults
        if not versions[version] then
            versions[version] = {}
        end
    end

    -- Point the temporary global at the current version's sub-table.
    -- AceDB modifies this table in place, so changes are persisted when WoW
    -- serializes SV_NAME on logout.
    rawset(_G, ns.Constants.ACTIVE_SV_KEY, versions[version])
end

--- Persists collected migration log entries into the current version's SV slot.
--- Should be called after PrepareDatabase + Run are complete.
function Migration.FlushLog()
    if #migrationLog == 0 then
        return
    end

    local sv = _G[ns.Constants.SV_NAME]
    local versions = sv and sv._versions
    local slot = versions and versions[ns.Constants.CURRENT_SCHEMA_VERSION]
    if not slot then
        return
    end

    slot._migrationLog = slot._migrationLog or {}
    local dest = slot._migrationLog
    for _, entry in ipairs(migrationLog) do
        dest[#dest + 1] = entry
    end

    wipe(migrationLog)
end

--- Returns the migration log as a single string, or nil if empty/missing.
---@return string|nil
function Migration.GetLogText()
    local sv = _G[ns.Constants.SV_NAME]
    local versions = sv and sv._versions
    local slot = versions and versions[ns.Constants.CURRENT_SCHEMA_VERSION]
    local entries = slot and slot._migrationLog
    if not entries or #entries == 0 then
        return nil
    end

    return table.concat(entries, "\n")
end

function Migration.PrintInfo()
    ns.Print("Current schema version: V" .. ns.Constants.CURRENT_SCHEMA_VERSION)

    local sv = _G[ns.Constants.SV_NAME]
    local versions = sv and sv._versions
    local keys = {}
    if versions then
        for k in pairs(versions) do
            if type(k) == "number" then
                keys[#keys + 1] = k
            end
        end
        table.sort(keys)
    end

    if #keys == 0 then
        ns.Print("No versioned settings found.")
    else
        local labels = {}
        for i, k in ipairs(keys) do
            labels[i] = "V" .. k
        end
        ns.Print("Available versions: " .. table.concat(labels, ", "))
    end

    ns.Print("Commands:")
    ns.Print("  /ecm migration - show migration info")
    ns.Print("  /ecm migration log - show the settings migration log")
    ns.Print("  /ecm migration rollback <n> - rollback to version n (-1 = delete current only)")
end

--- Validates whether a rollback to the given target version is possible.
---@param targetVersion number|nil  Lowest version to keep.
---@return boolean valid
---@return string message
function Migration.ValidateRollback(targetVersion)
    local sv = _G[ns.Constants.SV_NAME]
    local versions = sv and sv._versions
    if not versions then
        return false, "No versioned settings found."
    end

    if targetVersion ~= nil and (type(targetVersion) ~= "number" or targetVersion ~= math.floor(targetVersion)) then
        return false, "Target version must be a whole number."
    end

    local current = ns.Constants.CURRENT_SCHEMA_VERSION
    local floor = targetVersion or (current - 1)

    if floor >= current then
        return false, "Target version must be less than the current version (V" .. current .. ")."
    end

    if floor < 1 then
        return false, "Target version must be at least 1."
    end

    local hasSeedVersion = false
    for k in pairs(versions) do
        if type(k) == "number" and k <= floor then
            hasSeedVersion = true
            break
        end
    end

    if not hasSeedVersion then
        return false, "No prior version at or below V" .. floor .. " exists to restore from."
    end

    -- Build the list of versions that would be deleted
    local toDelete = {}
    for v = floor + 1, current do
        if versions[v] then
            toDelete[#toDelete + 1] = "V" .. v
        end
    end

    if #toDelete == 0 then
        return false, "No version slots to delete above V" .. floor .. "."
    end

    return true, "Will delete " .. table.concat(toDelete, ", ") .. " and re-migrate from V" .. floor .. "."
end

--- Deletes schema version slots to force re-migration on next reload.
--- Call ValidateRollback first to check feasibility.
---@param targetVersion number|nil  Lowest version to keep. Must be < CURRENT_SCHEMA_VERSION.
function Migration.Rollback(targetVersion)
    local sv = _G[ns.Constants.SV_NAME]
    local versions = sv and sv._versions
    if not versions then
        return
    end

    if targetVersion ~= nil and (type(targetVersion) ~= "number" or targetVersion ~= math.floor(targetVersion)) then
        return
    end

    local current = ns.Constants.CURRENT_SCHEMA_VERSION
    local floor = targetVersion or (current - 1)

    for v = floor + 1, current do
        versions[v] = nil
    end
end