Init.lua

-- PETAL runtime bootstrap and saved-variable compatibility.
--
-- This file deliberately has no UI dependencies.  UI.lua can load after the
-- runtime files and use the methods on PETAL without needing to know
-- which Retail APIs are available on the current client.

local ADDON_NAME, PRIVATE = ...
local _G = _G

if type(PRIVATE) ~= "table" then
    PRIVATE = {}
end

local APS = _G.PETAL
if not APS then
    APS = CreateFrame("Frame")
    _G.PETAL = APS
end

PRIVATE.APS = APS
APS.NS = PRIVATE
APS.ADDON_NAME = ADDON_NAME or "PETAL"
APS.RUNTIME_SCHEMA = 4

-- The tag editor is a simpler view over the existing rule pools.  Rule IDs
-- remain canonical so existing selections survive the schema-4 migration and
-- older import/export helpers can continue to address the same records.
APS.CONDITION_TAGS = {
    { id = "city",         label = "City",         ruleID = "cities",      context = "city",         priority = 200 },
    { id = "dungeon",      label = "Dungeon",      ruleID = "dungeons",    context = "dungeon",      priority = 300 },
    { id = "raid",         label = "Raid",         ruleID = "raids",       context = "raid",         priority = 400 },
    { id = "openworld",    label = "Open world",   ruleID = "solo",        context = "solo",         priority = 100 },
    { id = "neighborhood", label = "Neighborhood", ruleID = "neighborhood", context = "neighborhood", priority = 500 },
}

local CONDITION_TAG_BY_ID = {}
local CONDITION_TAG_BY_RULE = {}
for _, definition in ipairs(APS.CONDITION_TAGS) do
    CONDITION_TAG_BY_ID[definition.id] = definition
    CONDITION_TAG_BY_RULE[definition.ruleID] = definition
end
CONDITION_TAG_BY_ID.cities = CONDITION_TAG_BY_ID.city
CONDITION_TAG_BY_ID.dungeons = CONDITION_TAG_BY_ID.dungeon
CONDITION_TAG_BY_ID.raids = CONDITION_TAG_BY_ID.raid
CONDITION_TAG_BY_ID.solo = CONDITION_TAG_BY_ID.openworld
CONDITION_TAG_BY_ID.open_world = CONDITION_TAG_BY_ID.openworld
CONDITION_TAG_BY_ID.neighbourhood = CONDITION_TAG_BY_ID.neighborhood

-- Keep these names intentionally stable.  Older versions stored minutes at
-- the top level, while the new UI may use the seconds aliases or SetSetting.
APS.DEFAULTS = APS.DEFAULTS or {
    enabled = true,
    checkIntervalSeconds = 300,
    intervalMinutes = 5,
    dismissGraceSeconds = 600,
    dismissGraceMinutes = 10,
    dismissGraceEnabled = true,
    disableInInstances = false,
    fullRandom = false,
    randomMode = "selected",
    randomShuffleEnabled = false,
    randomShuffleMinMinutes = 15,
    randomShuffleMaxMinutes = 30,
    darkMode = false,
    selectedPets = {},
    rules = {},
    activeProfile = "default",
    debug = false,
}

APS._runtime = APS._runtime or {}
local R = APS._runtime
R.loaded = R.loaded or false
R.db = R.db or nil
R.petPoolRevision = R.petPoolRevision or 0
R.fullRandomPool = R.fullRandomPool or nil
R.contextOverrides = R.contextOverrides or {}
R.lastSettingValues = R.lastSettingValues or {}

local function isSecret(value)
    local checker = _G.issecretvalue
    if type(checker) ~= "function" then
        return false
    end
    local ok, secret = pcall(checker, value)
    return ok and secret == true
end

function APS:IsSecret(value)
    return isSecret(value)
end

local function safeNumber(value)
    if isSecret(value) then
        return nil
    end
    local number = tonumber(value)
    if number and number == number then
        return number
    end
    return nil
end

local function safeString(value)
    if isSecret(value) or value == nil then
        return nil
    end
    if type(value) == "string" then
        return value
    end
    return nil
end

local function speciesCountKey(speciesID)
    speciesID = safeNumber(speciesID)
    if not speciesID or speciesID <= 0 then return nil end
    return tostring(math.floor(speciesID))
end

-- Requested roster GUIDs are readable even though Retail 12 can return a
-- secret GUID for the active pet. Resolve the stable, readable species ID
-- before summoning and use that identity for the user-visible history.
local function petSpeciesID(petID)
    if isSecret(petID) or (type(petID) ~= "string" and type(petID) ~= "number") then
        return nil
    end
    local journal = _G.C_PetJournal
    if not journal then return nil end
    if type(journal.GetPetInfoTableByPetID) == "function" then
        local ok, info = pcall(journal.GetPetInfoTableByPetID, petID)
        if ok and not isSecret(info) and type(info) == "table" then
            local speciesID = safeNumber(info.speciesID)
            if speciesID then return math.floor(speciesID) end
        end
    end
    if type(journal.GetPetInfoByPetID) == "function" then
        local ok, speciesID = pcall(journal.GetPetInfoByPetID, petID)
        speciesID = ok and safeNumber(speciesID) or nil
        if speciesID then return math.floor(speciesID) end
    end
    return nil
end

function APS:GetPetSpeciesID(petID)
    return petSpeciesID(petID)
end

local function migrateLegacySummonCounts(db)
    -- Unreadable saved history must be preserved intact. A later safe pass can
    -- resume migration without Petal replacing values it was unable to inspect.
    if isSecret(db.petSummonCountsBySpecies) or isSecret(db.petSummonCounts) then
        return false
    end
    for _, history in ipairs({ db.petSummonCountsBySpecies, db.petSummonCounts }) do
        if type(history) == "table" then
            for historyKey, historyValue in pairs(history) do
                if isSecret(historyKey) or isSecret(historyValue) then
                    return false
                end
            end
        end
    end
    local speciesCounts = {}
    if type(db.petSummonCountsBySpecies) == "table" and not isSecret(db.petSummonCountsBySpecies) then
        for speciesID, count in pairs(db.petSummonCountsBySpecies) do
            local key = speciesCountKey(speciesID)
            local clean = not isSecret(count) and math.max(0, math.floor(safeNumber(count) or 0)) or 0
            if key and clean > 0 then
                speciesCounts[key] = (speciesCounts[key] or 0) + clean
            end
        end
    end

    local unresolved = {}
    if type(db.petSummonCounts) == "table" and not isSecret(db.petSummonCounts) then
        for petID, count in pairs(db.petSummonCounts) do
            local clean = not isSecret(count) and math.max(0, math.floor(safeNumber(count) or 0)) or 0
            local speciesID = clean > 0 and petSpeciesID(petID) or nil
            local key = speciesCountKey(speciesID)
            if key then
                speciesCounts[key] = (speciesCounts[key] or 0) + clean
            elseif clean > 0 and not isSecret(petID) and (type(petID) == "string" or type(petID) == "number") then
                unresolved[tostring(petID)] = clean
            end
        end
    end

    db.petSummonCountsBySpecies = speciesCounts
    db.petSummonCounts = unresolved
    db.petSummonCountsMigrationComplete = next(unresolved) == nil
    return true
end

local function resolveConditionTag(tag)
    if type(tag) == "table" and not isSecret(tag) then
        tag = tag.id or tag.tag or tag.ruleID
    end
    tag = safeString(tag)
    if not tag then return nil end
    tag = string.lower(tag):gsub("[%s%-]", "_")
    return CONDITION_TAG_BY_ID[tag] or CONDITION_TAG_BY_RULE[tag]
end

local function copyValue(value, depth)
    if depth and depth > 8 then
        return nil
    end
    if isSecret(value) then
        return nil
    end
    if type(value) ~= "table" then
        return value
    end
    local result = {}
    depth = (depth or 0) + 1
    for key, child in pairs(value) do
        if not isSecret(key) then
            local copied = copyValue(child, depth)
            if copied ~= nil then
                result[key] = copied
            end
        end
    end
    return result
end

APS.Copy = copyValue

function APS:Clamp(value, minimum, maximum, fallback)
    value = safeNumber(value)
    if not value then
        return fallback
    end
    if minimum and value < minimum then
        value = minimum
    end
    if maximum and value > maximum then
        value = maximum
    end
    return value
end

function APS:Now()
    local getter = _G.GetTimePreciseSec or _G.GetTime
    if type(getter) ~= "function" then
        return 0
    end
    local ok, value = pcall(getter)
    value = ok and safeNumber(value) or nil
    return value or 0
end

function APS:SafeCall(object, method, ...)
    if not object or type(object[method]) ~= "function" then
        return false
    end
    local ok, a, b, c, d, e, f = pcall(object[method], ...)
    if not ok then
        return false
    end
    return true, a, b, c, d, e, f
end

function APS:Debug(...)
    local db = R.db or _G.PETALDB
    if not db or db.debug ~= true then
        return
    end
    local printer = _G.print
    if type(printer) == "function" then
        printer("|cffc7b7ffPETAL:|r", ...)
    end
end

local function bool(value, fallback)
    if value == nil or isSecret(value) then
        return fallback
    end
    return not not value
end

local function copyPetSelection(value)
    local result = {}
    if type(value) ~= "table" or isSecret(value) then
        return result
    end

    -- Both the old map form ({[petGUID] = true}) and the friendly UI list
    -- form ({petGUID1, petGUID2}) are accepted.  Pet IDs are always strings
    -- in Retail, but retaining numeric keys here keeps malformed data from
    -- crashing migration; the picker will reject them later.
    for key, selected in pairs(value) do
        if not isSecret(key) and not isSecret(selected) and selected then
            local petID = key
            if type(key) == "number" and type(selected) == "string" then
                petID = selected
            end
            if type(petID) == "string" or type(petID) == "number" then
                result[petID] = true
            end
        end
    end
    return result
end

local function looksLikeRule(record)
    return type(record) == "table" and (
        record.pool ~= nil or record.petPool ~= nil or record.pets ~= nil or
        record.selectedPets ~= nil or record.context ~= nil or
        record.contexts ~= nil or record.conditions ~= nil or
        record.priority ~= nil or record.name ~= nil
    )
end

local function normalisePool(pool, fallbackPets, fallbackMode)
    local result = {}
    if type(pool) == "string" then
        result.mode = pool
    elseif type(pool) == "table" and not isSecret(pool) then
        result = pool
    end

    local mode = safeString(result.mode or result.type or result.selection or result.randomMode)
    if not mode then
        mode = fallbackMode
    end
    mode = string.lower(mode or "selected")
    if mode == "all" or mode == "fullrandom" or mode == "full_random" or mode == "random_all" then
        mode = "full"
    elseif mode == "random" or mode == "shuffle" or mode == "selectedrandom" then
        mode = "selected"
        result.random = true
    elseif mode ~= "selected" and mode ~= "favorite" and mode ~= "favorites" then
        mode = "selected"
    end
    result.mode = mode
    if mode == "favorites" then
        result.mode = "favorite"
    end

    local pets = result.pets or result.petIDs or result.petIds or result.selectedPets
    if pets == nil then
        pets = fallbackPets
    end
    result.pets = copyPetSelection(pets)
    result.petIDs = result.pets -- Alias for the UI and import/export callers.
    result.random = bool(result.random, false)
    return result
end

local function normaliseRule(rule, index, fallbackPets, fallbackMode)
    if type(rule) ~= "table" or isSecret(rule) then
        return nil
    end
    local result = rule
    result.id = safeString(result.id or result.key or result.profileID or result.profileId)
        or ("rule-" .. tostring(index))
    result.name = safeString(result.name or result.title or result.label) or ("Pet plan " .. tostring(index))
    result.enabled = not isSecret(result.enabled) and result.enabled ~= false
    result.priority = APS:Clamp(result.priority, -100000, 100000, 0)
    result.order = APS:Clamp(result.order, 1, 1000000, index)

    local sourcePool = result.pool or result.petPool
    if not sourcePool and (result.pets or result.selectedPets) then
        sourcePool = result
    end
    result.pool = normalisePool(sourcePool, fallbackPets, fallbackMode)
    result.petPool = result.pool
    -- Friendly aliases used by the journal UI and by import/export tools.
    -- Keep the map in the runtime pool, while petIDs is an uncomplicated
    -- ordered list for checkboxes and previews.
    result.petIDs = {}
    for petID, selected in pairs(result.pool.pets or {}) do
        if selected then
            result.petIDs[#result.petIDs + 1] = petID
        end
    end

    -- A single context is the most ergonomic representation, while the
    -- matcher also accepts contexts/conditions written by future UI versions.
    if result.context == nil and result.contextKey ~= nil then
        result.context = result.contextKey
    end
    if result.context == nil then
        local legacyContext = result.conditionType or result.condition or result.type or result.kind
        if type(legacyContext) == "string" then
            local key = string.lower(legacyContext)
            local aliases = {
                party = "dungeon", instance = "dungeon", instances = "dungeon",
                dungeon = "dungeon", raid = "raid", raids = "raid",
                adventure = "solo", outdoor = "solo", solo = "solo",
                city = "city", capital = "city", town = "city",
                neighborhood = "neighborhood", neighbourhood = "neighborhood",
                housing = "neighborhood", outfit = "outfit", profile = "profile",
            }
            result.context = aliases[key] or legacyContext
        end
    end
    if result.contexts == nil and result.context ~= nil then
        result.contexts = { result.context }
    end
    if result.conditions == nil and type(result.when) == "table" then
        result.conditions = result.when
    end
    return result
end

local function copyRuleList(source, fallbackPets, fallbackMode)
    local result = {}
    if type(source) ~= "table" or isSecret(source) then
        return result
    end

    local arrayCount = 0
    for key, value in pairs(source) do
        if type(key) == "number" and type(value) == "table" then
            arrayCount = arrayCount + 1
        end
    end

    if arrayCount > 0 then
        for index = 1, #source do
            local rule = normaliseRule(source[index], index, fallbackPets, fallbackMode)
            if rule then
                result[#result + 1] = rule
            end
        end
    else
        local index = 0
        for key, value in pairs(source) do
            if type(value) == "table" and not isSecret(value) then
                index = index + 1
                local rule = normaliseRule(value, index, fallbackPets, fallbackMode)
                if rule then
                    if not rule.id or rule.id == "rule-" .. tostring(index) then
                        rule.id = safeString(key) or rule.id
                    end
                    result[#result + 1] = rule
                end
            end
        end
    end
    return result
end

local function ensureDefaultRule(db, selectedPets, fallbackMode)
    if type(db.rules) ~= "table" or #db.rules == 0 then
        db.rules = {
            {
                id = "everywhere",
                name = "Everywhere",
                label = "Everywhere",
                description = "Fallback pet roster.",
                enabled = true,
                priority = -100,
                order = 1,
                contexts = { any = true },
                pool = normalisePool(nil, selectedPets, fallbackMode),
                behavior = { keepIfCurrentIsEligible = true, switchOnMomentChange = false },
            },
            {
                id = "dungeons", name = "Dungeons", label = "Dungeons",
                description = "Pets for dungeons.", enabled = false,
                priority = 80, order = 2, contexts = { "dungeon" },
                pool = normalisePool(nil, {}, "selected"),
                behavior = { keepIfCurrentIsEligible = true, switchOnMomentChange = false },
            },
            {
                id = "raids", name = "Raids", label = "Raids",
                description = "Pets for raids.", enabled = false,
                priority = 80, order = 3, contexts = { "raid" },
                pool = normalisePool(nil, {}, "selected"),
                behavior = { keepIfCurrentIsEligible = true, switchOnMomentChange = false },
            },
            {
                id = "solo", name = "Open world", label = "Open world",
                description = "Pets for open-world zones.", enabled = false,
                priority = 60, order = 4, contexts = { "solo" },
                pool = normalisePool(nil, {}, "selected"),
                behavior = { keepIfCurrentIsEligible = true, switchOnMomentChange = false },
            },
            {
                id = "cities", name = "City", label = "City",
                description = "Pets for cities.", enabled = false,
                priority = 50, order = 5, contexts = { "city" },
                pool = normalisePool(nil, {}, "selected"),
                behavior = { keepIfCurrentIsEligible = true, switchOnMomentChange = false },
            },
            {
                id = "neighborhood", name = "Neighborhood", label = "Neighborhood",
                description = "Pets for neighborhoods.", enabled = false,
                priority = 50, order = 6, contexts = { "neighborhood" },
                pool = normalisePool(nil, {}, "selected"),
                behavior = { keepIfCurrentIsEligible = true, switchOnMomentChange = false },
            },
            {
                id = "outfit", name = "Outfit match", label = "Outfit match",
                description = "Legacy outfit-based pet set.", enabled = false,
                priority = 70, order = 7, contexts = { "outfit" },
                pool = normalisePool(nil, {}, "selected"),
                behavior = { keepIfCurrentIsEligible = true, switchOnMomentChange = false },
            },
        }
        for _, rule in ipairs(db.rules) do
            rule.petPool = rule.pool
            rule.petIDs = {}
            for petID, selected in pairs(rule.pool.pets or {}) do
                if selected then rule.petIDs[#rule.petIDs + 1] = petID end
            end
        end
    end
end

-- Older installs may already have a single default/profile rule.  Add the
-- light journal's named Moments once, disabled and editable, without touching
-- any rule the player already owns.
local function ensurePresetRules(db, fallbackMode)
    if type(db.rules) ~= "table" then db.rules = {} end
    local existing = {}
    for _, rule in ipairs(db.rules) do
        if type(rule) == "table" and type(rule.id) == "string" then existing[rule.id] = true end
    end
    local presets = {
        {id = "dungeons", name = "Dungeon", description = "Pets for dungeons.", context = "dungeon", priority = 80},
        {id = "raids", name = "Raid", description = "Pets for raids.", context = "raid", priority = 80},
        {id = "solo", name = "Open world", description = "Pets for open-world zones.", context = "solo", priority = 60},
        {id = "cities", name = "City", description = "Pets for cities.", context = "city", priority = 50},
        {id = "neighborhood", name = "Neighborhood", description = "Pets for neighborhoods.", context = "neighborhood", priority = 50},
        {id = "outfit", name = "Outfit match", description = "Legacy outfit-based pet set.", context = "outfit", priority = 70},
    }
    for _, preset in ipairs(presets) do
        if not existing[preset.id] then
            local rule = {
                id = preset.id, name = preset.name, label = preset.name,
                description = preset.description, enabled = false,
                priority = preset.priority, order = #db.rules + 1,
                contexts = { preset.context },
                pool = normalisePool(nil, {}, "selected"),
                behavior = { keepIfCurrentIsEligible = true, switchOnMomentChange = false },
            }
            rule.petPool = rule.pool
            rule.petIDs = {}
            db.rules[#db.rules + 1] = rule
            existing[preset.id] = true
        end
    end
end

local function selectionCount(pets)
    local count = 0
    if type(pets) ~= "table" or isSecret(pets) then return count end
    for petID, selected in pairs(pets) do
        if not isSecret(petID) and not isSecret(selected) and selected then
            count = count + 1
        end
    end
    return count
end

local function findRuleInDB(db, wanted)
    wanted = safeString(wanted)
    if not wanted then return nil end
    wanted = string.lower(wanted)
    for _, rule in ipairs(db.rules or {}) do
        if type(rule) == "table" and not isSecret(rule) then
            local id = safeString(rule.id or rule.key or rule.name)
            if id and string.lower(id) == wanted then
                return rule
            end
        end
    end
    return nil
end

local function syncRulePool(rule, pets, mode)
    if type(rule) ~= "table" then return end
    rule.pool = normalisePool(rule.pool, pets, mode or "selected")
    rule.pool.pets = pets
    rule.pool.petIDs = pets
    rule.petPool = rule.pool
    rule.pets = pets
    rule.petIDs = {}
    for petID, selected in pairs(pets or {}) do
        if selected then rule.petIDs[#rule.petIDs + 1] = petID end
    end
end

local function configureTagRule(rule, definition)
    if type(rule) ~= "table" or type(definition) ~= "table" then return end
    local pets = copyPetSelection(rule.pool and (rule.pool.pets or rule.pool.petIDs) or rule.pets)
    syncRulePool(rule, pets, "shuffle")
    rule.pool.mode = "shuffle"
    rule.pool.randomMode = "shuffle"
    rule.pool.random = true
    rule.mode = "shuffle"
    rule.context = definition.context
    rule.contexts = { definition.context }
    rule.priority = definition.priority
    rule.enabled = selectionCount(pets) > 0
    rule.behavior = type(rule.behavior) == "table" and rule.behavior or {}
    rule.behavior.keepIfCurrentIsEligible = true
    rule.behavior.switchOnMomentChange = true
    rule.switchOnMomentChange = true
end

local function ensureTagModel(db)
    db.tagMode = true

    local roster = copyPetSelection(db.selectedPets)
    local existingFallback = findRuleInDB(db, "everywhere") or findRuleInDB(db, "default")
    local fallbackPets = existingFallback and existingFallback.pool and existingFallback.pool.pets
    for petID, selected in pairs(copyPetSelection(fallbackPets)) do
        if selected then roster[petID] = true end
    end
    for _, definition in ipairs(APS.CONDITION_TAGS) do
        local rule = findRuleInDB(db, definition.ruleID)
        if not rule then
            rule = {
                id = definition.ruleID,
                key = definition.ruleID,
                name = definition.label,
                label = definition.label,
                order = #db.rules + 1,
                pool = normalisePool(nil, {}, "shuffle"),
            }
            db.rules[#db.rules + 1] = rule
        end
        configureTagRule(rule, definition)
        for petID, selected in pairs(rule.pool.pets or {}) do
            if selected then roster[petID] = true end
        end
    end

    db.selectedPets = roster
    local everywhere = findRuleInDB(db, "everywhere")
    if not everywhere then
        everywhere = {
            id = "everywhere", key = "everywhere", name = "Everywhere", label = "Everywhere",
            order = #db.rules + 1, contexts = { any = true }, pool = normalisePool(nil, roster, "shuffle"),
        }
        db.rules[#db.rules + 1] = everywhere
    end
    syncRulePool(everywhere, roster, "shuffle")
    everywhere.pool.mode = "shuffle"
    everywhere.pool.randomMode = "shuffle"
    everywhere.pool.random = true
    everywhere.mode = "shuffle"
    everywhere.enabled = selectionCount(roster) > 0
    everywhere.priority = -100
    everywhere.context = nil
    everywhere.contexts = { any = true }
    everywhere.behavior = type(everywhere.behavior) == "table" and everywhere.behavior or {}
    everywhere.behavior.keepIfCurrentIsEligible = true
    everywhere.behavior.switchOnMomentChange = false
    everywhere.switchOnMomentChange = false
end

function APS:NormalizeDB()
    local db = _G.PETALDB
    if type(db) ~= "table" or isSecret(db) then
        db = {}
        _G.PETALDB = db
    end

    local oldSchema = safeNumber(db.schemaVersion or db.dbVersion or db.version) or 0
    local oldSelectedPets = copyPetSelection(db.selectedPets)

    -- Preserve the legacy profile/condition records by promoting them into
    -- ordered rules only when a newer rules list does not already exist.
    local sourceRules = db.rules
    if type(sourceRules) ~= "table" or #sourceRules == 0 then
        if type(db.profiles) == "table" then
            sourceRules = db.profiles
        elseif type(db.conditions) == "table" then
            sourceRules = db.conditions
        elseif looksLikeRule(db.profile) then
            sourceRules = { db.profile }
        end
    end

    local fullRandom = bool(db.fullRandom, nil)
    if fullRandom == nil and type(db.settings) == "table" then
        fullRandom = bool(db.settings.fullRandom, nil)
    end
    local randomMode = safeString(db.randomMode)
    if not randomMode and type(db.settings) == "table" then
        randomMode = safeString(db.settings.randomMode)
    end
    if fullRandom == true then
        randomMode = "full"
    end
    randomMode = string.lower(randomMode or "selected")
    if randomMode == "all" or randomMode == "fullrandom" or randomMode == "full_random" then
        randomMode = "full"
    elseif randomMode ~= "full" then
        randomMode = "selected"
    end

    local rules = copyRuleList(sourceRules, oldSelectedPets, randomMode)
    db.rules = rules
    ensureDefaultRule(db, oldSelectedPets, randomMode)
    ensurePresetRules(db, randomMode)

    -- Keep the original selection map intact in canonical form.  UI callers
    -- can continue to toggle db.selectedPets while rule-aware callers use the
    -- default pool; SetSelectedPets below updates both representations.
    db.selectedPets = oldSelectedPets
    ensureTagModel(db)

    -- Petal-owned summon history is deliberately separate from the roster and
    -- rules. It is informative only, never participates in selection.
    migrateLegacySummonCounts(db)

    local settings = db.settings
    if type(settings) ~= "table" or isSecret(settings) then
        settings = {}
        db.settings = settings
    end

    local function setting(name, legacyName, fallback)
        local value = db[name]
        if value == nil then
            value = settings[name]
        end
        if value == nil and legacyName then
            value = db[legacyName]
        end
        if value == nil or isSecret(value) then
            value = fallback
        end
        db[name] = value
        settings[name] = value
        R.lastSettingValues[name] = value
        return value
    end

    setting("enabled", nil, APS.DEFAULTS.enabled)
    setting("debug", nil, APS.DEFAULTS.debug)
    setting("disableInInstances", nil, APS.DEFAULTS.disableInInstances)
    setting("dismissGraceEnabled", nil, APS.DEFAULTS.dismissGraceEnabled)
    setting("fullRandom", nil, randomMode == "full")
    setting("randomMode", nil, randomMode)
    setting("randomShuffleEnabled", nil, APS.DEFAULTS.randomShuffleEnabled)
    setting("darkMode", nil, APS.DEFAULTS.darkMode)
    local shuffleMin = self:Clamp(safeNumber(setting("randomShuffleMinMinutes", nil, APS.DEFAULTS.randomShuffleMinMinutes)), 1, 1440, APS.DEFAULTS.randomShuffleMinMinutes)
    local shuffleMax = self:Clamp(safeNumber(setting("randomShuffleMaxMinutes", nil, APS.DEFAULTS.randomShuffleMaxMinutes)), shuffleMin, 1440, APS.DEFAULTS.randomShuffleMaxMinutes)
    db.randomShuffleMinMinutes = shuffleMin
    settings.randomShuffleMinMinutes = shuffleMin
    db.randomShuffleMaxMinutes = shuffleMax
    settings.randomShuffleMaxMinutes = shuffleMax

    -- Dungeon and Raid are first-class tags in schema 4. The retired legacy
    -- restriction would silently prevent both from working, so tag mode
    -- migrates it off instead of retaining a contradictory hidden setting.
    if db.tagMode then
        db.disableInInstances = false
        settings.disableInInstances = false
        R.lastSettingValues.disableInInstances = false
    end

    local intervalSeconds = safeNumber(db.checkIntervalSeconds)
    if not intervalSeconds then
        intervalSeconds = safeNumber(settings.checkIntervalSeconds)
    end
    if not intervalSeconds then
        local legacyMinutes = safeNumber(db.intervalMinutes or settings.intervalMinutes)
        intervalSeconds = legacyMinutes and legacyMinutes * 60 or APS.DEFAULTS.checkIntervalSeconds
    end
    intervalSeconds = self:Clamp(intervalSeconds, 15, 3600, APS.DEFAULTS.checkIntervalSeconds)
    db.checkIntervalSeconds = intervalSeconds
    settings.checkIntervalSeconds = intervalSeconds
    db.intervalMinutes = intervalSeconds / 60
    settings.intervalMinutes = db.intervalMinutes

    local graceSeconds = safeNumber(db.dismissGraceSeconds)
    if not graceSeconds then
        graceSeconds = safeNumber(settings.dismissGraceSeconds)
    end
    if not graceSeconds then
        local legacyMinutes = safeNumber(db.dismissGraceMinutes or settings.dismissGraceMinutes)
        graceSeconds = legacyMinutes and legacyMinutes * 60 or APS.DEFAULTS.dismissGraceSeconds
    end
    graceSeconds = self:Clamp(graceSeconds, 0, 86400, APS.DEFAULTS.dismissGraceSeconds)
    db.dismissGraceSeconds = graceSeconds
    settings.dismissGraceSeconds = graceSeconds
    db.dismissGraceMinutes = graceSeconds / 60
    settings.dismissGraceMinutes = db.dismissGraceMinutes

    local activeProfile = safeString(db.activeProfile)
    if not activeProfile then
        activeProfile = safeString(db.profileKey) or safeString(settings.activeProfile) or "default"
    end
    db.activeProfile = activeProfile
    settings.activeProfile = activeProfile

    -- A numeric marker makes migration idempotent and gives support tooling a
    -- clear way to distinguish legacy data from the current contract.  Keep a
    -- few historical aliases for import/export tools that used them.
    db.schemaVersion = self.RUNTIME_SCHEMA
    db.dbVersion = self.RUNTIME_SCHEMA
    db.version = self.RUNTIME_SCHEMA
    if oldSchema < self.RUNTIME_SCHEMA and db._migratedFromSchema == nil then
        db._migratedFromSchema = oldSchema
    end

    R.db = db
    R.petPoolRevision = (R.petPoolRevision or 0) + 1
    R.fullRandomPool = nil
    R.loaded = true
    return db
end

-- Short alias used by diagnostics/import tools that only know the generic
-- migration verb.  NormalizeDB remains the canonical entry point.
function APS:Normalize()
    return self:NormalizeDB()
end

function APS:GetDB()
    if not R.db or R.db ~= _G.PETALDB then
        return self:NormalizeDB()
    end
    return R.db
end

function APS:GetSetting(name, fallback)
    local db = self:GetDB()
    local value = db[name]
    if value == nil and type(db.settings) == "table" then
        value = db.settings[name]
    end
    if value == nil or isSecret(value) then
        return fallback
    end
    return value
end

function APS:SetSetting(name, value)
    local db = self:GetDB()
    db[name] = value
    if type(db.settings) ~= "table" then
        db.settings = {}
    end
    db.settings[name] = value
    R.lastSettingValues[name] = value
    if name == "intervalMinutes" then
        local minutes = self:Clamp(value, 0.25, 60, APS.DEFAULTS.intervalMinutes)
        db.intervalMinutes = minutes
        db.checkIntervalSeconds = minutes * 60
        db.settings.intervalMinutes = minutes
        db.settings.checkIntervalSeconds = db.checkIntervalSeconds
    elseif name == "checkIntervalSeconds" then
        local seconds = self:Clamp(value, 15, 3600, APS.DEFAULTS.checkIntervalSeconds)
        db.checkIntervalSeconds = seconds
        db.intervalMinutes = seconds / 60
        db.settings.checkIntervalSeconds = seconds
        db.settings.intervalMinutes = db.intervalMinutes
    elseif name == "dismissGraceMinutes" then
        local minutes = self:Clamp(value, 0, 1440, APS.DEFAULTS.dismissGraceMinutes)
        db.dismissGraceMinutes = minutes
        db.dismissGraceSeconds = minutes * 60
        db.settings.dismissGraceMinutes = minutes
        db.settings.dismissGraceSeconds = db.dismissGraceSeconds
    elseif name == "dismissGraceSeconds" then
        local seconds = self:Clamp(value, 0, 86400, APS.DEFAULTS.dismissGraceSeconds)
        db.dismissGraceSeconds = seconds
        db.dismissGraceMinutes = seconds / 60
        db.settings.dismissGraceSeconds = seconds
        db.settings.dismissGraceMinutes = db.dismissGraceMinutes
    elseif name == "fullRandom" then
        db.fullRandom = not isSecret(value) and value == true
        db.randomMode = db.fullRandom and "full" or "selected"
        db.settings.fullRandom = db.fullRandom
        db.settings.randomMode = db.randomMode
    elseif name == "randomMode" then
        db.randomMode = value == "full" and "full" or "selected"
        db.fullRandom = db.randomMode == "full"
        db.settings.randomMode = db.randomMode
        db.settings.fullRandom = db.fullRandom
    elseif name == "randomShuffleMinMinutes" or name == "randomShuffleMaxMinutes" then
        local minimum = self:Clamp(value, 1, 1440, APS.DEFAULTS.randomShuffleMinMinutes)
        local maximum = self:Clamp(db.randomShuffleMaxMinutes, 1, 1440, APS.DEFAULTS.randomShuffleMaxMinutes)
        if name == "randomShuffleMaxMinutes" then
            maximum = self:Clamp(value, 1, 1440, APS.DEFAULTS.randomShuffleMaxMinutes)
            minimum = self:Clamp(db.randomShuffleMinMinutes, 1, maximum, APS.DEFAULTS.randomShuffleMinMinutes)
        else
            maximum = self:Clamp(maximum, minimum, 1440, APS.DEFAULTS.randomShuffleMaxMinutes)
        end
        db.randomShuffleMinMinutes = minimum
        db.randomShuffleMaxMinutes = maximum
        db.settings.randomShuffleMinMinutes = minimum
        db.settings.randomShuffleMaxMinutes = maximum
    end
    if name == "enabled" then
        if self.ResetScheduler then self:ResetScheduler() end
        if value == true and self.RequestEvaluation then
            self:RequestEvaluation(0.05, "addon enabled")
        end
    elseif name == "randomShuffleEnabled" or name == "randomShuffleMinMinutes" or name == "randomShuffleMaxMinutes" then
        if self.ResetShuffleScheduler then self:ResetShuffleScheduler() end
    elseif name == "disableInInstances" and self.RequestEvaluation then
        self:RequestEvaluation(0.05, "instance preference changed")
    end
    return value
end

local function syncEverywhereRoster(db)
    local everywhere = findRuleInDB(db, "everywhere")
    if not everywhere then return end
    syncRulePool(everywhere, db.selectedPets, "shuffle")
    everywhere.pool.mode = "shuffle"
    everywhere.pool.randomMode = "shuffle"
    everywhere.pool.random = true
    everywhere.mode = "shuffle"
    everywhere.enabled = selectionCount(db.selectedPets) > 0
    everywhere.priority = -100
end

local function finishPetPoolChange(self, reason)
    R.petPoolRevision = (R.petPoolRevision or 0) + 1
    R.fullRandomPool = nil
    if self.RequestEvaluation then
        self:RequestEvaluation(0.05, reason or "selection changed")
    end
end

function APS:GetSelectedRoster()
    return copyPetSelection(self:GetDB().selectedPets)
end

function APS:GetPetSummonCount(speciesID)
    local key = speciesCountKey(speciesID)
    if not key then return 0 end
    local db = self:GetDB()
    if not migrateLegacySummonCounts(db) then return 0 end
    local counts = db.petSummonCountsBySpecies
    local count = type(counts) == "table" and counts[key] or 0
    return math.max(0, math.floor(safeNumber(count) or 0))
end

function APS:RecordPetSummon(petID, speciesID)
    speciesID = safeNumber(speciesID) or petSpeciesID(petID)
    local key = speciesCountKey(speciesID)
    local db = self:GetDB()
    if not migrateLegacySummonCounts(db) then return 0 end

    local counts
    local countKey
    if key then
        if type(db.petSummonCountsBySpecies) ~= "table" then
            db.petSummonCountsBySpecies = {}
        end
        counts = db.petSummonCountsBySpecies
        countKey = key
    elseif not isSecret(petID) and (type(petID) == "string" or type(petID) == "number") then
        if type(db.petSummonCounts) ~= "table" then
            db.petSummonCounts = {}
        end
        counts = db.petSummonCounts
        countKey = tostring(petID)
    else
        return 0
    end

    local existing = math.max(0, math.floor(safeNumber(counts[countKey]) or 0))
    local nextCount = existing + 1
    counts[countKey] = nextCount
    db.lastPetalSummon = {
        petID = not isSecret(petID) and petID or nil,
        speciesID = key and math.floor(speciesID) or nil,
    }
    return nextCount
end

function APS:GetLastPetalSummonRecord()
    local db = self:GetDB()
    if not migrateLegacySummonCounts(db) then return nil end
    local record = db.lastPetalSummon
    if type(record) ~= "table" or isSecret(record) then return nil end

    local petID = not isSecret(record.petID) and record.petID or nil
    if type(petID) ~= "string" and type(petID) ~= "number" then petID = nil end
    local speciesID = safeNumber(record.speciesID) or petSpeciesID(petID)
    local speciesKey = speciesCountKey(speciesID)
    local count = 0
    if speciesKey and type(db.petSummonCountsBySpecies) == "table" then
        count = safeNumber(db.petSummonCountsBySpecies[speciesKey]) or 0
    elseif petID and type(db.petSummonCounts) == "table" then
        count = safeNumber(db.petSummonCounts[tostring(petID)]) or 0
    end
    count = math.max(0, math.floor(count))
    if count <= 0 then return nil end

    if speciesKey and record.speciesID ~= math.floor(speciesID) then
        record.speciesID = math.floor(speciesID)
    end
    return {
        petID = petID,
        speciesID = speciesKey and math.floor(speciesID) or nil,
        count = count,
    }
end

function APS:IsPetSelected(petID)
    if isSecret(petID) then return false end
    local selected = self:GetDB().selectedPets
    return type(selected) == "table" and selected[petID] == true
end

function APS:SetSelectedPets(pets, rule)
    local db = self:GetDB()
    local selected = copyPetSelection(pets)
    local definition = type(rule) == "table" and resolveConditionTag(rule.id or rule.key) or nil

    if definition then
        syncRulePool(rule, selected, "shuffle")
        configureTagRule(rule, definition)
        for petID, enabled in pairs(selected) do
            if enabled then db.selectedPets[petID] = true end
        end
    else
        db.selectedPets = selected
        -- Removing a pet from the roster also removes every conditional tag.
        for _, tag in ipairs(APS.CONDITION_TAGS) do
            local tagRule = findRuleInDB(db, tag.ruleID)
            if tagRule then
                local tagged = copyPetSelection(tagRule.pool and tagRule.pool.pets)
                for petID in pairs(tagged) do
                    if not selected[petID] then tagged[petID] = nil end
                end
                syncRulePool(tagRule, tagged, "shuffle")
                configureTagRule(tagRule, tag)
            end
        end
    end
    syncEverywhereRoster(db)
    finishPetPoolChange(self, "selection changed")
    return copyPetSelection(db.selectedPets)
end

function APS:SetPetSelected(petID, selected)
    if isSecret(petID) or (type(petID) ~= "string" and type(petID) ~= "number") then
        return false
    end
    local db = self:GetDB()
    if not isSecret(selected) and selected == true then
        db.selectedPets[petID] = true
    else
        db.selectedPets[petID] = nil
        for _, definition in ipairs(APS.CONDITION_TAGS) do
            local rule = findRuleInDB(db, definition.ruleID)
            if rule then
                local pets = copyPetSelection(rule.pool and rule.pool.pets)
                pets[petID] = nil
                syncRulePool(rule, pets, "shuffle")
                configureTagRule(rule, definition)
            end
        end
    end
    syncEverywhereRoster(db)
    finishPetPoolChange(self, "roster changed")
    return db.selectedPets[petID] == true
end

function APS:GetPetTags(petID)
    local result = {}
    if isSecret(petID) then return result end
    for _, definition in ipairs(APS.CONDITION_TAGS) do
        local rule = findRuleInDB(self:GetDB(), definition.ruleID)
        local pets = rule and rule.pool and rule.pool.pets
        if type(pets) == "table" and pets[petID] == true then
            result[#result + 1] = definition.id
            result[definition.id] = true
        end
    end
    return result
end

function APS:GetTaggedPetIDs(tag)
    local definition = resolveConditionTag(tag)
    local result = {}
    if not definition then return result end
    local rule = findRuleInDB(self:GetDB(), definition.ruleID)
    local pets = rule and rule.pool and rule.pool.pets
    if type(pets) ~= "table" then return result end
    for petID, selected in pairs(pets) do
        if selected and not isSecret(petID) then
            result[#result + 1] = petID
            result[petID] = true
        end
    end
    table.sort(result, function(a, b) return tostring(a) < tostring(b) end)
    return result
end

function APS:SetPetTag(petID, tag, enabled)
    local definition = resolveConditionTag(tag)
    if not definition or isSecret(petID) or (type(petID) ~= "string" and type(petID) ~= "number") then
        return false
    end
    local db = self:GetDB()
    local rule = findRuleInDB(db, definition.ruleID)
    if not rule then return false end
    local pets = copyPetSelection(rule.pool and rule.pool.pets)
    local add = not isSecret(enabled) and enabled == true
    if add then
        pets[petID] = true
        db.selectedPets[petID] = true
    else
        pets[petID] = nil
    end
    syncRulePool(rule, pets, "shuffle")
    configureTagRule(rule, definition)
    syncEverywhereRoster(db)
    finishPetPoolChange(self, "pet tag changed")
    return true, pets[petID] == true
end

-- Apply a complete condition set in one saved-data change.  The Tags page
-- uses this for its compact ALL control so a single click cannot briefly
-- evaluate a half-updated collection or queue five separate refreshes.
function APS:SetPetTags(petIDs, tagStates)
    local targets, seen = {}, {}
    local function addTarget(petID)
        if isSecret(petID) or (type(petID) ~= "string" and type(petID) ~= "number") then
            return
        end
        local key = tostring(petID)
        if not seen[key] then
            seen[key] = true
            targets[#targets + 1] = petID
        end
    end
    if type(petIDs) == "string" or type(petIDs) == "number" then
        addTarget(petIDs)
    elseif type(petIDs) == "table" then
        for _, petID in ipairs(petIDs) do addTarget(petID) end
    end
    if #targets == 0 then return false end

    local db = self:GetDB()
    for _, definition in ipairs(APS.CONDITION_TAGS) do
        local rule = findRuleInDB(db, definition.ruleID)
        if rule then
            local pets = copyPetSelection(rule.pool and rule.pool.pets)
            local enabled = type(tagStates) == "table" and tagStates[definition.id] == true
            for _, petID in ipairs(targets) do
                if enabled then
                    pets[petID] = true
                    db.selectedPets[petID] = true
                else
                    pets[petID] = nil
                end
            end
            syncRulePool(rule, pets, "shuffle")
            configureTagRule(rule, definition)
        end
    end
    syncEverywhereRoster(db)
    finishPetPoolChange(self, "pet tags changed")
    return true
end

local function ruleIDEquals(rule, wanted)
    if type(rule) ~= "table" or wanted == nil or isSecret(wanted) then
        return false
    end
    local id = rule.id or rule.key or rule.name
    if isSecret(id) then return false end
    return id == wanted or (type(id) == "string" and type(wanted) == "string" and string.lower(id) == string.lower(wanted))
end

local function ruleContextForID(id)
    local key = type(id) == "string" and string.lower(id) or ""
    local contexts = {
        dungeons = "dungeon", dungeon = "dungeon", raids = "raid", raid = "raid",
        solo = "solo", adventure = "solo", cities = "city", city = "city",
        neighborhood = "neighborhood", neighbourhood = "neighborhood",
        outfit = "outfit", profile = "profile",
    }
    return contexts[key]
end

function APS:GetRules()
    local db = self:GetDB()
    return db.rules or {}
end

function APS:FindRule(ruleID, create)
    local db = self:GetDB()
    for _, rule in ipairs(db.rules or {}) do
        if ruleIDEquals(rule, ruleID) then
            return rule
        end
    end
    if not create or type(ruleID) ~= "string" or ruleID == "" then
        return nil
    end
    local rule = {
        id = ruleID,
        key = ruleID,
        name = ruleID,
        label = ruleID,
        enabled = false,
        priority = 100,
        order = #db.rules + 1,
        contexts = {},
        pool = normalisePool(nil, db.selectedPets, db.randomMode == "full" and "full" or "selected"),
    }
    local context = ruleContextForID(ruleID)
    if context then
        rule.contexts = { context }
    else
        rule.contexts = { any = true }
    end
    rule.petPool = rule.pool
    rule.petIDs = {}
    for petID, selected in pairs(rule.pool.pets or {}) do
        if selected then rule.petIDs[#rule.petIDs + 1] = petID end
    end
    db.rules[#db.rules + 1] = rule
    return rule
end

function APS:SetRuleEnabled(ruleID, enabled)
    local rule = self:FindRule(ruleID, true)
    if not rule then return false end
    local definition = resolveConditionTag(ruleID)
    if definition then
        configureTagRule(rule, definition)
    else
        rule.enabled = not isSecret(enabled) and enabled == true
    end
    if self.RequestEvaluation then self:RequestEvaluation(0.05, "rule enabled changed") end
    return rule.enabled
end

function APS:SetRulePets(ruleID, pets)
    local rule = self:FindRule(ruleID, true)
    if not rule then return false end
    local selected = copyPetSelection(pets)
    local db = self:GetDB()

    local definition = resolveConditionTag(ruleID)
    if definition then
        syncRulePool(rule, selected, "shuffle")
        configureTagRule(rule, definition)
        for petID, enabled in pairs(selected) do
            if enabled then db.selectedPets[petID] = true end
        end
        syncEverywhereRoster(db)
        finishPetPoolChange(self, "rule pets changed")
        return true
    end
    if rule.id == "default" or rule.id == "everywhere" then
        self:SetSelectedPets(selected)
        return true
    end

    rule.pool = normalisePool(rule.pool, selected, rule.pool and rule.pool.mode or "selected")
    rule.pool.pets = selected
    rule.pool.petIDs = selected
    rule.petPool = rule.pool
    rule.pets = selected
    rule.petIDs = {}
    for petID, enabled in pairs(selected) do
        if enabled then rule.petIDs[#rule.petIDs + 1] = petID end
    end
    finishPetPoolChange(self, "rule pets changed")
    return true
end

function APS:SetRuleMode(ruleID, mode)
    local rule = self:FindRule(ruleID, true)
    if not rule then return false end
    local definition = resolveConditionTag(ruleID)
    if definition then
        configureTagRule(rule, definition)
        if self.RequestEvaluation then self:RequestEvaluation(0.05, "rule mode changed") end
        return "shuffle"
    end
    mode = type(mode) == "string" and string.lower(mode) or "selected"
    if mode == "all" or mode == "fullrandom" or mode == "full_random" or mode == "random_all" then
        mode = "full"
    elseif mode == "random" or mode == "selectedrandom" then
        mode = "shuffle"
    elseif mode == "favorites" then
        mode = "favorite"
    elseif mode ~= "full" and mode ~= "favorite" and mode ~= "shuffle" then
        mode = "selected"
    end
    local shuffle = mode == "shuffle"
    rule.pool = rule.pool or {}
    rule.pool.mode = mode
    rule.pool.randomMode = mode
    rule.pool.random = shuffle
    rule.mode = mode
    rule.petPool = rule.pool
    if self.RequestEvaluation then self:RequestEvaluation(0.05, "rule mode changed") end
    return mode
end

function APS:SetRuleSwitchOnMomentChange(ruleID, enabled)
    local rule = self:FindRule(ruleID, true)
    if not rule then return false end
    local definition = resolveConditionTag(ruleID)
    if definition then
        configureTagRule(rule, definition)
        if self.RequestEvaluation then self:RequestEvaluation(0.05, "moment behavior changed") end
        return true
    end
    rule.behavior = type(rule.behavior) == "table" and rule.behavior or {}
    rule.behavior.switchOnMomentChange = not isSecret(enabled) and enabled == true
    -- Keep the friendly alias available to import/export callers.
    rule.switchOnMomentChange = rule.behavior.switchOnMomentChange
    if self.RequestEvaluation then self:RequestEvaluation(0.05, "moment behavior changed") end
    return rule.behavior.switchOnMomentChange
end

function APS:RefreshRules()
    if self.InvalidatePetPool then self:InvalidatePetPool() end
    if self.RequestEvaluation then self:RequestEvaluation(0.05, "rules refreshed") end
end

function APS:SetEnabled(enabled)
    return self:SetSetting("enabled", not isSecret(enabled) and enabled == true)
end

function APS:SetDisableInInstances(disabled)
    return self:SetSetting("disableInInstances", not isSecret(disabled) and disabled == true)
end

function APS:SetContextOverride(key, value)
    key = safeString(key)
    if not key then
        return false
    end
    if value == nil then
        R.contextOverrides[key] = nil
    else
        R.contextOverrides[key] = value
    end
    if self.RequestEvaluation then
        self:RequestEvaluation(0.05, "context override changed")
    end
    return true
end

function APS:GetContextOverride(key)
    return R.contextOverrides[key]
end

function APS:SetActiveProfile(profile, profileID)
    self:SetContextOverride("profile", profile)
    self:SetContextOverride("profileKey", profile)
    if profileID ~= nil then
        self:SetContextOverride("profileID", profileID)
    end
    return profile
end

function APS:SetOutfit(outfit, outfitID)
    self:SetContextOverride("outfit", outfit)
    if outfitID ~= nil then
        self:SetContextOverride("outfitID", outfitID)
    end
    return outfit
end

-- A small compatibility surface for UI code written before the runtime was
-- split into files.
function APS:IsEnabled()
    local enabled = self:GetSetting("enabled", true)
    return not isSecret(enabled) and enabled == true
end

function APS:GetIntervalSeconds()
    local db = self:GetDB()
    -- The light journal writes the legacy minutes field directly.  Prefer it
    -- when present so a settings edit is reflected immediately, while the
    -- seconds alias remains available to API callers.
    local minutes = safeNumber(db.intervalMinutes)
    if minutes and minutes == minutes then
        return self:Clamp(minutes * 60, 15, 3600, APS.DEFAULTS.checkIntervalSeconds)
    end
    return self:Clamp(self:GetSetting("checkIntervalSeconds", APS.DEFAULTS.checkIntervalSeconds), 15, 3600, APS.DEFAULTS.checkIntervalSeconds)
end

function APS:GetRandomShuffleRangeSeconds()
    local db = self:GetDB()
    if self:GetSetting("randomShuffleEnabled", false) ~= true then
        return nil, nil
    end
    local minimum = self:Clamp(safeNumber(db.randomShuffleMinMinutes), 1, 1440, APS.DEFAULTS.randomShuffleMinMinutes)
    local maximum = self:Clamp(safeNumber(db.randomShuffleMaxMinutes), minimum, 1440, APS.DEFAULTS.randomShuffleMaxMinutes)
    return minimum * 60, maximum * 60
end

function APS:GetDismissGraceSeconds()
    if self:GetSetting("dismissGraceEnabled", true) ~= true then
        return 0
    end
    local db = self:GetDB()
    local minutes = safeNumber(db.dismissGraceMinutes)
    if minutes and minutes == minutes then
        return self:Clamp(minutes * 60, 0, 86400, APS.DEFAULTS.dismissGraceSeconds)
    end
    return self:Clamp(self:GetSetting("dismissGraceSeconds", APS.DEFAULTS.dismissGraceSeconds), 0, 86400, APS.DEFAULTS.dismissGraceSeconds)
end