Scanner.lua

-- TOG Profession Master — Profession & Cooldown Scanner
-- Author: Pimptasty
--
-- Responsibilities:
--   • Listen for trade-skill / craft window events and scan the open profession.
--   • Scan all known profession cooldown spells on login and on window events.
--   • Store results in AceDB (factionrealm scope, keyed by "Name-Realm").
--   • Broadcast own data to the guild via DeltaSync-1.0.
--   • Receive and merge incoming guild-member data back into AceDB.

local _, addon = ...
local Ace = addon.lib   -- the AceAddon object created in TOGProfessionMaster.lua
local L   = LibStub("AceLocale-3.0"):GetLocale("TOGProfessionMaster")

-- ---------------------------------------------------------------------------
-- Module object
-- ---------------------------------------------------------------------------

local Scanner = {}
addon.Scanner = Scanner

--- Has `sender` gone offline since the broadcast we are answering?
---
--- ONE implementation, because there were THREE and only one of them was ever
--- asserted. Every outbound `DS:RequestData` is gated on this: DeltaSync has its
--- own internal offline check, but that races with GUILD_ROSTER_UPDATE
--- propagation, so gating here catches the common case where LibGuildRoster has
--- already seen the transition. Mirrors TOGBankClassic's DeltaComms pattern --
--- every send site gets a guard before dispatch.
---
--- **False when no roster library is loaded**, which is deliberate and is the
--- reason this is a named function rather than an inline `and`: with no roster we
--- know nothing about who is online, and refusing to send on the strength of
--- knowing nothing would disable sync entirely rather than protect it.
function Scanner:PeerIsOffline(sender)
    local GR = self.GuildRoster
    return (GR and not GR:IsOnline(sender)) and true or false
end

-- DELETED 2026-08-19: `GetReagentScraper` and its `_reagentScraper` upvalue.
-- A hidden GameTooltip ("TOGPMReagentScraper") built to scrape reagent item
-- links when GetTradeSkillReagentItemLink / GetCraftReagentItemLink return nil
-- on Classic Era. It had NO CALLER -- luacheck's `unused function` found it, and
-- the whole-repo lint that surfaced that had been unreadable behind ~90
-- undeclared-global warnings, which is how it survived. Whatever replaced the
-- scrape path did so without taking the frame with it. If the link APIs are ever
-- seen failing again, this is the shape the fix took, but write it back with a
-- caller attached.

-- ---------------------------------------------------------------------------
-- Module-scope merge helpers (reused by ScanTradeSkillInto, ScanCraftSkillInto,
-- and the v0.2.0 OnGuildDataReceived per-leaf merges).
-- ---------------------------------------------------------------------------

local function asString(v) return type(v) == "string" and v or nil end

-- Non-destructively merge an incoming reagent array into our existing one.
-- Preserves itemId/itemLink per-reagent when the incoming payload lacks them.
-- Returns nil when incoming is not a table so callers can preserve existing.
local function mergeReagents(existing, incoming)
    if type(incoming) ~= "table" then return nil end
    local byName = {}
    if type(existing) == "table" then
        for _, e in ipairs(existing) do
            if e.name then byName[e.name] = e end
        end
    end
    local merged = {}
    for i, inE in ipairs(incoming) do
        local entry = {
            name     = inE.name,
            count    = inE.count,
            itemId   = inE.itemId,
            itemLink = asString(inE.itemLink),
        }
        local prev = entry.name and byName[entry.name]
        if prev then
            if (not entry.itemId or entry.itemId == 0)
               and prev.itemId and prev.itemId > 0 then
                entry.itemId = prev.itemId
            end
            if not entry.itemLink and type(prev.itemLink) == "string"
               and prev.itemLink ~= "" then
                entry.itemLink = prev.itemLink
            end
        end
        merged[i] = entry
    end
    return merged
end

-- Returns a clean human-readable recipe name.  Classic Era's GetTradeSkillInfo
-- can return placeholder text like "? 10002" when the underlying item info
-- hasn't loaded into the client cache yet (typical for long-tail recipes the
-- player hasn't seen recently).  Item links always carry the real name in
-- their [...] field, even when the trade-skill window hasn't loaded the item
-- name — so when the raw name is one of those placeholders, extract from
-- itemLink (preferred) or recipeLink.  Falls through to the raw value if
-- nothing better is available.
local function isBogusName(n)
    if type(n) ~= "string" or n == "" then return true end
    -- "? 10002", "?10002", "? " — Classic Era placeholder forms
    if n:match("^%?") then return true end
    return false
end

-- True when a name looks like a Blizzard internal/dev/placeholder string
-- that should never reach the player. Used to catch the spell-id / item-id
-- namespace collision in MergeCraftersIntoGdb and BackfillBogusRecipeNames:
-- GetItemInfo(spellId) sometimes returns a real (but obsolete/QA) ItemSparse
-- entry whose ID happens to match a recipe's spellId. Example: spell 26926
-- = "Heavy Copper Ring" (Jewelcrafting); item 26926 = "59 TEST Green Shaman
-- Chest". Without this guard the stub gets cached with the TEST name and
-- every render shows it. Mirror of _OBSOLETE_NAME_PATTERNS in
-- tools/build_authoritative_data.py — keep the two in sync.
local function isObsoleteItemName(n)
    if type(n) ~= "string" or n == "" then return false end
    if n:find("%f[%w]TEST%f[%W]")       then return true end  -- "59 TEST ..."
    if n:find("%f[%w]QA%f[%W]")         then return true end
    if n:lower():find("%f[%w]deprecated%f[%W]") then return true end
    if n:lower():find("%f[%w]unused%f[%W]")     then return true end
    if n:lower():match("^zz")            then return true end  -- "ZZOLD Design: ..."
    -- "[ph]" is matched PLAINLY, so it must be written plainly: with the plain
    -- flag set, string.find treats the pattern literally, so the escaped form
    -- "%[ph%]" searched for a percent sign followed by a bracket and never
    -- matched anything. Every "Manual: … [PH]" placeholder sailed through this
    -- filter and persisted in SavedVariables.
    if n:lower():find("[ph]", 1, true) then return true end  -- "Manual: ... [PH]"
    if n:lower():match("%s+old$")        then return true end  -- "Pattern: ... OLD"
    return false
end

local function extractNameFromLink(link)
    if type(link) ~= "string" then return nil end
    local name = link:match("%[(.-)%]")
    if name and name ~= "" and not isBogusName(name) then return name end
    return nil
end

local function cleanRecipeName(rawName, itemLink, recipeLink)
    if not isBogusName(rawName) then return rawName end
    return extractNameFromLink(itemLink)
        or extractNameFromLink(recipeLink)
        or rawName
end

-- ---------------------------------------------------------------------------
-- Offline-test seam — the pure name/reagent helpers above. `local` because
-- nothing outside this file calls them; not used at runtime.
-- See Tests/scanner_names_spec.lua.
-- ---------------------------------------------------------------------------
Scanner._mergeReagents       = mergeReagents
Scanner._isBogusName         = isBogusName
Scanner._isObsoleteItemName  = isObsoleteItemName
Scanner._extractNameFromLink = extractNameFromLink
Scanner._cleanRecipeName     = cleanRecipeName

-- Broadcast state
Scanner._pendingBroadcast = false
Scanner._lastBroadcastAt  = 0
-- Hard minimum between guild broadcasts (seconds). Dynamically sized by
-- Scanner:ScheduleAddonUserRecount based on the number of guildmates running
-- the addon (sourced from a VersionCheck-1.0 batch). Linear scale clamped to
-- [3, 30]: small guilds (or solo testing) get a 3s floor so post-scan recipe
-- hashes propagate quickly; large active guilds with many addon users keep
-- the 30s ceiling to protect the GUILD addon-message channel from saturation.
-- Default of 30 is in effect until the first recount lands ~21s after PEW.
Scanner._broadcastSeconds = 30

-- DeltaSync + GuildRoster LibStub handles (assigned in InitDeltaSync)
Scanner.DS         = nil
Scanner.GuildRoster = nil

-- ---------------------------------------------------------------------------
-- English profession name → skill line ID
-- Used as a fallback for linked professions that aren't in GetProfessions().
-- Game-data facts; locale-specific servers share the same IDs but may have
-- different string keys.  Additional locale strings can be appended without
-- affecting logic.
-- ---------------------------------------------------------------------------

local PROF_NAME_TO_ID = {
    ["Alchemy"]        = 171,
    ["Archaeology"]    = 794,   -- Cata+ gathering profession (skill-line scan)
    ["Blacksmithing"]  = 164,
    ["Cooking"]        = 185,
    ["Enchanting"]     = 333,
    ["Engineering"]    = 202,
    ["First Aid"]      = 129,
    ["Fishing"]        = 356,
    ["Herbalism"]      = 182,
    ["Inscription"]    = 773,
    ["Jewelcrafting"]  = 755,
    ["Leatherworking"] = 165,
    ["Mining"]         = 186,
    ["Skinning"]       = 393,
    ["Tailoring"]      = 197,
}

-- ---------------------------------------------------------------------------
-- Cross-guild sister-roster sync (v0.10.1)
-- ---------------------------------------------------------------------------
-- RosterSync (in DeltaSync) pulls an allied guild's roster over whispers and
-- writes it into LibGuildRoster's sister-roster store, then fires
-- onSisterRosterUpdated. We persist a copy into SavedVariables so the data
-- survives /reload before the next live pull, and re-feed those copies on login.

-- Snapshot a sister guild's roster from LibGuildRoster into SavedVariables.
function Scanner:PersistSisterRoster(guildKey)
    local GR = self.GuildRoster
    if not GR or not GR.GetRoster then return end
    local roster = GR:GetRoster(guildKey)
    if not roster then return end
    local members = {}
    for charKey, m in pairs(roster) do
        members[#members + 1] = {
            name  = charKey,
            class = m and m.class,
            level = m and m.level,
            rank  = m and m.rank,
        }
    end
    local gdb = addon:GetGuildDb()
    if not gdb then return end
    gdb.sisterRosters = gdb.sisterRosters or {}
    gdb.sisterRosters[guildKey] = {
        members = members,
        meta    = (GR.GetRosterMeta and GR:GetRosterMeta(guildKey)) or nil,
        fedAt   = GetServerTime and GetServerTime() or nil,
    }
end

-- Fired by RosterSync after a sister roster lands in LibGuildRoster: persist a
-- copy and refresh the UI.
function Scanner:OnSisterRosterUpdated(guildKey)
    -- Accept gate: only federate rosters for guilds we have configured as
    -- sisters. A roster pushed/served for an unlisted guild is rejected and
    -- removed — nothing cross-guild happens without the guild being on the list.
    if not addon:IsSisterGuildKey(guildKey) then
        local GR = self.GuildRoster
        if GR and GR.RemoveSisterRoster then GR:RemoveSisterRoster(guildKey) end
        addon:DebugPrint("Scanner: rejected unlisted sister roster", guildKey)
        return
    end
    self:PersistSisterRoster(guildKey)
    addon:DebugPrint("Scanner: sister roster updated:", guildKey)
    -- Part B: a fresh pull should reach the rest of the guild quickly rather
    -- than waiting for the periodic tick. Suppression dedupes if others already
    -- hold it. Gossip-relayed rosters apply via addon:OnSisterRosterReceived,
    -- which does NOT route here, so this fires only for our own pulls — no echo.
    if C_Timer and C_Timer.After then
        C_Timer.After(10, function() addon:BroadcastSisterRosters() end)
    end
    if addon.callbacks then
        -- A sister roster landing changes cross-guild membership/attribution.
        addon.callbacks:Fire("GUILD_DATA_UPDATED", "sister:" .. tostring(guildKey),
            { altgroups = true, roster = true })
    end
end

-- Re-feed persisted sister rosters into LibGuildRoster on login so cross-guild
-- queries / the visibility gate work before the first live /who-driven pull.
-- Skips (and forgets) any persisted roster whose guild is no longer on the
-- allied-guild list, so a de-configured guild can't be resurrected on login.
function Scanner:RefeedSisterRosters()
    local GR = self.GuildRoster
    if not GR or not GR.SetSisterRoster then return end
    local gdb = addon:GetGuildDb()
    local stored = gdb and gdb.sisterRosters
    if type(stored) ~= "table" then return end
    local n = 0
    for guildKey, entry in pairs(stored) do
        if not addon:IsSisterGuildKey(guildKey) then
            stored[guildKey] = nil   -- stale: dropped from the list since last save
        elseif type(entry) == "table" and type(entry.members) == "table" then
            GR:SetSisterRoster(guildKey, entry.members, entry.meta)
            n = n + 1
        end
    end
    if n > 0 then addon:DebugPrint("Scanner: re-fed", n, "persisted sister roster(s)") end
end

-- ---------------------------------------------------------------------------
-- ---------------------------------------------------------------------------
-- DeltaSync initialisation
-- Called on PLAYER_ENTERING_WORLD (initial login or UI reload only).
-- ---------------------------------------------------------------------------

function Scanner:InitDeltaSync()
    -- DeltaSync-1.0 and LibGuildRoster-1.0 are declared as ## Dependencies in the
    -- .toc. As of DeltaSync v4.0.0 (LibStub MINOR 15) the library is multi-host:
    -- each consumer creates its OWN isolated host via NewHost instead of the old
    -- singleton DS:Initialize (which kept per-addon state on the one shared LibStub
    -- table, so two DeltaSync consumers in a client clobbered each other,
    -- last-Initialize-wins). We hold our host in Scanner.DS and call everything on
    -- it — every downstream site already reads Scanner.DS / self.DS, so pointing
    -- that field at the host migrates them all.
    local DSlib = LibStub("DeltaSync-1.0", true)
    if not (DSlib and DSlib.NewHost and (DSlib.MINOR or 0) >= 15) then
        -- Missing, or an older / stale DeltaSync won the shared LibStub slot. Do
        -- NOT fall back to DS:Initialize (the singleton path that clobbers) —
        -- disable guild sync. Requires the standalone DeltaSync addon at v4.0.0+.
        addon:DebugPrint("Scanner: DeltaSync-1.0 v4 multi-host (MINOR>=15) not found — guild sync disabled")
        return
    end

    local GuildRoster = LibStub("LibGuildRoster-1.0", true)
    if not GuildRoster then
        addon:DebugPrint("Scanner: LibGuildRoster-1.0 not found — guild sync disabled")
        return
    end

    -- Create our isolated per-host object. Forward-declared so the config
    -- closures below (and InitP2P / guild-mode / roster-sync further down) can
    -- call back into `DS` — Lua captures it by reference as an upvalue, and those
    -- callbacks only fire long after this assignment lands. Everything hereafter
    -- runs on this host; never on the bare DSlib handle.
    local DS
    DS = DSlib:NewHost({
        -- Hand DeltaSync our AceAddon instance so its sends route through
        -- AceComm-3.0 + AceCommQueue-1.0 (embedded onto Ace at the addon
        -- bootstrap in TOGProfessionMaster.lua) instead of falling back to
        -- raw C_ChatInfo.SendAddonMessage. Without this, large chunked
        -- payloads can interleave under sync load and CRC-fail silently.
        aceAddon  = addon.lib,
        namespace = "TOGPmv3",   -- v0.7.0: bare crafters leaf, no recipemeta; was TOGPmv2 in v0.2-v0.6

        -- Delivery verdict (DeltaSync MINOR 17+). WoW silently discards addon
        -- messages under congestion, and AceComm forwards only a boolean — so a
        -- refused send is otherwise indistinguishable from a delivered one, and a
        -- sync that has quietly stopped working looks exactly like an idle one.
        -- DeltaSync counts every send either way; this callback is what turns a
        -- refusal into something visible at the moment it happens. Ignored by an
        -- older library (an unknown config key), so no version gate is needed.
        onSendFailed = function(info)
            Scanner._lastSendFailure = info
            Scanner._sendFailureCount = (Scanner._sendFailureCount or 0) + 1
            addon:DebugPrint("Scanner: send REFUSED — did NOT arrive:",
                info and info.prefix, info and info.distribution,
                info and info.target or "(broadcast)", info and info.bytes, "bytes")
            -- Surface it in the sync log the user can actually see, but only the
            -- first few: a guildless player broadcasting on GUILD would otherwise
            -- generate one line per message forever, which trains people to ignore
            -- the log entirely.
            if addon.callbacks and Scanner._sendFailureCount <= 3 then
                addon.callbacks:Fire("SYNC_SENT", "guild", 0,
                    "|cffff4444REFUSED|r " .. tostring(info and info.channelType or "?")
                    .. " — message did not arrive")
            end
        end,

        -- A guild member is asking us for data.  baseline carries the request
        -- type per the v0.2.0 protocol (see docs/v0.2.0-protocol.md §5):
        --   { type = "subhashes", parent = "guild:cooldowns" | "guild:accountchars" }
        --   { type = "leaf-data", keys  = { itemKey, ... } }
        -- We respond by broadcasting the requested data on GUILD/BULK so any
        -- peer with a stale hash for the same leaf merges for free.
        onDataRequest = function(sender, baseline)
            addon:DebugPrint("Scanner: onDataRequest ENTRY from", sender,
                "type=", baseline and baseline.type or "nil",
                "parent=", baseline and baseline.parent or "nil",
                "keys=", baseline and baseline.keys and #baseline.keys or 0)
            if type(baseline) ~= "table" then
                addon:DebugPrint("Scanner: onDataRequest from", sender, "with no baseline (legacy?), ignoring")
                return
            end
            if baseline.type == "subhashes" and baseline.parent then
                Scanner:BroadcastSubhashesToGuild(baseline.parent)
            elseif baseline.type == "leaf-data" and type(baseline.keys) == "table" then
                local reqGdb   = addon:GetGuildDb()
                local myHashes = (reqGdb and reqGdb.hashes) or {}
                for _, itemKey in ipairs(baseline.keys) do
                    if itemKey:sub(1, 9) == "cooldown:" then
                        -- New-framework cooldown serve: prefer-newer. The requester
                        -- stamps its own updatedAt for this key, or -1 = "I hold nothing"
                        -- (a MISSING stamp is treated as -1 too, so a bare-offer request
                        -- still resolves). Serve when our copy is strictly newer than
                        -- theirs — first acquisition works because their -1 is below any
                        -- real timestamp. If they already hold an equal-or-newer copy
                        -- they wouldn't have requested, so the gate never wrongly
                        -- refuses a legitimate new-client request. This is sound ONLY
                        -- because both sides now carry owner-minted, verbatim-adopted
                        -- timestamps (never recomputed) — the clean break from the
                        -- mixed-version drift that froze v1.0.0. BroadcastLeafToGuild
                        -- no-ops when we hold no backing data.
                        local reqStamp = tonumber(baseline.stamps and baseline.stamps[itemKey]) or -1
                        local mine     = myHashes[itemKey]
                        local myTs     = (mine and mine.updatedAt) or 0
                        if myTs > reqStamp then
                            Scanner:BroadcastLeafToGuild(itemKey)
                        end
                    else
                        Scanner:BroadcastLeafToGuild(itemKey)
                    end
                end
            elseif baseline.type == "player-subhashes" and baseline.profId then
                -- Per-player drill-down under crafters:<profId>: send the per-player
                -- hash list so the requester pulls only the players it differs on.
                Scanner:BroadcastPlayerSubhashes(baseline.profId)
            elseif baseline.type == "player-leaf" and baseline.profId
                   and type(baseline.players) == "table" then
                -- Scoped fetch: emit ONE partial crafters:<profId> leaf PER requested
                -- player, in the order asked (the requester sorts newest-scan first).
                -- Separate messages — rather than one combined leaf — so AceCommQueue
                -- can interleave them with other traffic instead of one big payload
                -- blocking the pipe head-of-line, and the requester's tab paints
                -- incrementally as each player's leaf lands. Same total wire bytes;
                -- better congestion behavior and UX. Each leaf rides the existing
                -- format + merge (own-scan replace when the player IS the sender,
                -- union otherwise — now decided cleanly per single-player leaf).
                local profKey = "crafters:" .. tostring(baseline.profId)
                for _, ck in ipairs(baseline.players) do
                    if type(ck) == "string" then
                        Scanner:BroadcastLeafToGuild(profKey, { [ck] = true })
                    end
                end
            elseif baseline.type == "sister-pull" then
                -- A sister-guild peer is requesting our full guild dataset for
                -- cross-guild sharing. BILATERAL CONSENT GATE: serve only when
                --   (a) WE list THEIR guild  (baseline.parent ∈ our sisters), and
                --   (b) THEY list OUR guild  (our home key ∈ baseline.keys, the
                --       sister-key set they attach as a consent proof).
                -- This makes a one-sided config inert and refuses any stranger /
                -- accidental / malicious puller from a guild we don't federate
                -- with. Respond over WHISPER — they're not on our GUILD channel.
                local reqHome    = baseline.parent
                local reqSisters = (type(baseline.keys) == "table") and baseline.keys or {}
                local myHome     = addon:GetGuildKey()
                local consentOk  = myHome and reqHome
                    and addon:IsSisterGuildKey(reqHome)   -- we consent to them
                    and reqSisters[myHome] and true       -- they consent to us
                -- Anti-spoof: if we ALREADY hold their claimed guild's roster,
                -- the requester must actually be a member of it — defeats a
                -- stranger forging parent/keys for a guild we list. On first
                -- contact (no roster yet) we trust the bilateral-config claim;
                -- the roster is bootstrapped by the (public) roster pull.
                local identityOk = true
                local GR = Scanner.GuildRoster
                if consentOk and GR and GR.GetRoster and GR.IsInGuildScoped then
                    if GR:GetRoster(reqHome) then
                        local who = (GR.NormalizeName and GR:NormalizeName(sender)) or sender
                        if not GR:IsInGuildScoped(who, reqHome) then identityOk = false end
                    end
                end
                if consentOk and identityOk then
                    local payload = Scanner:BuildFullGuildPayload()
                    if payload then DS:SendData(sender, payload, false) end
                else
                    addon:DebugPrint("Scanner: refused sister-pull from", sender,
                        "— gate failed (consent=", tostring(consentOk),
                        "identity=", tostring(identityOk), "reqHome=", tostring(reqHome), ")")
                end
            end
        end,

        -- Incoming guild-member data — either a leaf-data broadcast (one or
        -- more leaves with content) or a subhashes response.  Dispatch is
        -- inside OnGuildDataReceived based on the payload shape.
        onDataReceived = function(sender, data, bytes)
            addon:DebugPrint("Scanner: onDataReceived ENTRY from", sender,
                "bytes=", bytes or 0,
                "type=", data and data.type or "leaves",
                "charKey=", data and data.charKey or "nil")
            Scanner:OnGuildDataReceived(sender, data, bytes or 0)
        end,

        -- onVersionReceived: DeltaSync's own VERSION channel — not used by this
        -- addon (nothing calls DS:BroadcastVersion). Version checking is handled
        -- by VersionCheck-1.0 via a separate comm protocol.
    })

    self.DS         = DS
    self.GuildRoster = GuildRoster

    -- Guild-only sync mode (DeltaSync MINOR >= 13). Some private/emulated servers
    -- (e.g. Whitemane) never deliver addon messages over WHISPER, which silently
    -- breaks DeltaSync's directed channels (QUERY/RESPONSE/DELTA/OFFER/HANDSHAKE):
    -- hash offers go out on GUILD fine, but the follow-up fetch over WHISPER never
    -- lands, so sync gets stuck at "broadcasts out, nothing back". Guild-mode
    -- reroutes those directed channels onto GUILD (each message stamped with its
    -- intended recipient so other members drop it). Opt-in, OFF by default,
    -- persisted in our realm-scoped DB and re-applied on every login. Must be
    -- called AFTER NewHost (channel config has to exist on the host first).
    -- Feature-detected — an older embedded DeltaSync simply has no guild-mode and single-
    -- guild behaviour is unchanged. User toggle: Settings → General → Sync.
    if DS.InitGuildMode then
        local realm = Ace.db and Ace.db.realm
        DS:InitGuildMode({
            enabled   = (realm and realm.guildMode) and true or false,
            onChanged = function(on)
                if Ace.db and Ace.db.realm then
                    Ace.db.realm.guildMode = on and true or false
                end
            end,
        })
        addon:DebugPrint("Scanner: guild-mode available; enabled =",
            (realm and realm.guildMode) and true or false)
    end

    -- Cross-guild ("sister roster") sync. Opt-in / feature-detected: a DeltaSync
    -- build without RosterSync, or a LibGuildRoster without the sister API,
    -- simply skips this and single-guild sync is unaffected. RosterSync owns the
    -- wire and writes received rosters into LibGuildRoster itself; our callback
    -- persists a copy and refreshes the UI. Discovery (/who) and the pull trigger
    -- come in a later step — this wires the plumbing + login re-feed only.
    if DS.InitRosterSync and GuildRoster.SetSisterRoster then
        DS:InitRosterSync({
            onSisterRosterUpdated = function(guildKey)
                Scanner:OnSisterRosterUpdated(guildKey)
            end,
        })
        self:RefeedSisterRosters()
    end

    -- v0.2.0 hash migration: drop legacy v0.1.x leaf keys and ensure all
    -- expected v0.2.0 leaves exist.  Idempotent — safe to run on every PEW.
    -- Run inside a ScheduleTimer so gdb.lastScan has had a chance to populate
    -- (PEW currently stamps lastScan[myKey].accountchars synchronously, but
    -- profession + cooldown timestamps come from later scans; running this
    -- one tick later keeps the migration consistent with whatever's there).
    Ace:ScheduleTimer(function()
        local gdb = addon:GetGuildDb()
        if gdb then addon.HashManager:RebuildOnFirstLoad(DS, gdb) end
    end, 1)

    -- ── P2P catch-up sync (v0.2.0) ───────────────────────────────────────────
    -- L0 broadcast carries per-profession leaves (recipemeta + crafters) plus
    -- two roll-ups (guild:cooldowns, guild:accountchars).  Per-character leaves
    -- are drilled down on roll-up mismatch via a "subhashes" request.
    --
    -- onSyncAccepted: peer has different data for a leaf.  The flow:
    --   1. crafters:<profId> / recipemeta:<profId> mismatch → request the leaf
    --      data directly (it's already at L0 granularity).
    --   2. guild:cooldowns / guild:accountchars roll-up mismatch → request
    --      the per-character sub-hashes from the peer.  The receiver compares
    --      sub-hashes locally and requests individual cooldown:<charKey> /
    --      accountchars:<charKey> leaves.
    --   3. cooldown:<charKey> / accountchars:<charKey> direct mismatch (when
    --      a peer broadcasts these explicitly) → request leaf data.
    DS:InitP2P({
        -- DeltaSync defaults (3 sessions, 3 sends, 10s collect window) are
        -- tuned for small numbers of peers.  In active guilds with 30+ online
        -- members, we end up with the cap saturated by leaf fetches that
        -- back up while peers wait on each other's caps too — sync grinds
        -- to a halt for everything outside the first three slots.  Bump
        -- both inbound and outbound concurrency to 8 and stretch the
        -- collect window to 30s so we accumulate offers from more peers
        -- before picking one (gives a better chance of catching all the
        -- broadcasters that have what we want).
        maxActiveSessions = 8,
        maxActiveSends    = 8,
        collectWindow     = 30,

        getMyHashes = function()
            local gdb = addon:GetGuildDb()
            if not gdb then return {} end
            local HM = addon.HashManager
            HM:RebuildOnFirstLoad(DS, gdb)
            local map = HM:GetL0BroadcastMap(gdb)
            -- Pad placeholders so peers offer data for professions we have
            -- no local content for (Engineering / BS / LW / etc. on a char
            -- that only knows Enchanting + Tailoring etc.). Without this,
            -- the broadcaster-driven OFFER protocol leaves those keys
            -- silently un-synced. See HashManager:PadMissingProfessionPlaceholders.
            HM:PadMissingProfessionPlaceholders(DS, map)
            return map
        end,

        hasContent = function(itemKey)
            local gdb = addon:GetGuildDb()
            if not gdb then return false end
            return addon.HashManager:HasContent(gdb, itemKey)
        end,

        -- True when any online guildmate has no entry in our cooldown hash cache.
        hasMissingItems = function()
            local gdb = addon:GetGuildDb()
            if not gdb then return false end
            local me = GuildRoster:GetNormalizedPlayer()
            for _, name in ipairs(GuildRoster:GetOnlineMembers()) do
                if name ~= me and not (gdb.hashes and gdb.hashes["cooldown:" .. name]) then
                    return true
                end
            end
            return false
        end,

        -- Leaf sync accepted: peer has data we need.  Request the appropriate
        -- payload type via baseline.type encoded in the QUERY message.
        --
        -- Online gate: skip if the peer went offline between their broadcast
        -- and this dispatch. DeltaSync has its own internal offline check
        -- but that races with GUILD_ROSTER_UPDATE propagation; gating here
        -- catches the common case where GuildRoster has already seen the
        -- offline transition. Mirrors the TOGBankClassic pattern from
        -- DeltaComms.lua — every send site gets a guard before dispatch.
        onSyncAccepted = function(itemKey, sender)
            addon:DebugPrint("Scanner: onSyncAccepted itemKey=", itemKey, "sender=", sender)
            if Scanner:PeerIsOffline(sender) then
                addon:DebugPrint("Scanner:   -> skip RequestData -- peer offline:", sender)
                return
            end
            if itemKey == "guild:cooldowns" or itemKey == "guild:accountchars"
               or itemKey == "guild:skills" or itemKey == "guild:professions" then
                -- Roll-up mismatch — ask for per-character sub-hashes.
                addon:DebugPrint("Scanner:   → sending subhashes RequestData to", sender)
                DS:RequestData(sender, { type = "subhashes", parent = itemKey })
            elseif itemKey:sub(1, 9) == "crafters:" then
                -- Profession mismatch. If the peer is drill-down capable (we've seen a
                -- subsync-marked payload from them), fetch the per-player sub-hashes so
                -- we pull only the players whose recipes differ — newest first. Else
                -- fall back to the whole-profession leaf (legacy / old peer).
                local profId = tonumber(itemKey:sub(10))
                if profId and Scanner:PeerSupportsSubSync(sender) then
                    addon:DebugPrint("Scanner:   → sending player-subhashes RequestData to", sender, "for prof", profId)
                    DS:RequestData(sender, { type = "player-subhashes", profId = profId })
                else
                    addon:DebugPrint("Scanner:   → sending leaf-data RequestData to", sender, "for", itemKey)
                    DS:RequestData(sender, { type = "leaf-data", keys = { itemKey } })
                end
            elseif itemKey:sub(1, 11) == "recipemeta:"
                or itemKey:sub(1, 9)  == "cooldown:"
                or itemKey:sub(1, 13) == "accountchars:" then
                addon:DebugPrint("Scanner:   → sending leaf-data RequestData to", sender, "for", itemKey)
                DS:RequestData(sender, { type = "leaf-data", keys = { itemKey } })
            else
                addon:DebugPrint("Scanner:   → UNRECOGNIZED itemKey shape, no QUERY sent")
            end
        end,
    })

    -- Kick off the first VersionCheck batch so the broadcast debounce can
    -- adapt to the number of guildmates running the addon (rather than the
    -- static 30s floor inherited at file load). Updates Scanner._broadcastSeconds
    -- 21 seconds after FireBatch returns; subsequent refreshes happen on the
    -- 10-min periodic tick.
    self:ScheduleAddonUserRecount()

    addon:DebugPrint("Scanner: DeltaSync initialized for", DS.namespace)
end

--- Fire a VersionCheck-1.0 batch and, 21 seconds later, set
--- Scanner._broadcastSeconds based on how many guildmates responded.
--- Linear scale clamped to [3, 30] so small guilds sync quickly and large
--- guilds stay channel-courteous. No-ops when VersionCheck isn't loaded.
function Scanner:ScheduleAddonUserRecount()
    local VC = LibStub and LibStub("VersionCheck-1.0", true)
    if not VC or type(VC.FireBatch) ~= "function" then
        addon:DebugPrint("Scanner: ScheduleAddonUserRecount — VersionCheck-1.0 not available")
        return
    end
    VC:FireBatch()
    -- VC10_REQ broadcasts to guild; peers reply via whisper (VC10_RSP) with
    -- up to 8s jitter; VC collects for 12s. 21s buffer captures every reply.
    Ace:ScheduleTimer(function()
        local hostEntry = VC.hosts and VC.hosts[addon.name]
        local responses = hostEntry and hostEntry.VersionResponses or {}
        local n = 1  -- count self
        for _ in pairs(responses) do n = n + 1 end
        Scanner._broadcastSeconds = math.max(3, math.min(30, n))
        addon:DebugPrint("Scanner: broadcast debounce set to",
            Scanner._broadcastSeconds .. "s for", n, "addon user(s) online")
    end, 21)
end

-- ---------------------------------------------------------------------------
-- Event wiring — hooked into the Ace lifecycle via hooksecurefunc
-- ---------------------------------------------------------------------------

-- ---------------------------------------------------------------------------
-- Chat filter: swallow "No player named X is currently playing." spam
-- ---------------------------------------------------------------------------
-- The race window: a peer broadcasts hashes on the GUILD channel, then
-- logs out. Our addon (or DeltaSync's internal P2P logic) decides to
-- whisper them an OFFER / RequestData based on that broadcast. The
-- whisper hits the server, the server can't find the player, the server
-- replies with this system message, WoW prints it to the active chat
-- frame. A guild with active sync can produce this spam dozens of times
-- per logout event.
--
-- Mirrors the TOGBankClassic pattern in Modules/Events.lua:62-77 — fast
-- plain-text prefix check first (cheap on the high-volume CHAT_MSG_SYSTEM
-- stream which carries every guild login/logout/achievement message),
-- then the full pattern match only when the prefix matched. Suppresses
-- both quote variants ("No player named 'X'..." and "No player named
-- X...") and the "Player not found" alternate phrasing seen on some
-- clients.
--
-- Trade-off: a manual /w to a player who logged off ALSO won't show the
-- error — the TOGBank precedent accepted this because the addon itself
-- generates orders of magnitude more such errors than user typos do, and
-- the lack of a typing response in the chat window already signals the
-- failed send. If the player is in your guild the offline status is
-- visible in the guild roster anyway.
local _chatFilterInstalled = false
local function InstallChatFilter()
    if _chatFilterInstalled or not ChatFrame_AddMessageEventFilter then return end
    _chatFilterInstalled = true
    ChatFrame_AddMessageEventFilter("CHAT_MSG_SYSTEM", function(_self, _event, message)
        if not message then return false end
        if message:find("No player named ", 1, true) then
            if message:match("^No player named .+ is currently playing%.$") then
                return true  -- suppress
            end
        end
        if message:find("Player not found", 1, true) then
            return true  -- suppress
        end
        return false
    end)
end

function Scanner:Init()
    InstallChatFilter()

    -- Trade skill window (TBC+/Wrath/Cata/MoP — most professions)
    Ace:RegisterEvent("TRADE_SKILL_SHOW",   function() Scanner:OnTradeSkillEvent() end)
    Ace:RegisterEvent("TRADE_SKILL_UPDATE", function() Scanner:OnTradeSkillEvent() end)

    -- Craft window (Vanilla enchanting and weapon crafting)
    Ace:RegisterEvent("CRAFT_SHOW",   function() Scanner:OnCraftEvent() end)
    Ace:RegisterEvent("CRAFT_UPDATE", function() Scanner:OnCraftEvent() end)

    -- Item-based cooldowns (Salt Shaker in Vanilla leatherworking)
    Ace:RegisterEvent("BAG_UPDATE_COOLDOWN", function() Scanner:OnBagCooldownEvent() end)

    -- Gathering-profession skill changes (Herbalism / Skinning / Fishing /
    -- Archaeology have no trade-skill window, so the recipe scan never sees them).
    -- SKILL_LINES_CHANGED fires whenever a skill is learned or ranks up.
    Ace:RegisterEvent("SKILL_LINES_CHANGED", function() Scanner:ScanGatheringProfessions() end)

    -- Trainer window. When a player opens a profession trainer, capture
    -- the EXACT ReqSkillRank Blizzard's server enforces for every offered
    -- spell (via GetTrainerServiceSkillReq). This is the authoritative
    -- "Requires Blacksmithing (N)" value — same data the trainer's
    -- tooltip displays — that emulator SQL doesn't have for apprentice-
    -- tier recipes and that DBC's MinSkillLineRank reports as the
    -- placeholder 1 for many recipes. One trainer visit captures every
    -- spell that trainer teaches in a single event; the data syncs
    -- guild-wide via DeltaSync (added in a follow-up patch) so a single
    -- player's trainer visit fills the requiredSkill gap for everyone.
    -- See gdb.trainerObservations table for the captured shape.
    Ace:RegisterEvent("TRAINER_SHOW",   function() Scanner:OnTrainerShow() end)
    -- TRAINER_UPDATE fires AFTER TRAINER_SHOW once the service list is
    -- actually populated. On this client GetNumTrainerServices() returns 0
    -- inside the TRAINER_SHOW handler — the services arrive one frame
    -- later via TRAINER_UPDATE. Both events route to the same handler;
    -- the handler is idempotent (existing entries refresh their
    -- observedAt timestamp rather than double-counting).
    Ace:RegisterEvent("TRAINER_UPDATE", function() Scanner:OnTrainerShow() end)

    -- Scan cooldowns on login after the server is ready
    Ace:ScheduleTimer(function()
        Scanner:ScanCooldowns()
        Scanner:DetectSpecializations()
        Scanner:ScanGatheringProfessions()
        Scanner:ScheduleBroadcast()
        -- Kick off P2P catch-up: always broadcast on login so peers can compare
        -- hashes and offer fresher data. hasMissingItems() only checks for absent
        -- entries, not stale ones, so gating here would prevent refreshing
        -- cooldown data that changed while we were offline.
        local DS = Scanner.DS
        if DS and type(DS.BroadcastItemHashes) == "function" then
            local p2p = DS.p2p
            if p2p and p2p.cb then
                local hashes = type(p2p.cb.getMyHashes) == "function" and p2p.cb.getMyHashes() or {}
                DS:BroadcastItemHashes(hashes, "BULK")
            end
        end
    end, 2)

    -- v0.2.0 periodic catch-up tick: every 10 minutes, force a non-differential
    -- L0 hash broadcast.  Without this, an idle peer (no scans triggering
    -- broadcasts) never sends its hash list, so other peers never see its
    -- presence and can't push fresher data to it.  The 10-min cadence matches
    -- TOGBank's pattern and the v0.2.0-protocol.md design.
    Ace:ScheduleRepeatingTimer(function()
        -- Refresh the addon-user count so _broadcastSeconds tracks guild
        -- composition changes through the day. The new count lands ~21s
        -- after FireBatch returns and applies to the NEXT broadcast cycle;
        -- this tick uses whatever value was set by the previous recount.
        Scanner:ScheduleAddonUserRecount()
        Scanner._lastBroadcastHashes = nil  -- bypass differential check
        Scanner._lastBroadcastAt     = 0    -- bypass debounce
        Scanner:BroadcastHashes()
    end, 600)

    addon:DebugPrint("Scanner: Init complete")
end

-- Hook into Ace OnEnable so Init() runs after AceDB is ready.
hooksecurefunc(Ace, "OnEnable", function(_self)
    Scanner:Init()
end)

-- Hook into OnPlayerEnteringWorld to initialise DeltaSync once per session
-- and backfill any reagent rows missing itemId.  PEW guarantees guild + realm
-- info are populated, which the 2s post-OnEnable timer cannot — there we'd
-- silently bail when GetGuildDb() returned nil.
hooksecurefunc(Ace, "OnPlayerEnteringWorld", function(_self, _event, isInitialLogin, isReloadingUi)
    if isInitialLogin or isReloadingUi then
        Scanner:InitDeltaSync()
        -- One-time scrub of obsolete-marker names cached in gdb.recipes by
        -- pre-v0.5.5 versions of the addon (before the MergeCraftersIntoGdb /
        -- BackfillBogusRecipeNames / MergeRecipeMetaIntoGdb guards). Runs
        -- BEFORE the backfill schedule so the backfill sees the cleared
        -- names and repopulates them via GetSpellInfo. Without this, the
        -- guards prevent NEW pollution but the OLD pollution (Heavy Copper
        -- Ring stored as "59 TEST Green Shaman Chest", JC designs stored as
        -- "ZZOLD Design: ...", etc.) persists in SavedVariables forever.
        Scanner:ScrubObsoleteRecipeNames()
        -- Both backfills retry several times because GetItemInfo returns nil for
        -- items not yet in the client cache, and the cache fills lazily over the
        -- first ~couple minutes after login.  Each pass only logs when it
        -- actually had something to check, so silent retries don't spam chat.
        -- The reagent backfill's GetItemInfo call also kicks an async server-side
        -- load, so later passes pick up resolutions kicked by earlier passes.
        Ace:ScheduleTimer(function() Scanner:BackfillReagentItemIds()    end, 3)
        Ace:ScheduleTimer(function() Scanner:BackfillBogusRecipeNames()  end, 4)
        Ace:ScheduleTimer(function() Scanner:BackfillReagentItemIds()    end, 30)
        Ace:ScheduleTimer(function() Scanner:BackfillBogusRecipeNames()  end, 30)
        Ace:ScheduleTimer(function() Scanner:BackfillReagentItemIds()    end, 120)
        Ace:ScheduleTimer(function() Scanner:BackfillBogusRecipeNames()  end, 120)
    end
end)

-- Override the ForceSync stub from the main file.
function addon:ForceSync()
    Scanner:ScanCooldowns()
    Scanner._lastBroadcastAt = 0          -- bypass debounce
    Scanner._lastBroadcastHashes = nil    -- force full hash list (no diff)
    Scanner:BroadcastHashes()
    addon:Print(L["SlashForceSyncSent"])
end

-- /togpm status — dump comm/sync diagnostic snapshot to chat.
function addon:PrintStatus()
    local sep = "|cffaaaaaa----------------------------------------|r"
    addon:Print("|cffda8cffTOG Profession Master — Status|r")
    addon:Print(sep)

    -- ── DeltaSync ────────────────────────────────────────────────────────────
    local DS = Scanner.DS
    if not DS then
        addon:Print("|cffff4444DeltaSync: NOT initialized|r")
        addon:Print("  └ Scanner.DS is nil — was PLAYER_ENTERING_WORLD missed?")
    else
        addon:Print("|cff00ff00DeltaSync: initialized|r  namespace=" .. tostring(DS.namespace))
        -- External DeltaSync no longer exposes useAceComm/useAceCommQueue as
        -- direct fields; pull them from GetCommStats() and add the LibStub
        -- MINOR + a P2P-enabled flag while we're at it.
        local stats = (DS.GetCommStats and DS:GetCommStats()) or {}
        addon:Print("  aceComm="     .. tostring(stats.useAceComm or false)
            .. "  registered=" .. tostring(stats.registered or false)
            .. "  p2p="        .. tostring(stats.p2pEnabled or false)
            .. "  guildRoster=" .. tostring(Scanner.GuildRoster ~= nil))

        -- Communication prefixes (7 channels)
        if DS.prefixes then
            local pList = {}
            for k, v in pairs(DS.prefixes) do
                table.insert(pList, k .. "=" .. v)
            end
            table.sort(pList)
            addon:Print("  Prefixes: " .. table.concat(pList, "  "))
        end
    end

    addon:Print(sep)

    -- ── Guild ────────────────────────────────────────────────────────────────
    local guildKey = addon:GetGuildKey()
    addon:Print("Guild key: " .. (guildKey or "|cffff4444(not in a guild)|r"))

    local gdb = addon:GetGuildDb()
    if gdb then
        local memberCount, profCount, cdCount = 0, 0, 0
        for _ in pairs(gdb.guildData  or {}) do memberCount = memberCount + 1 end
        for _ in pairs(gdb.recipes    or {}) do profCount   = profCount   + 1 end
        for _ in pairs(gdb.cooldowns  or {}) do cdCount     = cdCount     + 1 end
        addon:Print("  Stored members=" .. memberCount
            .. "  profession buckets=" .. profCount
            .. "  cooldown members=" .. cdCount)
        addon:Print("  Hash cache entries: " ..
            (function()
                local n = 0
                for _ in pairs(gdb.hashes or {}) do n = n + 1 end
                return n
            end)())
    else
        addon:Print("  |cffff4444No guild DB available|r")
    end

    addon:Print(sep)

    -- ── Online roster ────────────────────────────────────────────────────────
    -- PrintStatus runs on `addon` (function addon:PrintStatus), but the
    -- GuildRoster handle is stashed on Scanner — reach across explicitly.
    local GuildRoster = Scanner.GuildRoster
    if GuildRoster then
        local online = GuildRoster:GetOnlineMembers()
        addon:Print("Online guild members: " .. #online)
        for _, name in ipairs(online) do
            local inGdb = gdb and gdb.guildData and gdb.guildData[name]
            addon:Print("  " .. name .. (inGdb and "" or "  |cffff4444(no data)|r"))
        end
    end

    addon:Print(sep)

    -- ── P2P state ─────────────────────────────────────────────────────────────
    if DS and DS.p2p then
        local p2p = DS.p2p
        local totalSends = 0
        for _, c in pairs(p2p.activeSends or {}) do totalSends = totalSends + c end
        addon:Print("P2P  active sessions=" .. (p2p.activeSessions or 0)
            .. "  active sends=" .. totalSends
            .. "  collecting=" .. tostring(p2p.isCollecting or false)
            .. "  catchUpCycles=" .. (p2p.catchUpCycles or 0))

        -- List in-flight sessions
        local sessions = p2p.sessions or {}
        local count = 0
        for _ in pairs(sessions) do count = count + 1 end
        if count > 0 then
            addon:Print("  Active sessions:")
            for sid, s in pairs(sessions) do
                addon:Print(("    [%s] %s → %s (%s)"):format(
                    s.state or "?", s.itemKey or "?", s.peer or "?", sid))
            end
        else
            addon:Print("  No active P2P sessions")
        end
    else
        addon:Print("P2P: not initialized")
    end

    addon:Print(sep)

    -- ── Broadcast debounce ───────────────────────────────────────────────────
    local lastBc  = Scanner._lastBroadcastAt or 0
    local elapsed = (GetServerTime() - lastBc)
    addon:Print("Last broadcast: "
        .. (lastBc > 0 and (elapsed .. "s ago") or "never")
        .. "  debounce=" .. Scanner._broadcastSeconds .. "s")

    -- ── Sync log summary ─────────────────────────────────────────────────────
    local log = addon.guildDb and addon.guildDb.global.syncLog or {}
    local sends, recvs = 0, 0
    for _, e in ipairs(log) do
        if e.event == "send" then sends = sends + 1
        elseif e.event == "recv" then recvs = recvs + 1 end
    end
    addon:Print("Sync log: " .. #log .. " entries  sends=" .. sends .. "  recvs=" .. recvs)
    addon:Print(sep)
end

--- /togpm dsstatus — focused DeltaSync multi-host health check (our /fgids).
--- Confirms the library is the v4.0.0+ multi-host build, that TOGPM created its
--- OWN isolated host via NewHost, and that the host carries our namespace, comm
--- prefixes and P2P — the migration-verification readout from the DeltaSync
--- handoff. Run it alongside another DeltaSync addon's own status command to
--- prove isolation: each should report its own namespace and prefixes.
function addon:PrintDeltaSyncStatus()
    local sep = "|cffaaaaaa----------------------------------------|r"
    addon:Print("|cffda8cffTOG Profession Master — DeltaSync|r")
    addon:Print(sep)

    local DSlib = LibStub and LibStub("DeltaSync-1.0", true)
    if not DSlib then
        addon:Print("|cffff4444Library: not found|r — the standalone DeltaSync addon isn't loaded.")
        return
    end

    local minor     = DSlib.MINOR or 0
    local multiHost  = (DSlib.NewHost ~= nil) and minor >= 15
    addon:Print("Library: |cff00ff00loaded|r  MINOR=" .. tostring(minor)
        .. "  multi-host=" ..
        (multiHost and "|cff00ff00yes (NewHost, MINOR>=15)|r"
                    or "|cffff4444NO — update the DeltaSync addon to v4.0.0+|r"))

    local DS = Scanner.DS
    if not DS then
        addon:Print("|cffff4444Host: not created|r (Scanner.DS is nil).")
        addon:Print("  \226\148\148 " .. (multiHost
            and "Was PLAYER_ENTERING_WORLD missed? Try /reload."
            or  "Guild sync is disabled until DeltaSync is updated to v4.0.0+."))
        return
    end

    addon:Print("Host: |cff00ff00created via NewHost|r  namespace=" .. tostring(DS.namespace))

    -- Comm prefixes — should be our own togpmv-v / -d / -q / -r / -x / -o / -h,
    -- distinct from any other DeltaSync consumer's (that's the whole point of
    -- multi-host isolation).
    if DS.prefixes then
        local pList = {}
        for k, v in pairs(DS.prefixes) do pList[#pList + 1] = k .. "=" .. v end
        table.sort(pList)
        addon:Print("  Prefixes: " .. table.concat(pList, "  "))
    end

    addon:Print("  P2P: " .. (DS.p2p and "|cff00ff00loaded|r" or "|cffff4444not loaded|r")
        .. "  GuildRoster: " .. (Scanner.GuildRoster and "|cff00ff00loaded|r" or "|cffff4444missing|r"))

    -- Delivery accounting (DeltaSync MINOR 17+). A non-zero "refused" count is
    -- usually the fastest answer to "why isn't sync working" — those messages
    -- never arrived, and nothing else in the game tells you. Absent on an older
    -- library, in which case we say so rather than printing a misleading zero.
    if DS.sendsDelivered ~= nil or DS.sendFailures ~= nil then
        local refused = DS.sendFailures or 0
        addon:Print("  Sends: delivered=" .. tostring(DS.sendsDelivered or 0)
            .. "  refused=" .. (refused > 0 and ("|cffff4444" .. refused .. "|r") or "0")
            .. "  not-attempted=" .. tostring(DS.sendsNotAttempted or 0))
        local f = DS.lastSendFailure
        if f then
            addon:Print("    \226\148\148 last refusal: " .. tostring(f.prefix)
                .. " " .. tostring(f.distribution)
                .. " \226\134\146 " .. tostring(f.target or "(broadcast)")
                .. "  " .. tostring(f.bytes) .. " bytes")
        end
        if refused > 0 and not addon:GetGuildKey() then
            addon:Print("    \226\148\148 |cffffd100You are not in a guild|r \226\128\148 guild broadcasts"
                .. " are refused by the client; this is expected.")
        end
    else
        addon:Print("  Sends: |cffaaaaaano delivery accounting|r (DeltaSync < MINOR 17)")
    end

    -- Defer to DeltaSync's own detailed dump when the build exposes one.
    if DS.DebugStatus then
        addon:Print(sep)
        addon:Print("|cffaaaaaaDeltaSync DebugStatus():|r")
        DS:DebugStatus()
    end

    addon:Print(sep)
    addon:Print("|cffaaaaaaIsolation check: run another DeltaSync addon's status (e.g. /fgids)"
        .. " \226\128\148 each host should show its OWN namespace and prefixes, and neither's"
        .. " sync should disturb the other.|r")
end

-- ---------------------------------------------------------------------------
-- Event handlers
-- ---------------------------------------------------------------------------

function Scanner:OnTradeSkillEvent()
    if UnitAffectingCombat("player") then return end

    local isLinked, linkedPlayer = IsTradeSkillLinked()
    if isLinked then
        -- Only store linked data if the player is a guildmate.
        if linkedPlayer and self.GuildRoster then
            local normKey = self.GuildRoster:NormalizeName(linkedPlayer)
            if normKey and self.GuildRoster:IsInGuild(normKey) then
                self:ScanTradeSkillInto(normKey, true)
            end
        end
        return
    end

    -- Always scan into whichever bucket the player's current guild key maps
    -- to. When guildless, addon:GetGuildDb() falls back to the synthetic
    -- NoGuildBucketKey bucket so the data is still captured for the local
    -- "My Characters" view. ScheduleBroadcast → BroadcastHashes guards on
    -- addon:GetGuildKey() so no-guild data never reaches the wire.
    local charKey = addon:GetCharacterKey()
    self:ScanTradeSkillInto(charKey, false)
    self:ScanCooldowns()
    self:DetectSpecializations()
    self:ScheduleBroadcast()
end

function Scanner:OnCraftEvent()
    if UnitAffectingCombat("player") then return end

    local charKey = addon:GetCharacterKey()
    self:ScanCraftSkillInto(charKey)
    self:ScanCooldowns()
    self:ScheduleBroadcast()
end

--- Capture trainer-service skill requirements on TRAINER_SHOW.
--- For each spell offered by the trainer (regardless of whether the player
--- can currently afford / has already learned it), record:
---   reqSkill   : the literal ReqSkillRank from GetTrainerServiceSkillReq —
---                same value as the "Requires Tailoring (100)" tooltip line
---                the trainer shows. AUTHORITATIVE; matches what Blizzard's
---                server enforces.
---   moneyCost  : copper cost to learn the spell (bonus signal; future UI)
---   profId     : the trainer's profession skill line, derived from
---                GetTrainerServiceSkillLine when present, else nil. Useful
---                for cross-checking against the recipe's profession.
---   observedBy : char key that captured this observation
---   observedAt : server UNIX timestamp
---
--- Stored under gdb.trainerObservations[spellId] = { ... }. Schema lives
--- top-level (peer to gdb.recipes etc.) so the table is grep-able in the
--- SavedVariables file — easy for the maintainer to find and dump when
--- promoting community observations into the shipped recipe DB.
---
--- v0.5.6: local capture only. Sync via DeltaSync added in a follow-up
--- so we can validate the capture shape against real trainer interactions
--- before plumbing it onto the wire.
function Scanner:OnTrainerShow()
    -- Always-on chat ping so we can confirm the event fires in the
    -- field, even before captures show up. Removed/quieted in a later
    -- patch once the capture pipeline is verified end-to-end.
    addon:DebugPrint("Scanner: TRAINER_SHOW/UPDATE fired (Scanner:OnTrainerShow)")
    if not GetNumTrainerServices then
        addon:DebugPrint("  GetNumTrainerServices unavailable on this client")
        return
    end
    local gdb = addon:GetGuildDb()
    if not gdb then
        addon:DebugPrint("  GetGuildDb returned nil (not in a guild?)")
        return
    end
    if not gdb.trainerObservations then gdb.trainerObservations = {} end

    local charKey = addon:GetCharacterKey()
    local now     = GetServerTime and GetServerTime() or time()
    local n       = GetNumTrainerServices() or 0
    if n == 0 then return end  -- pre-population fire, nothing to do
    local captured, updated, refreshed, skipped_header, skipped_no_spell = 0, 0, 0, 0, 0

    for i = 1, n do
        local name, _, svcType = GetTrainerServiceInfo(i)
        if not name or svcType == "header" then
            skipped_header = skipped_header + 1
        else
            local link = GetTrainerServiceItemLink and GetTrainerServiceItemLink(i)
            -- TBC's GetTrainerServiceItemLink returns the CRAFTED-ITEM link
            -- (|Hitem:N|h[Name]|h|r), not the spell link — the function is
            -- literally named "ItemLink". Extract item ID, then reverse-
            -- lookup to the recipe spell via addon.recipeDB[*][*].craftedItemId
            -- (added in v0.5.5 from SpellEffect[Effect=24]). Also accept
            -- spell:/enchant: as legacy formats for any client that uses
            -- the older link shape (Vanilla CRAFT_SHOW path, etc.).
            local spellId  = link and (tonumber(link:match("enchant:(%d+)"))
                                    or tonumber(link:match("Hspell:(%d+)"))
                                    or tonumber(link:match("spell:(%d+)")))
            local itemId   = link and tonumber(link:match("Hitem:(%d+)"))
            if not spellId and itemId and addon.recipeDB then
                -- Walk every profession's recipe table to find the spell
                -- whose craftedItemId matches the trainer's offered item.
                -- O(profession-size) but only fires once per trainer
                -- service (~60 per trainer visit) so it's negligible.
                for _, profRecipes in pairs(addon.recipeDB) do
                    for sid, data in pairs(profRecipes) do
                        if data.craftedItemId == itemId then
                            spellId = sid
                            break
                        end
                    end
                    if spellId then break end
                end
            end
            if not spellId and name and addon.recipeDB then
                -- Name-based fallback. Enchanting recipes apply effects
                -- directly to items rather than producing an item, so
                -- 84% of enchant entries in our recipeDB have no
                -- craftedItemId. The trainer service's name
                -- ("Enchant Cloak - Lesser Shadow Resistance", etc.)
                -- still matches the spell name in our recipeDB exactly.
                -- Use that to find the spell ID. Only kicks in when both
                -- prior lookups (spell-link regex, itemId reverse-lookup)
                -- missed, so it's a clean third-tier fallback.
                for _, profRecipes in pairs(addon.recipeDB) do
                    for sid, data in pairs(profRecipes) do
                        if data.name == name then
                            spellId = sid
                            break
                        end
                    end
                    if spellId then break end
                end
            end
            if not spellId then
                skipped_no_spell = skipped_no_spell + 1
                if skipped_no_spell <= 3 then
                    local raw = tostring(link):gsub("|", "||")
                    addon:DebugPrint(("  [skip] svc %d name=%q type=%q itemId=%s link=%s"):format(
                        i, tostring(name), tostring(svcType), tostring(itemId), raw))
                end
            else
                local reqSkill = 0
                if GetTrainerServiceSkillReq then
                    -- API returns (reqSkillName, reqSkillRank) — the skill
                    -- name first ("Blacksmithing"/etc.), the numeric rank
                    -- second. Previous code captured only the first return
                    -- and got the string, failing the type check and
                    -- shipping reqSkill=0 for every observation.
                    local _, reqSkillRank = GetTrainerServiceSkillReq(i)
                    if type(reqSkillRank) == "number" then reqSkill = reqSkillRank end
                end
                local moneyCost = 0
                if GetTrainerServiceCost then
                    local c = GetTrainerServiceCost(i)
                    if type(c) == "number" then moneyCost = c end
                end
                local profId
                if GetTrainerServiceSkillLine then
                    local sl = GetTrainerServiceSkillLine(i)
                    if type(sl) == "number" then profId = sl end
                end
                local existing = gdb.trainerObservations[spellId]
                local entry = {
                    reqSkill   = reqSkill,
                    moneyCost  = moneyCost,
                    profId     = profId,
                    observedBy = charKey,
                    observedAt = now,
                }
                if not existing then
                    gdb.trainerObservations[spellId] = entry
                    captured = captured + 1
                elseif existing.reqSkill ~= reqSkill or existing.moneyCost ~= moneyCost then
                    gdb.trainerObservations[spellId] = entry
                    updated = updated + 1
                else
                    existing.observedAt = now
                    refreshed = refreshed + 1
                end
            end
        end
    end

    local total = 0
    for _ in pairs(gdb.trainerObservations) do total = total + 1 end
    -- Full diagnostic stays on DebugPrint (visible with /togpm debug).
    -- The one-line summary on captures stays user-facing — small,
    -- informative, fires once per trainer visit (the early no-services
    -- fires now return at the top so they don't print at all).
    addon:DebugPrint(("Scanner: trainerObs captured=%d updated=%d refreshed=%d"
        .. " skipped(header)=%d skipped(no-spell)=%d total=%d"):format(
        captured, updated, refreshed, skipped_header, skipped_no_spell, total))
    if captured > 0 or updated > 0 then
        addon:Print(("Trainer scan: %d new, %d updated (%d total recorded)"):format(captured, updated, total))
    end
end

function Scanner:OnBagCooldownEvent()
    if not addon.isVanilla then return end
    -- BAG_UPDATE_COOLDOWN fires for every item that gains/loses a cooldown, which
    -- happens constantly in play (potions, food, engineering items, etc.).
    -- We only care about the Salt Shaker, and only when its state actually changes.
    local data   = addon:GetCooldownData()
    local itemId = data and data.saltShakerItem
    if not itemId then return end

    -- Skip entirely if the player doesn't own a Salt Shaker.
    local count = addon.Item.GetCount(itemId, true) or 0
    if not count or count == 0 then return end

    local gdb     = addon:GetGuildDb()
    local charKey = addon:GetCharacterKey()
    if not gdb or not charKey then return end

    local prevExpiry = gdb.cooldowns[charKey] and gdb.cooldowns[charKey][itemId]
    self:ScanCooldowns()
    local newExpiry = gdb.cooldowns[charKey] and gdb.cooldowns[charKey][itemId]

    if newExpiry ~= prevExpiry then
        self:ScheduleBroadcast()
    end

    -- Timing insurance: BAG_UPDATE_COOLDOWN can fire a hair BEFORE the item's
    -- cooldown is queryable, so the scan above may still read "Ready" — you used
    -- it, but the tab stays Ready until the next scan / reload. If the shaker
    -- isn't showing an active cooldown yet, re-check JUST the shaker ~1s later and,
    -- if it's now on cooldown, commit and fire the COOLDOWNS-scoped UI refresh so
    -- the open tab updates. Guarded so a burst of unrelated bag-cooldown events
    -- (potions, food, …) can't stack timers.
    local active = newExpiry and (newExpiry - GetServerTime()) > 0
    if not active and not self._saltRescanPending then
        self._saltRescanPending = true
        Ace:ScheduleTimer(function()
            self._saltRescanPending = false
            local g  = addon:GetGuildDb()
            local ck = addon:GetCharacterKey()
            if not g or not ck then return end
            if not g.cooldowns[ck] then g.cooldowns[ck] = {} end
            local before = g.cooldowns[ck][itemId]
            self:ScanSaltShaker(g.cooldowns[ck], GetServerTime(), itemId)
            if g.cooldowns[ck][itemId] ~= before then
                if self.DS then
                    addon.HashManager:InvalidateCharCooldowns(self.DS, g, ck)
                end
                self:ScheduleBroadcast()
                if addon.callbacks then
                    addon.callbacks:Fire("GUILD_DATA_UPDATED", ck, { cooldowns = true })
                end
            end
        end, 1)
    end
end

-- ---------------------------------------------------------------------------
-- Profession scanning — TradeSkill frame
-- ---------------------------------------------------------------------------

--- Build a name → spellId lookup from the player's spellbook.
-- GetSpellInfo() does not return spellID on Classic Era clients (that return
-- value was added in retail patch 7.1).  GetSpellBookItemInfo() always returns
-- the spellID as its 2nd value and works on all Classic builds.
-- Only covers spells the local player knows; linked scans get spellId = nil.
function Scanner:BuildSpellNameCache()
    local cache = {}
    local numTabs = GetNumSpellTabs and GetNumSpellTabs() or 0
    for tab = 1, numTabs do
        local _, _, offset, numSpells = GetSpellTabInfo(tab)
        for j = 1, numSpells do
            local idx = offset + j
            local _, spellId = GetSpellBookItemInfo(idx, "spell")
            if spellId then
                local spellName = GetSpellInfo(spellId)
                if spellName then
                    cache[spellName] = spellId
                end
            end
        end
    end
    return cache
end

--- Scan the currently open trade-skill window and store the result in AceDB.
-- @param charKey   "Name-Realm" string for the character being scanned
-- @param isLinked  true when viewing another player's linked trade skill
function Scanner:ScanTradeSkillInto(charKey, _isLinked)
    -- v0.7.0: isLinked no longer matters — we don't store metadata so the
    -- "build local spellbook cache for non-linked scans" branch is gone.
    --
    -- v0.7.6: GetTradeSkillLine returns (name, rank, maxRank) on every
    -- Classic version (Vanilla / TBC / Wrath / Cata / MoP) — 3 values,
    -- no texture parameter. Confirmed against AllTheThings
    -- (src/UI/Windows/Tradeskills.lua:167) and MissingTradeSkillsList
    -- (ui/event_handler.lua:168), both of which run on every Classic
    -- expansion and use the same 3-return signature.
    --
    -- The pre-v0.7.6 read was `name, _, rank, max` — assuming a 4-return
    -- signature with `texture` in position 2 (modern WoW pre-C_TradeSkillUI
    -- behaviour). Wrong on Classic: the `_` ate the actual current rank,
    -- position 3 picked up `maxRank` instead, and `skillMax` came back
    -- nil and got defaulted to 300 inside MergeRecipesIntoGdb. Net effect
    -- for every Classic scan since the addon was written:
    --   gdb.skills[charKey][profId].skillRank = the character's MAX skill
    --   gdb.skills[charKey][profId].skillMax  = 300 (regardless of cap)
    -- Nothing read these fields until v0.7.4's "Can learn now" filter, so
    -- the bug stayed invisible. Then a 267/300 Blacksmith with the filter
    -- on saw every 290 / 295 / 300 plan still in their missing list
    -- because the filter compared the recipe's requiredSkill against a
    -- skillRank that had silently been pinned to 300 forever.
    --
    -- Existing affected players need to open each trade-skill window
    -- once post-update to overwrite their stale gdb.skills entries with
    -- the correctly-read rank. Same self-healing model as the v0.7.5
    -- ScanCraftSkillInto fix for Vanilla Enchanters.
    local skillName, skillRank, skillMax = GetTradeSkillLine()
    if not skillName or skillName == "UNKNOWN" then return end

    local profId = self:ResolveProfessionId(skillName)
    if not profId then
        addon:DebugPrint("Scanner: unrecognised profession name:", skillName)
        return
    end

    -- v0.7.0: collect ONLY recipe IDs. Recipe metadata (name / icon / reagents /
    -- itemLink) lives in the shipped addon.recipeDB and is looked up at render
    -- time. The SV stores nothing but the crafter set per recipe, keyed by tag.
    local recipeIds = {}
    local total = GetNumTradeSkills()
    for i = 1, total do
        local _, tradeSkillType = GetTradeSkillInfo(i)
        if tradeSkillType == "optimal" or tradeSkillType == "medium"
        or tradeSkillType == "easy"    or tradeSkillType == "trivial" then
            local recipeId = self:ExtractTradeSkillId(i)
            if recipeId then recipeIds[recipeId] = true end
        end
    end

    local gdb = addon:GetGuildDb()
    if not gdb then return end
    local changed = self:MergeRecipesIntoGdb(gdb, charKey, profId, skillRank, skillMax, recipeIds)

    -- Stamp the content-derived scan time used by HashManager.
    if not gdb.lastScan[charKey] then gdb.lastScan[charKey] = {} end
    gdb.lastScan[charKey][profId] = GetServerTime()

    -- Invalidate the per-profession recipe hash.
    local DS = self.DS
    if DS then
        addon.HashManager:InvalidateProfession(DS, gdb, profId)
    end

    local count = 0; for _ in pairs(recipeIds) do count = count + 1 end
    addon:DebugPrint("Scanner: scanned", skillName, "for", charKey, "—", count, "recipes")

    -- Refresh the UI for our own freshly-scanned recipes, but only when the set
    -- actually changed, so crafting's repeated TRADE_SKILL_UPDATE events don't
    -- churn the active tab.
    if changed then self:RefreshAfterLocalScan(charKey) end
end

--- Merge a freshly-scanned recipe-id set into the flat recipe DB.
--- v0.7.0: no metadata stored — just the crafter set per recipe, tagged with
--- the local player's current guild. The shipped addon.recipeDB carries name,
--- icon, reagents, etc., looked up at display time by recipeId.
---
--- @param recipeIds  table  set { [recipeId] = true } of recipes this char knows
function Scanner:MergeRecipesIntoGdb(gdb, charKey, profId, skillRank, skillMax, recipeIds)
    if not gdb.recipes then gdb.recipes = {} end
    if not gdb.skills  then gdb.skills  = {} end

    -- Skill rank/max. Fall back the max to the RANK (never the old Vanilla-cap
    -- constant 300) when the API didn't hand us a maxRank — a skill's cap can't be
    -- below its current rank, and hard-coding 300 produced the impossible "375/300"
    -- on TBC/Wrath and then synced that bad value guild-wide.
    skillRank = skillRank or 0
    if not gdb.skills[charKey] then gdb.skills[charKey] = {} end
    gdb.skills[charKey][profId] = { skillRank = skillRank, skillMax = skillMax or skillRank }

    -- Compute the current guild tag once. Tag is "personal" when guildless,
    -- so own scans on a no-guild alt still get stored (and visible to that
    -- alt's owner via the My Characters view).
    local tag = addon:GetCurrentGuildTag()

    -- Remove charKey from any existing recipe's crafter set for this prof
    -- (covers recipes the character has unlearned since the last scan). Snapshot
    -- which recipes this char crafted BEFORE the scan so we can report whether
    -- anything actually changed — callers refresh the UI only on a real change,
    -- which avoids redraw churn from identical re-scans (the repeated
    -- TRADE_SKILL_UPDATE events WoW fires while crafting all re-run this merge).
    local oldSet = {}
    if not gdb.recipes[profId] then
        gdb.recipes[profId] = {}
    else
        for rid, rd in pairs(gdb.recipes[profId]) do
            if rd.crafters and rd.crafters[charKey] then oldSet[rid] = true end
            if rd.crafters then rd.crafters[charKey] = nil end
        end
    end

    -- Add charKey + tag to each known recipe.
    -- v0.7.1: on Vanilla / Classic Hardcore, ExtractTradeSkillId returns
    -- the crafted item ID (Hitem:N links) rather than the spell ID; the
    -- addon.recipeDB is keyed by spell ID universally. Remap item-IDs to
    -- spell-IDs here so storage lands at the key everything else reads
    -- from. addon.recipeDB on other clients (TBC+) keys directly by spell
    -- and the lookup is a no-op (profMeta[recipeId] hits, no remap).
    local profMeta = addon.recipeDB and addon.recipeDB[profId]
    local newSet = {}
    for recipeId in pairs(recipeIds) do
        local effectiveId = recipeId
        if profMeta and not profMeta[recipeId] then
            local spellId = addon:GetSpellIdForCraftedItem(profId, recipeId)
            if spellId then effectiveId = spellId end
        end
        local rd = gdb.recipes[profId][effectiveId]
        if not rd then
            rd = { crafters = {} }
            gdb.recipes[profId][effectiveId] = rd
        end
        if not rd.crafters then rd.crafters = {} end
        rd.crafters[charKey] = tag
        newSet[effectiveId] = true
    end

    -- Report whether this char's crafted-recipe set actually changed (symmetric
    -- diff of old vs new). Lets callers skip a UI refresh on a no-op re-scan.
    for rid in pairs(newSet) do if not oldSet[rid] then return true end end
    for rid in pairs(oldSet) do if not newSet[rid] then return true end end
    return false
end

-- Refresh the UI after a LOCAL scan that actually changed our recipe set. A
-- local scan commits to gdb but (unlike a received sync) raised no UI signal, so
-- the Browser's recipe-list cache never rewarmed and the Professions tab —
-- especially the cached "All Professions" view — kept serving a stale list until
-- a /reload or an incoming peer update. Wiping the list cache makes the next draw
-- rebuild from current gdb; firing GUILD_DATA_UPDATED runs the same redraw +
-- background rewarm path a peer update uses. Caller gates this on a real change
-- so repeated identical re-scans (TRADE_SKILL_UPDATE while crafting) don't churn.
function Scanner:RefreshAfterLocalScan(charKey)
    if addon.BrowserTab and addon.BrowserTab.InvalidateCache then
        addon.BrowserTab:InvalidateCache()
    end
    if addon.callbacks then
        -- A local scan only ever changes our recipe (crafter) set.
        addon.callbacks:Fire("GUILD_DATA_UPDATED", charKey, { recipes = true })
    end
end

--- Extract a numeric recipe key from a trade-skill row.
-- Returns id, isSpell where isSpell=true means id is a spell/enchant ID,
-- false means id is the crafted item ID.
function Scanner:ExtractTradeSkillId(index)
    -- Retail / modern Classic: recipe link always has enchant:SPELLID.
    local link = GetTradeSkillRecipeLink and GetTradeSkillRecipeLink(index)
    if link then
        local id = tonumber(link:match("enchant:(%d+)"))
        if id then return id, true end
    end
    -- Classic Era: GetTradeSkillItemLink returns enchant:SPELLID for Enchanting,
    -- or item:ITEMID (the crafted product) for all other professions.
    link = GetTradeSkillItemLink(index)
    if link then
        local id = tonumber(link:match("enchant:(%d+)"))
        if id then return id, true end
        id = tonumber(link:match("item:(%d+)"))
        if id then return id, false end
    end
    return nil, nil
end

-- ---------------------------------------------------------------------------
-- Profession scanning — Craft frame (Vanilla enchanting / weapon crafting)
-- ---------------------------------------------------------------------------

function Scanner:ScanCraftSkillInto(charKey)
    if not GetCraftDisplaySkillLine then return end

    -- v0.7.5: GetCraftDisplaySkillLine on Vanilla returns (name, rank, maxRank).
    -- v0.7.4 and earlier only read the name and hardcoded skillRank=0,
    -- skillMax=300 into MergeRecipesIntoGdb. That broke the v0.7.4 "Can
    -- learn now" filter for every Vanilla Enchanter: gdb.skills[charKey][333]
    -- recorded skillRank=0, the filter compared every recipe's requiredSkill
    -- against 0, every requiredSkill > 0 → every Enchanting recipe hidden.
    local skillName, skillRank, skillMax = GetCraftDisplaySkillLine()
    if not skillName then return end

    local profId = self:ResolveProfessionId(skillName)
    if not profId then
        addon:DebugPrint("Scanner: unrecognised craft skill:", skillName)
        return
    end

    -- v0.7.0: recipe IDs only — metadata lives in the shipped addon.recipeDB.
    local recipeIds = {}
    local total = GetNumCrafts and GetNumCrafts() or 0
    for i = 1, total do
        local _, _, craftType = GetCraftInfo(i)
        if craftType == "optimal" or craftType == "medium"
        or craftType == "easy"    or craftType == "trivial" then
            local link    = GetCraftItemLink and GetCraftItemLink(i)
            local spellId = link and tonumber(link:match("enchant:(%d+)"))
            if spellId then recipeIds[spellId] = true end
        end
    end

    local gdb = addon:GetGuildDb()
    if not gdb then return end
    local changed = self:MergeRecipesIntoGdb(gdb, charKey, profId, skillRank, skillMax, recipeIds)

    -- Stamp content-derived scan time for hash leaves.
    if not gdb.lastScan[charKey] then gdb.lastScan[charKey] = {} end
    gdb.lastScan[charKey][profId] = GetServerTime()

    -- Invalidate the per-profession recipe hash.
    local DS = self.DS
    if DS then
        addon.HashManager:InvalidateProfession(DS, gdb, profId)
    end

    local count = 0; for _ in pairs(recipeIds) do count = count + 1 end
    addon:DebugPrint("Scanner: scanned craft", skillName, "for", charKey, "—", count, "recipes")

    -- See ScanTradeSkillInto: refresh the UI only when the recipe set changed.
    if changed then self:RefreshAfterLocalScan(charKey) end
end

-- ---------------------------------------------------------------------------
-- Profession ID resolution
-- Primary path: match the open window's name against GetProfessions() entries.
-- Fallback: static English name map (covers linked professions and all locales
-- where the skill name happens to match the English key).
-- ---------------------------------------------------------------------------

function Scanner:ResolveProfessionId(name)
    if not name then return nil end

    -- Walk the character's own profession slots first. GetProfessions is the
    -- Cata+ API and is feature-detected at every OTHER call site in this addon
    -- (enumerateHeldProfessions below, CraftingEngine:GetKnownProfessions) —
    -- this one wasn't, and it sits in the hot path of every trade-skill and
    -- craft-window scan, so on a client without the global nothing would scan
    -- at all. Absent → fall through to the static name map, same as a slot walk
    -- that finds nothing.
    if GetProfessions and GetProfessionInfo then
        for _, idx in ipairs({ GetProfessions() }) do
            if idx then
                local pName, _, _, _, _, _, skillLine = GetProfessionInfo(idx)
                if pName == name then
                    return skillLine
                end
            end
        end
    end

    -- Fall back to the static English map.
    return PROF_NAME_TO_ID[name]
end

-- ---------------------------------------------------------------------------
-- Cooldown-remaining helper (mirrors ProfessionCooldown GetCooldownLeftOnItem)
-- Handles the WoW GetTime() 2^32 ms (~49.7-day) rollover.
-- ---------------------------------------------------------------------------

local function GetCooldownLeft(start, duration)
    if start < GetTime() then
        return (start + duration) - GetTime()
    end
    -- Post-rollover case: start is from the previous epoch.
    local luaTime     = time()
    local startupTime = luaTime - GetTime()
    local cdTime      = (2 ^ 32) / 1000 - start
    local cdStartTime = startupTime - cdTime
    return (cdStartTime + duration) - luaTime
end

-- ---------------------------------------------------------------------------
-- Profession-spec detection
--
-- Walks IsSpellKnown on each known spec spell ID and records which spec
-- (if any) this character has for each profession. Result lands in
-- gdb.specializations[charKey][profId] = specSpellId, then piggybacks the
-- crafters: leaf on the next sync (see BuildLeafPayload / OnGuildDataReceived).
--
-- Detection catalog covers TBC-introduced specs (Vanilla had no profession
-- specs in the bonus-output sense; Cata 4.0.1 removed the proc system).
-- Engineering Gnomish/Goblin gate exclusive recipes but currently have no
-- bonus-output mapping — they're kept here so the detection table is
-- complete for future use (e.g. spec-aware recipe filtering).
-- ---------------------------------------------------------------------------

local SPEC_SPELLS = {
    -- Alchemy: Transmutation / Potion / Elixir Master
    -- (DBC-verified; 28682/28683 were wrong -- Combustion/Leap)
    [171] = { 28672, 28675, 28677 },
    [202] = { 20219, 20222 },          -- Engineering: Gnomish / Goblin
    -- Tailoring: Spellfire / Mooncloth / Shadoweave (DBC-verified; 26802 was
    -- wrong -- "Detect Amore", a holiday spell. Mooncloth is 26798)
    [197] = { 26797, 26798, 26801 },
    -- Vanilla Leatherworking / Blacksmithing specializations (still present on
    -- TBC/Wrath; removed in Cata 4.0.1). No bonus-output mapping — recorded so
    -- the Guild tab can break professions down by sub-class. IsSpellKnown just
    -- returns false on clients where the spec doesn't exist, so no version gate
    -- is needed.
    [165] = { 10656, 10658, 10660 },   -- Leatherworking: Dragonscale / Elemental / Tribal
    -- Blacksmithing: list the finer Weaponsmith sub-specs BEFORE Weaponsmith
    -- itself so a swordsmith/hammersmith/axesmith (who knows BOTH the parent and
    -- the sub-spell) records the more specific one; the loop breaks on first hit.
    [164] = { 17039, 17040, 17041, 9788, 9787 }, -- Swordsmith / Hammersmith / Axesmith / Armorsmith / Weaponsmith
}

function Scanner:DetectSpecializations()
    local charKey = addon:GetCharacterKey()
    local gdb     = addon:GetGuildDb()
    if not gdb then return end
    if not gdb.specializations then gdb.specializations = {} end

    local specs = {}
    for profId, spellList in pairs(SPEC_SPELLS) do
        for _, spellId in ipairs(spellList) do
            if IsSpellKnown and IsSpellKnown(spellId, false) then
                specs[profId] = spellId
                break
            end
        end
    end
    gdb.specializations[charKey] = specs
end

-- ---------------------------------------------------------------------------
-- Profession scanning (the owner-authoritative profession registry)
--
-- Records the COMPLETE set of professions the local player currently holds —
-- crafting AND gathering — into gdb.skills[charKey], the authoritative "who has
-- what profession" registry that syncs on the skills:<charKey> leaf. This is the
-- owner side of the dropped-profession fix: because a dropped profession has no
-- trade-skill window to re-scan, the ONLY way it leaves the guild's data is for
-- the owner to notice it's gone from their current profession set and broadcast a
-- fresh snapshot that omits it (peers replace their row + prune crafters). See
-- [[project-dropped-profession-fix]] / the skills: leaf in BuildLeafPayload.
--
-- On a real change it invalidates the skills:<charKey> leaf (owner MINT — the
-- only place the hash is computed from data) and broadcasts, syncing the same
-- owner-authoritative, relay-by-anyone way as every other leaf.
-- ---------------------------------------------------------------------------

-- Enumerate the professions the local player currently holds. Returns
--   held      = { [profId] = { rank = N, max = N } }   (crafting AND gathering)
--   reliable  = boolean — true only when the read can be TRUSTED FOR REMOVAL.
-- Reliability matters because deleting a profession off an unreliable read would
-- wipe data the player still has:
--   * Cata/MoP: GetProfessions/GetProfessionInfo hand us the locale-independent
--     skillLine ID directly → always reliable.
--   * Era/TBC/Wrath: no GetProfessions, so skill-line NAMES are mapped through the
--     English PROF_NAME_TO_ID. A non-English client can't resolve those names, so
--     it would under-report — only trust removal on an English locale with a
--     non-empty read (a genuinely profession-less char has nothing to remove).
local function enumerateHeldProfessions()
    local held     = {}
    local reliable = false

    -- Cata/MoP path — locale-independent skillLine IDs.
    if GetProfessions then
        local anySlot = false
        for _, idx in ipairs({ GetProfessions() }) do
            if idx then
                local _n, _i, rank, max, _, _, skillLine = GetProfessionInfo(idx)
                if skillLine then
                    held[skillLine] = { rank = rank or 0, max = max or 0 }
                    anySlot = true
                end
            end
        end
        if anySlot then reliable = true end
    end

    -- Classic path (Era/TBC/Wrath) — also the fallback if the Cata path yielded
    -- nothing. Reads the character-panel skill lines (GetProfessions is a no-op on
    -- Classic Era). A COLLAPSED header hides its children, so the caller expands
    -- all headers first.
    if not reliable and GetNumSkillLines and GetSkillLineInfo then
        for i = 1, (GetNumSkillLines() or 0) do
            -- name(1), isHeader(2), isExpanded(3), rank(4), _, _, maxRank(7)
            local name, isHeader, _, rank, _, _, maxRank = GetSkillLineInfo(i)
            if name and not isHeader then
                local profId = PROF_NAME_TO_ID[name]
                if profId then held[profId] = { rank = rank or 0, max = maxRank or 0 } end
            end
        end
        local loc = (GetLocale and GetLocale()) or "enUS"
        if next(held) and loc:sub(1, 2) == "en" then reliable = true end
    end

    return held, reliable
end

function Scanner:ScanGatheringProfessions()
    if not GetNumSkillLines or not GetSkillLineInfo then return end
    -- Re-entrancy guard: ExpandSkillHeader below can fire SKILL_LINES_CHANGED, which
    -- would re-enter this scan. The flag resets at the single exit point at the end,
    -- so genuine skill-ups still re-scan normally.
    if self._scanningGather then return end
    self._scanningGather = true

    -- A COLLAPSED skill header hides its child skills from GetSkillLineInfo — so a
    -- character with the "Professions" header collapsed drops its primary gathering
    -- skills (Skinning / Herbalism), and a collapsed "Secondary Skills" drops
    -- Fishing / Archaeology. Expand every header first so the scan sees them all.
    if _G.ExpandSkillHeader then _G.ExpandSkillHeader(0) end

    local charKey = addon:GetCharacterKey()
    local gdb     = addon:GetGuildDb()
    if gdb and charKey then
        if not gdb.skills[charKey] then gdb.skills[charKey] = {} end
        local stored  = gdb.skills[charKey]
        local changed = false

        local held, reliable = enumerateHeldProfessions()

        -- 1. Record / update every profession currently held (crafting AND
        --    gathering). Recording crafting profs here means a profession appears in
        --    the registry at its real rank even before its window is ever opened.
        for profId, info in pairs(held) do
            local prev = stored[profId]
            if not prev or prev.skillRank ~= info.rank or prev.skillMax ~= info.max then
                stored[profId] = { skillRank = info.rank, skillMax = info.max }
                changed = true
                addon:DebugPrint("Scanner: recorded profession", profId,
                    "(", info.rank .. "/" .. info.max, ")")
            end
        end

        -- 2. Drop professions no longer held — the dropped-profession fix. Guarded
        --    two ways so we NEVER delete a profession the player still has:
        --      * reliable read only (see enumerateHeldProfessions), AND
        --      * absent across TWO consecutive reliable reads. A partial/early
        --        skill-line read (common in the seconds after login — some
        --        professions loaded, others not yet) would otherwise look like a
        --        drop. A first-time "missing" prof is only FLAGGED, and a confirming
        --        re-scan is scheduled; it's removed only if still missing next read
        --        (a partial read self-corrects because the prof reappears).
        local dropped = false
        if reliable then
            local candidates     = {}
            local prevCandidates = self._dropCandidates or {}
            local pendingConfirm = false
            for profId in pairs(stored) do
                if not held[profId] then
                    candidates[profId] = true
                    if prevCandidates[profId] then
                        stored[profId] = nil
                        changed = true
                        dropped = true
                        addon:DebugPrint("Scanner: profession gone (confirmed), dropping", profId)
                    else
                        pendingConfirm = true
                        addon:DebugPrint("Scanner: profession missing (1st read), awaiting confirm", profId)
                    end
                end
            end
            self._dropCandidates = candidates
            -- Schedule the confirming second read so a genuine mid-session drop
            -- still commits promptly (SKILL_LINES_CHANGED fires only once on a drop).
            if pendingConfirm and not self._dropConfirmTimer then
                self._dropConfirmTimer = Ace:ScheduleTimer(function()
                    Scanner._dropConfirmTimer = nil
                    Scanner:ScanGatheringProfessions()
                end, 3)
            end
        end

        if changed then
            if not gdb.lastScan[charKey] then gdb.lastScan[charKey] = {} end
            local now = GetServerTime()
            gdb.lastScan[charKey].skills = now
            -- `.professions` asserts we hold a COMPLETE authoritative snapshot for
            -- ourselves — set only on a reliable read (ranks alone don't establish
            -- membership authority). The reconcile + resurrection guards key off it.
            if reliable then gdb.lastScan[charKey].professions = now end

            local DS = self.DS
            -- Prune our OWN crafter rows for any profession we just dropped, so the
            -- fresh snapshot and the recipe lists agree.
            local pruned = false
            if dropped then
                pruned = self:ReconcileCraftersAgainstSkills(gdb, charKey)
            end
            -- Owner MINT of the gathering skills leaf (unchanged, backward-compat).
            if DS then addon.HashManager:InvalidateCharSkills(DS, gdb, charKey) end
            -- Owner MINT of the professions leaf — the authoritative full snapshot
            -- that carries the drop. Only on a reliable read (we set .professions
            -- above only then), so we never assert a set we can't trust.
            if DS and reliable then
                addon.HashManager:InvalidateCharProfessions(DS, gdb, charKey)
            end
            self:ScheduleBroadcast()
            if addon.callbacks then
                local scopes = { skills = true }
                if pruned then scopes.recipes = true end
                addon.callbacks:Fire("GUILD_DATA_UPDATED", charKey, scopes)
            end
            addon:DebugPrint("Scanner: professions updated for", charKey,
                "(reliable=", tostring(reliable), " dropped=", tostring(dropped), ")")
        end
    end

    self._scanningGather = false
end

-- Prune crafter rows for ONE owner against their AUTHORITATIVE profession snapshot.
-- Removes the owner from every recipe of any profession their snapshot does not
-- contain, and re-mints that profession's (aggregate) crafters hash so the pruned
-- set propagates. Guarded: acts ONLY when we positively hold a complete snapshot
-- for the owner (gdb.lastScan[owner].professions set) — never on mere absence of a
-- skills row, so a peer we simply lack snapshot data for is left untouched. This is
-- what turns "owner dropped a profession" into "their recipes disappear for
-- everyone"; the crafters leaf itself can't express the deletion. Returns whether
-- anything was pruned.
function Scanner:ReconcileCraftersAgainstSkills(gdb, ownerKey)
    if not gdb or not gdb.recipes or not ownerKey then return false end
    if not (gdb.lastScan and gdb.lastScan[ownerKey]
            and gdb.lastScan[ownerKey].professions) then
        return false
    end
    local snap = gdb.skills and gdb.skills[ownerKey]
    local changed = false
    for profId, profRecipes in pairs(gdb.recipes) do
        if not (snap and snap[profId]) then
            local profChanged = false
            for _, rd in pairs(profRecipes) do
                if rd.crafters and rd.crafters[ownerKey] then
                    rd.crafters[ownerKey] = nil
                    profChanged = true
                end
            end
            if profChanged then
                changed = true
                if self.DS then
                    addon.HashManager:InvalidateProfession(self.DS, gdb, profId)
                end
            end
        end
    end
    return changed
end

-- ---------------------------------------------------------------------------
-- Cooldown scanning
-- ---------------------------------------------------------------------------

function Scanner:ScanCooldowns()
    local charKey = addon:GetCharacterKey()
    local gdb     = addon:GetGuildDb()
    if not gdb then return end
    local now     = GetServerTime()

    -- Augment the transmute catalogue from the alchemy recipe DB.  This
    -- self-heals for clients (Classic Era Anniversary, locale variants)
    -- where the actual transmute spell IDs differ from VANILLA_TRANSMUTES.
    -- Idempotent; cheap; runs every scan so newly-learned transmutes from
    -- guildmate broadcasts get picked up too.
    addon:RefreshTransmuteCatalogueFromRecipes()
    local data    = addon:GetCooldownData()

    if not gdb.cooldowns[charKey] then gdb.cooldowns[charKey] = {} end
    local stored = gdb.cooldowns[charKey]

    -- Snapshot our own cooldown values BEFORE the scan mutates them, so we can
    -- tell whether this scan actually changed anything the Cooldowns tab shows
    -- (using a transmute, salt shaker, etc.) and fire a scoped refresh only then.
    -- A local scan raises no sync-receive signal, and now that the drift churn is
    -- gone there's no incidental redraw to piggyback on — so without this, your
    -- own cooldown starting/finishing wouldn't refresh the tab until the next
    -- guild update. Cheap: a character has only a handful of cooldown entries.
    local beforeScan = {}
    for spellId, expiresAt in pairs(stored) do beforeScan[spellId] = expiresAt end

    -- ---- Transmutes --------------------------------------------------------
    -- All transmutes share one cooldown bucket. Iterate every known transmute
    -- spell ID to find the one currently active, then store the shared expiry
    -- under every transmute the player knows so the cooldowns tab can show
    -- exactly which transmutes they have.
    --
    -- Why we don't gate on IsSpellKnown: on Classic Era, IsSpellKnown returns
    -- false for transmute spell IDs (see docs/bugs.md DATA-004), so the gate
    -- silently blocks both the active-CD store and the Ready seed. Instead we
    -- determine "known transmutes" from the alchemy recipe DB (recipe entries
    -- carry spellId from the spellbook scan) and always include the spell that
    -- was actually found on cooldown so the active CD shows even on first
    -- login before any trade-skill scan has populated recipes.

    local transmuteExpiry, activeTransmuteId = nil, nil
    for spellId in pairs(data.transmutes) do
        local start, duration = GetSpellCooldown(spellId)
        if start and start > 0 and duration and duration > 1.5 then
            local remaining = (start + duration) - GetTime()
            if remaining > 0 and remaining < 691200 then
                transmuteExpiry   = math.floor(now + remaining)
                activeTransmuteId = spellId
                break
            end
        end
    end

    local knownTransmutes = {}
    local alchemyRecipes  = gdb.recipes and gdb.recipes[171]
    if alchemyRecipes then
        for _, rd in pairs(alchemyRecipes) do
            if rd.crafters and rd.crafters[charKey]
            and rd.spellId and data.transmutes[rd.spellId] then
                knownTransmutes[rd.spellId] = true
            end
        end
    end
    if activeTransmuteId then
        knownTransmutes[activeTransmuteId] = true
    end

    for spellId in pairs(data.transmutes) do
        if knownTransmutes[spellId] or IsSpellKnown(spellId, false) then
            if transmuteExpiry then
                stored[spellId] = transmuteExpiry
            elseif not stored[spellId] or (stored[spellId] - now) > 691200 then
                stored[spellId] = now - 1  -- seed as Ready
            end
        end
    end

    -- ---- Non-transmute cooldowns -------------------------------------------

    for spellId in pairs(data.cooldowns) do
        local start, duration = GetSpellCooldown(spellId)
        if start and start > 0 and duration and duration > 1.5 then
            local remaining = GetCooldownLeft(start, duration)
            if remaining > 0 and remaining < 2592000 then
                stored[spellId] = math.floor(now + remaining)
            end
            -- If remaining <= 0 the GCD fired; leave the existing stored entry alone
            -- so "Ready" state (past timestamp) is preserved.
        else
            -- Spell is not on CD.  Seed "Ready" if the character knows it.
            if not stored[spellId] or (stored[spellId] - now) > 2592000 then
                if IsSpellKnown(spellId, false) then
                    stored[spellId] = now - 1  -- past timestamp means Ready
                end
            end
        end
    end

    -- ---- Salt Shaker (Vanilla Leatherworking item) -------------------------

    if addon.isVanilla then
        self:ScanSaltShaker(stored, now, data.saltShakerItem)
    end

    gdb.syncTimes[charKey] = now

    -- Stamp content-derived scan time for v0.2.0 cooldown:<charKey> leaf.
    if not gdb.lastScan[charKey] then gdb.lastScan[charKey] = {} end
    gdb.lastScan[charKey].cooldowns = now

    -- Update the per-member cooldown hash and the guild:cooldowns roll-up.
    local DS = self.DS
    if DS then
        addon.HashManager:InvalidateCharCooldowns(DS, gdb, charKey)
    end

    -- Did this scan change any of our own cooldown values? If so, refresh the UI
    -- with a COOLDOWNS-scoped signal — the Cooldowns tab re-renders, the recipe
    -- Browser (which renders none of this) does not.
    local cooldownsChanged = false
    for spellId, expiresAt in pairs(stored) do
        if beforeScan[spellId] ~= expiresAt then cooldownsChanged = true; break end
    end
    if not cooldownsChanged then
        for spellId in pairs(beforeScan) do
            if stored[spellId] == nil then cooldownsChanged = true; break end
        end
    end
    if cooldownsChanged and addon.callbacks then
        addon.callbacks:Fire("GUILD_DATA_UPDATED", charKey, { cooldowns = true })
    end

    addon:DebugPrint("Scanner: cooldown scan complete for", charKey,
        cooldownsChanged and "(changed → UI refresh)" or "(no change)")
end

-- Walk every recipe's reagent table and resolve missing itemId via
-- GetItemInfoInstant(name).  Needed because pre-v0.1.5 scans (and scans on
-- builds where GetTradeSkillReagentItemLink returns nil) stored reagents
-- with neither itemLink nor itemId, breaking the bank-stock lookup and
-- reagent-watch features that key off the item ID.
--
-- Recovery sources, in order:
--   1. itemLink → tonumber(...:match("item:(%d+)"))      (instant, cache-free)
--   2. GetItemInfoInstant(name)                          (instant, cache-only)
--   3. GetItemInfo(name)                                 (cache + lazy fetch:
--      kicks the client to load the item.  Returns nil on this call but the
--      load resolves async; subsequent backfill retries pick it up via path 2.)
--
-- Scheduled with retries (4s/30s/120s post-PEW) so async loads kicked in pass 1
-- have a chance to resolve in pass 2/3.
function Scanner:BackfillReagentItemIds()
    if not GetItemInfoInstant then
        addon:Print("|cffff4444Backfill: GetItemInfoInstant unavailable|r")
        return
    end
    local gdb = addon:GetGuildDb()
    if not gdb or not gdb.recipes then
        addon:Print("|cffff4444Backfill: no guild DB available|r")
        return
    end

    local checked, fixed, missed = 0, 0, 0
    for _, profRecipes in pairs(gdb.recipes) do
        for _, rd in pairs(profRecipes) do
            if type(rd.reagents) == "table" then
                for _, rg in ipairs(rd.reagents) do
                    if not rg.itemId or rg.itemId == 0 then
                        checked = checked + 1
                        if type(rg.itemLink) == "string" then
                            rg.itemId = tonumber(rg.itemLink:match("item:(%d+)"))
                        end
                        if (not rg.itemId or rg.itemId == 0) and rg.name then
                            rg.itemId = (addon.Item.GetInfoInstant(rg.name))
                        end
                        if (not rg.itemId or rg.itemId == 0) and rg.name and GetItemInfo then
                            -- Cache-loading variant: returns nil on this call if
                            -- the item isn't cached yet, but issues a server-side
                            -- load.  Next retry picks up the result via the
                            -- GetItemInfoInstant path above once the load resolves.
                            local _, link = addon.Item.GetInfo(rg.name)
                            if type(link) == "string" then
                                rg.itemId = tonumber(link:match("item:(%d+)"))
                                if not rg.itemLink or rg.itemLink == "" then
                                    rg.itemLink = link
                                end
                            end
                        end
                        if rg.itemId and rg.itemId > 0 then
                            fixed = fixed + 1
                        else
                            missed = missed + 1
                        end
                    end
                end
            end
        end
    end
    -- Only log when something was actually checked, so silent retry passes
    -- don't spam chat after the data is fully healed.
    if checked > 0 then
        addon:Print(("Backfill: checked=%d fixed=%d missed=%d"):format(checked, fixed, missed))
    end
end

--- One-time PEW scrub: clear any rd.name in gdb.recipes that's a Blizzard
--- internal / dev / QA / placeholder string (TEST / ZZOLD / DEPRECATED /
--- UNUSED / [PH] / OLD-suffix). These got cached by pre-v0.5.5 versions of
--- the addon when MergeCraftersIntoGdb's stub creation called
--- `GetItemInfo(recipeId)` with what was actually a spell ID — and the
--- item-ID namespace collides with the spell-ID namespace for many recipes
--- (e.g. spell 26926 = Heavy Copper Ring; item 26926 = "59 TEST Green
--- Shaman Chest"), so the stub got stamped with the wrong name and persisted
--- in SavedVariables. Clearing the name (rather than overwriting it here)
--- lets BackfillBogusRecipeNames run next and populate it from GetSpellInfo
--- — which is now guarded against the same collision. Also clears stale
--- itemLink/icon when they look item-id-derived, so the next backfill picks
--- up the spell icon instead.
function Scanner:ScrubObsoleteRecipeNames()
    local gdb = addon:GetGuildDb()
    if not gdb or not gdb.recipes then return end
    local scrubbed = 0
    for _, profRecipes in pairs(gdb.recipes) do
        for _, rd in pairs(profRecipes) do
            if isObsoleteItemName(rd.name) then
                rd.name     = nil
                rd.icon     = nil      -- was likely the obsolete item's icon
                rd.itemLink = nil      -- was likely a link to the obsolete item
                scrubbed    = scrubbed + 1
            end
        end
    end
    if scrubbed > 0 then
        addon:Print(("Scrubbed %d obsolete recipe names (TEST/ZZOLD/DEPRECATED/[PH]) from cache"):format(scrubbed))
    end
end

--- Walk gdb.recipes once and recover any missing or placeholder recipe metadata.
--- Two failure modes this fixes:
---   1. Classic Era's GetTradeSkillInfo returns "? <id>" placeholder strings when
---      the item info hasn't loaded into the client cache yet.
---   2. MergeCraftersIntoGdb creates {crafters={}} stubs when a crafters:<profId>
---      leaf arrives before the matching recipemeta:<profId> leaf — leaving the
---      recipe with crafters but no name/icon/links.
--- Recovery sources, in order: existing itemLink/recipeLink [...] field, then
--- GetItemInfo(recipeId) for item-keyed recipes, then GetSpellInfo for spells.
--- Run once on PEW after BackfillReagentItemIds.  Idempotent.
function Scanner:BackfillBogusRecipeNames()
    local gdb = addon:GetGuildDb()
    if not gdb or not gdb.recipes then return end
    local checked, fixed = 0, 0
    for _, profRecipes in pairs(gdb.recipes) do
        for recipeId, rd in pairs(profRecipes) do
            local needsName = isBogusName(rd.name)
            if needsName then
                checked = checked + 1
                local clean = cleanRecipeName(rd.name, rd.itemLink, rd.recipeLink)
                if not isBogusName(clean) then
                    rd.name = clean
                end
            end
            -- Item-keyed recipe (most professions): recipeId IS the crafted item
            -- ID, so GetItemInfo gives us name + icon + a real itemLink.
            -- Reject the result when it matches a Blizzard internal/dev/QA name
            -- (TEST / ZZOLD / DEPRECATED / [PH] / OLD) — the item-ID namespace
            -- collides with the spell-ID namespace for some recipes (e.g. spell
            -- 26926 = Heavy Copper Ring; item 26926 = "59 TEST Green Shaman
            -- Chest"), and we don't want the test name leaking into the UI.
            if isBogusName(rd.name) and rd.isSpell ~= true and type(recipeId) == "number" then
                local nm, link, _, _, _, _, _, _, _, icon = addon.Item.GetInfo(recipeId)
                if nm and not isObsoleteItemName(nm) then
                    rd.name     = rd.name     and not isBogusName(rd.name)     and rd.name     or nm
                    rd.icon     = rd.icon     or icon
                    rd.itemLink = rd.itemLink or link
                end
            end
            -- Spell-keyed recipe (enchanting / craft frame): try GetSpellInfo.
            -- Run regardless of the isSpell flag because (a) GetSpellInfo
            -- returns nil for non-spell IDs so there are no false positives,
            -- and (b) stubs created by MergeCraftersIntoGdb when crafters:<pid>
            -- arrives before recipemeta:<pid> leave isSpell/spellId both unset.
            -- Without this fallback, Enchanting recipeIds (which ARE the
            -- enchant spell ID) stay as "? <id>" forever — /togpm backfill
            -- can't fix them because the spell branch never runs. When the
            -- lookup succeeds we backfill isSpell + spellId so future tooltip
            -- resolution in BrowserTab uses SetSpellByID instead of falling
            -- through to "item:<id>" (which produces "Retrieving item
            -- information" for spell-only IDs).
            if isBogusName(rd.name) and type(recipeId) == "number" and GetSpellInfo then
                local sid = rd.spellId or recipeId
                local nm, _, icon = GetSpellInfo(sid)
                if nm then
                    rd.name    = nm
                    rd.icon    = rd.icon or icon
                    rd.isSpell = true
                    rd.spellId = rd.spellId or sid
                end
            end
            if needsName and not isBogusName(rd.name) then
                fixed = fixed + 1
            end
        end
    end
    if checked > 0 then
        addon:Print(("Recipe-name backfill: checked=%d fixed=%d"):format(checked, fixed))
    end
end

function Scanner:ScanSaltShaker(stored, now, itemId)
    if not itemId then return end
    -- The item-cooldown API differs across Classic builds: newer clients expose
    -- C_Container.GetItemCooldown, older ones the global GetItemCooldown, and some
    -- recent Classic Era builds ship one but not the other (mirroring the
    -- GetContainerItemInfo → C_Container move that forced the Compat shims). The
    -- old code called ONLY the namespaced form, so a client where it's absent — or
    -- present but returning nothing — never detected the cooldown and rendered
    -- "Ready" forever. Try the namespaced call first, then FALL BACK ON THE RESULT
    -- (not just existence) to the global, so either failure mode is covered.
    local start, duration
    if C_Container and C_Container.GetItemCooldown then
        start, duration = C_Container.GetItemCooldown(itemId)
    end
    if (not start or start == 0) and GetItemCooldown then
        start, duration = GetItemCooldown(itemId)
    end

    if start and start > 0 and duration and duration > 1.5 then
        local remaining = GetCooldownLeft(start, duration)
        if remaining > 0 and remaining < 345600 then
            stored[itemId] = math.floor(now + remaining)
            addon:DebugPrint("Scanner: salt shaker on cooldown,", remaining, "s remaining")
            return
        end
    end
    addon:DebugPrint("Scanner: salt shaker NOT on cooldown — start=",
        tostring(start), "duration=", tostring(duration),
        "hasC_Container=", tostring(C_Container and C_Container.GetItemCooldown ~= nil),
        "hasGlobal=", tostring(GetItemCooldown ~= nil))

    -- Not on cooldown (or bogus value). Seed to Ready if player owns item (incl. bank).
    if not stored[itemId] or (stored[itemId] - now) > 691200 then
        local count = addon.Item.GetCount(itemId, true) or 0
        if count and count > 0 then
            stored[itemId] = now - 1
        end
    end
end

-- ---------------------------------------------------------------------------
-- Broadcast helpers
-- ---------------------------------------------------------------------------

--- Schedule a debounced broadcast (0.5 s coalesce window).
function Scanner:ScheduleBroadcast()
    if self._pendingBroadcast then return end
    self._pendingBroadcast = true
    Ace:ScheduleTimer(function()
        self._pendingBroadcast = false
        self:BroadcastHashes()
    end, 0.5)
end

--- v0.2.0 — Broadcast our L0 leaf-hash list to the guild.
-- Differential: only sends leaves whose (hash, updatedAt) tuple has changed
-- since our last broadcast.  Steady-state broadcasts are typically empty (no
-- entries) when no local content has changed; in that case we skip the send
-- entirely.  Suppressed by debounce within self._broadcastSeconds.
function Scanner:BroadcastHashes()
    local DS = self.DS
    if not DS then return end
    -- Belt-and-suspenders: never broadcast no-guild data. addon:GetGuildDb()
    -- now falls back to a synthetic NoGuildBucketKey bucket when guildless,
    -- so this guard is what keeps that bucket's contents off the wire.
    if not addon:GetGuildKey() then return end

    local now = GetServerTime()
    if (now - self._lastBroadcastAt) < self._broadcastSeconds then
        addon:DebugPrint("Scanner: broadcast suppressed (debounce)")
        return
    end

    local gdb = addon:GetGuildDb()
    if not gdb then return end

    local current = addon.HashManager:GetL0BroadcastMap(gdb)
    -- Pad placeholders so peers offer data for professions we have no
    -- local content for. See HashManager:PadMissingProfessionPlaceholders.
    addon.HashManager:PadMissingProfessionPlaceholders(DS, current)
    local last    = self._lastBroadcastHashes or {}
    local delta   = {}
    local count   = 0
    for k, v in pairs(current) do
        local prev = last[k]
        if not prev or prev.hash ~= v.hash or prev.updatedAt ~= v.updatedAt then
            delta[k] = v
            count = count + 1
        end
    end
    if count == 0 then
        addon:DebugPrint("Scanner: no hash changes — broadcast skipped")
        return
    end

    local _ok, offerBytes = DS:BroadcastItemHashes(delta, "BULK")
    -- Snapshot the FULL current map (not just delta) so future broadcasts
    -- diff against everything we've ever broadcast, not just the last delta.
    self._lastBroadcastHashes = current
    self._lastBroadcastAt = now
    addon:DebugPrint("Scanner: broadcast", count, "leaf hashes")
    if addon.callbacks then
        addon.callbacks:Fire("SYNC_SENT", "guild", tonumber(offerBytes) or 0, "offer: " .. count .. " hashes")
    end
end

--- " (Leatherworking)" suffix for a profId, so a sync-log line reads
--- "crafters:165 (Leatherworking)" instead of the bare, unreadable "crafters:165".
--- Empty string when the id is nil or unknown, so it's safe to concatenate blindly.
function Scanner:_ProfSuffix(profId)
    local name = profId and addon.PROF_NAMES and addon.PROF_NAMES[profId]
    return name and (" (" .. name .. ")") or ""
end

--- v0.2.0 — Broadcast a single leaf's data to the guild on the DATA channel.
-- Called in response to a leaf-data request from a peer.  All peers on the
-- guild channel see the broadcast; any with stale data for the same leaf
-- merges via OnGuildDataReceived.
-- @param players  optional set { [charKey]=true } passed through to BuildLeafPayload
--   to ship a SCOPED crafters:<profId> leaf (just those crafters) in response to a
--   player-leaf drill-down request. nil = full leaf (legacy whole-profession reply).
function Scanner:BroadcastLeafToGuild(itemKey, players)
    local DS = self.DS
    if not DS then return end
    if not addon:GetGuildKey() then return end  -- never broadcast no-guild data

    -- Serve-side coalescing (whole-leaf only). A leaf serve is a GUILD-WIDE broadcast,
    -- so re-sending the SAME VERSION seconds later reaches nobody new — but every peer's
    -- request triggers its own broadcast, so a leaf that many peers want (e.g. the one
    -- client actually holding real cooldown data in a mixed-version guild) gets spammed
    -- to everyone over and over. Coalesce only a repeat of the SAME hash within the
    -- window. CRITICAL: a CHANGED leaf (new hash — the owner just started/updated a
    -- cooldown) must always go out immediately, or the coalesce swallows the very update
    -- peers are waiting for (this stalled 2-client cooldown sync). Scoped crafter replies
    -- (players set) legitimately vary by which players were asked, so they're exempt.
    if not players then
        local cgdb    = addon:GetGuildDb()
        local curHash = cgdb and cgdb.hashes and cgdb.hashes[itemKey] and cgdb.hashes[itemKey].hash
        local last    = self._lastLeafBroadcast and self._lastLeafBroadcast[itemKey]
        if last and last.hash == curHash and (GetServerTime() - last.at) < 10 then
            addon:DebugPrint("Scanner: leaf serve coalesced (same version):", itemKey)
            return
        end
    end

    local payload = self:BuildLeafPayload(itemKey, players)
    if not payload then
        addon:DebugPrint("Scanner: BroadcastLeafToGuild — no content for", itemKey)
        -- Self-heal: we advertised a hash for a leaf we hold no data for (an orphan
        -- hash that gossiped in via subhashes). Drop it so we stop advertising it and
        -- so a fresh stamp=-1 request can pull the owner's real data. Only for an
        -- UNSCOPED request — a scoped crafters reply can legitimately have no content
        -- for the asked players without the whole leaf being orphaned.
        if not players and self.DS then
            local gdb = addon:GetGuildDb()
            if gdb and addon.HashManager:DropOrphanLeaf(self.DS, gdb, itemKey) then
                addon:DebugPrint("Scanner:   → dropped ORPHAN hash (advertised, no data):", itemKey)
            end
        end
        return
    end
    local _ok, sentBytes = DS:BroadcastData(payload, "GUILD", "BULK")
    if not players then
        self._lastLeafBroadcast = self._lastLeafBroadcast or {}
        local sentLeaf = payload.leaves and payload.leaves[itemKey]
        self._lastLeafBroadcast[itemKey] = { hash = sentLeaf and sentLeaf.hash, at = GetServerTime() }
    end
    if DS.p2p then
        DS.p2p:OnItemCompleted(itemKey, addon:GetCharacterKey())
    end
    addon:DebugPrint("Scanner: broadcast leaf", itemKey, players and "(scoped)" or "")
    if addon.callbacks then
        local detail = itemKey .. self:_ProfSuffix(tonumber(itemKey:match("^crafters:(%d+)")))
        if players then
            local names = {}
            for ck in pairs(players) do names[#names + 1] = ck end
            table.sort(names)
            detail = detail .. " {" .. table.concat(names, ", ") .. "}"
        end
        addon.callbacks:Fire("SYNC_SENT", "guild", tonumber(sentBytes) or 0, detail)
    end
end

--- v0.2.0 — Broadcast a sub-hash list for a roll-up parent.
-- Called in response to a subhashes request.  Receiver compares per-character
-- hashes locally and follows up with leaf-data requests for differing leaves.
function Scanner:BroadcastSubhashesToGuild(parentItemKey)
    local DS = self.DS
    if not DS then return end
    if not addon:GetGuildKey() then return end  -- never broadcast no-guild data
    local gdb = addon:GetGuildDb()
    if not gdb then return end
    local HM = addon.HashManager

    -- Serve-side coalescing, same idea as BroadcastLeafToGuild: a subhash list is a
    -- GUILD-WIDE broadcast, so if several peers request the same roll-up's subhashes at
    -- once (a login storm, or many clients whose roll-up drifted this cycle), we'd send
    -- the whole list — 20 KB+ for guild:accountchars — once per requester. Coalesce only
    -- when the roll-up is UNCHANGED since our last send (same parent hash): if any
    -- underlying leaf changed, peers need the fresh list now — don't swallow it. NOTE:
    -- this only collapses BURSTS — it does nothing for the steady ~per-minute re-requests
    -- driven by an un-converged roll-up (that only settles once peers are on the new code).
    local curRollup = gdb.hashes and gdb.hashes[parentItemKey] and gdb.hashes[parentItemKey].hash
    local last      = self._lastSubhashBroadcast and self._lastSubhashBroadcast[parentItemKey]
    if last and last.hash == curRollup and (GetServerTime() - last.at) < 10 then
        addon:DebugPrint("Scanner: subhash serve coalesced (unchanged):", parentItemKey)
        return
    end

    local subhashes
    if parentItemKey == "guild:cooldowns" then
        subhashes = HM:GetCooldownLevelMap(gdb)
    elseif parentItemKey == "guild:accountchars" then
        subhashes = HM:GetAccountCharsLevelMap(gdb)
    elseif parentItemKey == "guild:skills" then
        subhashes = HM:GetSkillsLevelMap(gdb)
    elseif parentItemKey == "guild:professions" then
        subhashes = HM:GetProfessionsLevelMap(gdb)
    else
        addon:DebugPrint("Scanner: BroadcastSubhashesToGuild — unknown parent", parentItemKey)
        return
    end

    local payload = {
        charKey   = addon:GetCharacterKey(),
        guildKey  = addon:GetGuildKey(),
        timestamp = GetServerTime(),
        type      = "subhashes",
        parent    = parentItemKey,
        subhashes = subhashes,
        subsync   = 1,   -- presence beacon (see BuildLeafPayload)
    }
    local _ok, sentBytes = DS:BroadcastData(payload, "GUILD", "BULK")
    self._lastSubhashBroadcast = self._lastSubhashBroadcast or {}
    self._lastSubhashBroadcast[parentItemKey] = {
        hash = gdb.hashes and gdb.hashes[parentItemKey] and gdb.hashes[parentItemKey].hash,
        at   = GetServerTime(),
    }
    addon:DebugPrint("Scanner: broadcast subhashes for", parentItemKey)
    if addon.callbacks then
        addon.callbacks:Fire("SYNC_SENT", "guild", tonumber(sentBytes) or 0, "subhashes: " .. parentItemKey)
    end
end

--- Respond to a player-subhashes request: broadcast the per-(player) hash list for
--- one profession so the requester diffs locally and pulls only the players whose
--- recipe set differs (newest ts first). Sibling to BroadcastSubhashesToGuild, but
--- for the optional crafters:<profId> drill-down level. GUILD broadcast so any peer
--- with a stale view of these players merges for free. Old clients never send the
--- "player-subhashes" request, so this only ever fires toward a new requester.
function Scanner:BroadcastPlayerSubhashes(profId)
    local DS = self.DS
    if not DS then return end
    if not addon:GetGuildKey() then return end
    local gdb = addon:GetGuildDb()
    if not gdb then return end
    local players = addon.HashManager:GetProfessionPlayerSubhashes(DS, gdb, profId)
    local nPlayers = 0
    for _ in pairs(players) do nPlayers = nPlayers + 1 end
    if nPlayers == 0 then
        addon:DebugPrint("Scanner: BroadcastPlayerSubhashes — no crafters for prof", profId)
        return
    end
    local payload = {
        charKey   = addon:GetCharacterKey(),
        guildKey  = addon:GetGuildKey(),
        timestamp = GetServerTime(),
        type      = "player-subhashes",
        profId    = profId,
        players   = players,
        subsync   = 1,
    }
    local _ok, sentBytes = DS:BroadcastData(payload, "GUILD", "BULK")
    addon:DebugPrint("Scanner: broadcast player-subhashes for prof", profId, "(", nPlayers, "players )")
    if addon.callbacks then
        addon.callbacks:Fire("SYNC_SENT", "guild", tonumber(sentBytes) or 0,
            "player-subhashes: " .. profId .. self:_ProfSuffix(profId) .. " (" .. nPlayers .. " players)")
    end
end

--- Has this peer advertised per-player drill-down capability? True once we've seen
--- any payload carrying the subsync presence beacon from them (recorded in
--- OnGuildDataReceived). Until then we use the whole-profession path — so the first
--- profession from a peer syncs the legacy way and subsequent ones drill down.
--- Keyed by normalized charKey to match OnGuildDataReceived's senderKey.
function Scanner:PeerSupportsSubSync(peerName)
    if not peerName or not self._subsyncPeers then return false end
    local key = peerName
    if self.GuildRoster and self.GuildRoster.NormalizeName then
        key = self.GuildRoster:NormalizeName(peerName) or peerName
    end
    return self._subsyncPeers[key] and true or false
end

--- v0.2.0 — Build a wire payload containing one leaf's data.
-- Returns nil when the local player has no content for itemKey.
-- @param players  optional set { [charKey]=true } — for a crafters:<profId> leaf,
--   restrict the payload to just these crafters (the per-player drill-down's scoped
--   leaf). nil = the full profession leaf (every crafter), the legacy behavior.
--   The result is still a normal crafters:<profId> leaf, so old receivers merge it
--   unchanged (union-add, or own-scan replace when the sender is among `players`).
function Scanner:BuildLeafPayload(itemKey, players)
    local gdb = addon:GetGuildDb()
    if not gdb then return nil end
    local now = GetServerTime()

    local payload = {
        charKey   = addon:GetCharacterKey(),
        guildKey  = addon:GetGuildKey(),
        timestamp = now,
        leaves    = {},
        -- Presence beacon for the optional per-player drill-down. Old clients
        -- ignore this field; new clients record the sender as drill-down capable
        -- (Scanner._subsyncPeers) so future crafters mismatches fetch per player
        -- instead of the whole profession. Version-independent on purpose — works
        -- on raw/unpackaged clients where the .toc version is @project-version@.
        subsync   = 1,
    }
    local lastScanOut = {}
    local entry = gdb.hashes and gdb.hashes[itemKey] or nil

    if itemKey:sub(1, 9) == "cooldown:" then
        local owner  = itemKey:sub(10)
        local bucket = gdb.cooldowns and gdb.cooldowns[owner]
        if not bucket or not next(bucket) then return nil end
        -- v0.10.11: ship ABSOLUTE expiry timestamps (server-time), NOT relative
        -- remaining. GetServerTime() is one shared clock for the whole guild, so
        -- an absolute expiry is directly comparable on every client and survives
        -- relay byte-for-byte — every receiver stores exactly what the owner
        -- minted, so the leaf hash converges instead of drifting upward by the
        -- transmission latency on each hop (the old now+remaining reconstruction
        -- inflated the value, changed the hash, and re-triggered sync forever).
        -- `abs = 1` marks the new format: v0.10.11+ receivers REQUIRE it and drop
        -- legacy relative payloads; pre-v0.10.11 receivers see ~1.7e9 values fail
        -- their `< 2592000` guard and simply ignore them (graceful, no crash).
        local cdAbs = {}
        for spellId, expiresAt in pairs(bucket) do
            if type(expiresAt) == "number" then cdAbs[spellId] = expiresAt end
        end
        payload.leaves[itemKey] = {
            data      = cdAbs,
            hash      = entry and entry.hash      or 0,
            -- Revision-2 token, shipped alongside. Absent when this leaf is
            -- still V1-only, which tells the receiver to compare on revision 1.
            hashV2    = entry and entry.hashV2,
            updatedAt = entry and entry.updatedAt or 0,
            abs       = 1,
        }
        local ls = gdb.lastScan and gdb.lastScan[owner]
        if ls and ls.cooldowns then
            lastScanOut[owner] = { cooldowns = ls.cooldowns }
        end

    elseif itemKey:sub(1, 13) == "accountchars:" then
        local owner = itemKey:sub(14)
        -- v0.7.0: per-broadcaster alt-group arrays live under altClaims to
        -- avoid colliding with the boolean-flag accountChars set.
        local group = gdb.altClaims and gdb.altClaims[owner]
        if not group or #group == 0 then return nil end
        payload.leaves[itemKey] = {
            data      = group,
            hash      = entry and entry.hash      or 0,
            -- Revision-2 token, shipped alongside. Absent when this leaf is
            -- still V1-only, which tells the receiver to compare on revision 1.
            hashV2    = entry and entry.hashV2,
            updatedAt = entry and entry.updatedAt or 0,
        }
        local ls = gdb.lastScan and gdb.lastScan[owner]
        if ls and ls.accountchars then
            lastScanOut[owner] = { accountchars = ls.accountchars }
        end

    elseif itemKey:sub(1, 12) == "professions:" then
        -- v1.0.3: the OWNER-AUTHORITATIVE full profession snapshot for one character
        -- — EVERY profession they currently have (crafting AND gathering), so a
        -- profession they DROPPED (absent here) is deleted on every peer rather than
        -- lingering forever. A SEPARATE leaf from skills: so un-updated clients (which
        -- don't know this key) are wholly undisturbed — zero rollout churn. The hash
        -- is the owner's minted token, shipped + relayed VERBATIM (receivers never
        -- recompute) exactly like cooldowns.
        local owner = itemKey:sub(13)
        local snapshot = addon.HashManager:GetProfessionSnapshot(gdb, owner)
        if not next(snapshot) then return nil end
        payload.leaves[itemKey] = {
            data      = snapshot,
            hash      = entry and entry.hash      or 0,
            -- Revision-2 token, shipped alongside. Absent when this leaf is
            -- still V1-only, which tells the receiver to compare on revision 1.
            hashV2    = entry and entry.hashV2,
            updatedAt = entry and entry.updatedAt or 0,
        }
        local ls = gdb.lastScan and gdb.lastScan[owner]
        if ls and ls.professions then
            lastScanOut[owner] = { professions = ls.professions }
        end

    elseif itemKey:sub(1, 7) == "skills:" then
        -- v1.0.0: a character's GATHERING-profession skills (Herbalism / Skinning /
        -- Fishing / Archaeology) — the recipe-less professions that have no crafters
        -- leaf to ride. Owner-authoritative + relayed like every other leaf.
        -- UNCHANGED — the v1.0.3 dropped-profession work lives on professions: above.
        local owner = itemKey:sub(8)
        local skills = addon.HashManager:GetGatheringSkills(gdb, owner)
        if not next(skills) then return nil end
        payload.leaves[itemKey] = {
            data      = skills,
            hash      = entry and entry.hash      or 0,
            -- Revision-2 token, shipped alongside. Absent when this leaf is
            -- still V1-only, which tells the receiver to compare on revision 1.
            hashV2    = entry and entry.hashV2,
            updatedAt = entry and entry.updatedAt or 0,
        }
        local ls = gdb.lastScan and gdb.lastScan[owner]
        if ls and ls.skills then
            lastScanOut[owner] = { skills = ls.skills }
        end

    -- v0.7.0: recipemeta: leaf removed entirely. All recipe metadata (name,
    -- icon, reagents, links) lives in the shipped addon.recipeDB and is looked
    -- up by recipeId at display time. The receiver never needs name/icon over
    -- the wire — they have it locally.

    elseif itemKey:sub(1, 9) == "crafters:" then
        local profId = tonumber(itemKey:sub(10))
        if not profId or not gdb.recipes or not gdb.recipes[profId] then return nil end
        -- v0.10.2: ship the per-crafter ORIGIN guild tag (already stored in gdb
        -- as crafters[ck] = guildTag) instead of a bare `true`. This lets a
        -- relaying "bridge" member rebroadcast cross-guild ("sister") crafters
        -- into its home guild WITHOUT them being re-stamped as the home guild —
        -- attribution survives the relay. Backward compatible both ways:
        --   * the crafters-leaf HASH is unaffected (ComputeCraftersHash
        --     normalizes every value to true before hashing), so old/new clients
        --     stay in sync — no version bump, no desync churn;
        --   * old receivers iterate keys and treat any truthy value as present,
        --     degrading to the pre-v0.10.2 "tag by my own guild" behavior.
        -- The receiver (MergeCraftersIntoGdb) prefers the shipped string tag and
        -- falls back to its sender-derived tag for legacy `true` values.
        local crafters = {}
        local hasCrafters = false
        for recipeId, rd in pairs(gdb.recipes[profId]) do
            if rd.crafters and next(rd.crafters) then
                local set = {}
                for ck, v in pairs(rd.crafters) do
                    if v and (not players or players[ck]) then set[ck] = v end
                end
                if next(set) then
                    crafters[recipeId] = set
                    hasCrafters = true
                end
            end
        end
        if not hasCrafters then return nil end
        payload.leaves[itemKey] = {
            data      = crafters,
            hash      = entry and entry.hash      or 0,
            -- Revision-2 token, shipped alongside. Absent when this leaf is
            -- still V1-only, which tells the receiver to compare on revision 1.
            hashV2    = entry and entry.hashV2,
            updatedAt = entry and entry.updatedAt or 0,
        }
        -- Include skill ranks for everyone who crafts in this profession.
        if gdb.skills then
            local skillsOut = {}
            for ck, charSkills in pairs(gdb.skills) do
                local s = charSkills[profId]
                if s and (not players or players[ck]) then
                    skillsOut[ck] = { skillRank = s.skillRank, skillMax = s.skillMax }
                end
            end
            if next(skillsOut) then payload.skills = { [profId] = skillsOut } end
        end
        -- Include profession-spec (TBC alchemy / tailoring) for everyone in
        -- this profession. Drives the bonus-output indicator on the Cooldowns
        -- tab. Same opportunistic-piggyback model as skills above — propagates
        -- on the next crafters: leaf transfer rather than triggering its own
        -- broadcast on spec acquisition (which is a one-time event per char).
        if gdb.specializations then
            local specsOut = {}
            for ck, charSpecs in pairs(gdb.specializations) do
                local sid = charSpecs[profId]
                if sid and (not players or players[ck]) then specsOut[ck] = sid end
            end
            if next(specsOut) then payload.specializations = { [profId] = specsOut } end
        end
        if gdb.lastScan then
            for _, rd in pairs(gdb.recipes[profId]) do
                for ck in pairs(rd.crafters or {}) do
                    local ls = gdb.lastScan[ck]
                    if ls and ls[profId] and (not players or players[ck]) then
                        if not lastScanOut[ck] then lastScanOut[ck] = {} end
                        lastScanOut[ck][profId] = ls[profId]
                    end
                end
            end
        end

    else
        return nil
    end

    if next(lastScanOut) then payload.lastScan = lastScanOut end
    return payload
end

-- Cross-guild (v0.10.1): build a payload carrying ONLY our own guild's crafter
-- leaves, served over a directed WHISPER to a sister-guild peer that asked via a
-- "sister-pull" request.
--
-- Two correctness rules baked in:
--   1. Serve only crafters tagged with OUR home guild tag. The crafters: leaf
--      ships bare charKeys and the receiver tags them all with our guildKey, so
--      re-serving sister data we previously pulled would re-tag THEIR members as
--      ours — cross-guild attribution corruption. Filtering by tag keeps each
--      guild authoritative for its own membership.
--   2. Opt-in: only share if we participate in a confederation (have an allied
--      guild configured). Non-participating users never serve their data.
--
-- Cooldowns / account-char groups are intentionally NOT shared cross-guild yet
-- (crafters — "who can craft X" — are the core value; cooldown sharing needs its
-- own member-filtering and comes later). Returns nil when guildless, not opted
-- in, or we have no own-guild crafters.
function Scanner:BuildFullGuildPayload()
    local gdb = addon:GetGuildDb()
    if not gdb then return nil end
    if not addon:GetGuildKey() then return nil end          -- never serve no-guild data
    if #addon:GetSisterGuilds() == 0 then return nil end     -- opt-in gate

    local myTag = addon:GetCurrentGuildTag()
    local out = {
        charKey   = addon:GetCharacterKey(),
        guildKey  = addon:GetGuildKey(),
        timestamp = GetServerTime(),
        leaves    = {},
    }
    local skillsOut, specsOut, lastScanOut = {}, {}, {}

    for profId, profRecipes in pairs(gdb.recipes or {}) do
        local crafters, ourCks, has = {}, {}, false
        for recipeId, rd in pairs(profRecipes) do
            if rd.crafters then
                local set = {}
                for ck, t in pairs(rd.crafters) do
                    if t == myTag then set[ck] = true; ourCks[ck] = true; has = true end
                end
                if next(set) then crafters[recipeId] = set end
            end
        end
        if has then
            local key   = "crafters:" .. profId
            local entry = gdb.hashes and gdb.hashes[key]
            out.leaves[key] = {
                data      = crafters,
                hash      = entry and entry.hash      or 0,
                updatedAt = entry and entry.updatedAt or 0,
            }
            if gdb.skills then
                local s = {}
                for ck in pairs(ourCks) do
                    local cs = gdb.skills[ck] and gdb.skills[ck][profId]
                    if cs then s[ck] = { skillRank = cs.skillRank, skillMax = cs.skillMax } end
                end
                if next(s) then skillsOut[profId] = s end
            end
            if gdb.specializations then
                local sp = {}
                for ck in pairs(ourCks) do
                    local sid = gdb.specializations[ck] and gdb.specializations[ck][profId]
                    if sid then sp[ck] = sid end
                end
                if next(sp) then specsOut[profId] = sp end
            end
            if gdb.lastScan then
                for ck in pairs(ourCks) do
                    local ls = gdb.lastScan[ck]
                    if ls and ls[profId] then
                        lastScanOut[ck] = lastScanOut[ck] or {}
                        lastScanOut[ck][profId] = ls[profId]
                    end
                end
            end
        end
    end

    if not next(out.leaves) then return nil end
    if next(skillsOut)   then out.skills          = skillsOut   end
    if next(specsOut)    then out.specializations = specsOut    end
    if next(lastScanOut) then out.lastScan        = lastScanOut end
    return out
end

-- Cross-guild (v0.10.1): ask an online sister-guild peer for their full guild
-- dataset over a directed WHISPER. Their onDataRequest serves it back via
-- whisper; our OnGuildDataReceived merges it, tagging crafters with their
-- guild's tag. The host supplies the peer (manual /togpm pullroster, or the
-- future /who discovery).
function Scanner:RequestSisterData(peer)
    local DS = self.DS
    if not DS or not DS.RequestData or not peer or peer == "" then return end
    -- Attach our identity + consent proof so the provider's bilateral gate can
    -- verify mutual federation: parent = our home guild key (so they can check
    -- they list us), keys = our sister-guild key SET (so they can confirm we
    -- list them). Only {hash, version, keys, type, parent} survive baseline
    -- serialization, hence this encoding.
    DS:RequestData(peer, {
        type   = "sister-pull",
        parent = addon:GetGuildKey(),
        keys   = addon:GetSisterGuildKeySet(),
    })
    addon:DebugPrint("Scanner: requested sister data from", peer)
end

-- ---------------------------------------------------------------------------
-- Receive & merge guild data
-- ---------------------------------------------------------------------------

--- Rebuild gdb.altGroups (denormalized lookup) from gdb.altClaims
--- (per-broadcaster authoritative).
--- Each member of any group gets a pointer to the same group array.
function Scanner:RebuildAltGroups(gdb)
    gdb.altGroups = {}
    for _, group in pairs(gdb.altClaims or {}) do
        if type(group) == "table" then
            for _, member in ipairs(group) do
                gdb.altGroups[member] = group
            end
        end
    end
end

--- Merge recipe metadata for one profession (incoming from a recipemeta:<profId>
--- leaf payload).  Preserves richest non-nil per field.  Reagents merge per
--- entry via mergeReagents so peers with partial reagent data don't wipe
--- richer data on receive.  Crafters set is left untouched — that lives in
--- the crafters:<profId> leaf.
function Scanner:MergeRecipeMetaIntoGdb(gdb, profId, meta)
    if type(meta) ~= "table" then return end
    if not gdb.recipes[profId] then gdb.recipes[profId] = {} end
    local profRecipes = gdb.recipes[profId]
    for recipeId, rd in pairs(meta) do
        if type(rd) == "table" then
            -- Cross-guildmate poison containment: if the sender's gdb is
            -- still carrying a Blizzard internal/dev/QA name (TEST / ZZOLD /
            -- DEPRECATED / [PH]) from a pre-v0.5.5 stub, do NOT propagate it
            -- into ours. Treat the incoming name as missing — the local
            -- BackfillBogusRecipeNames pass will populate from GetSpellInfo.
            -- Without this guard, ONE poisoned client's broadcast re-infects
            -- everyone via MergeRecipeMetaIntoGdb every time they sync.
            local incomingName = rd.name
            if isObsoleteItemName(incomingName) then incomingName = nil end
            local existing = profRecipes[recipeId]
            if not existing then
                profRecipes[recipeId] = {
                    name       = cleanRecipeName(incomingName, rd.itemLink, rd.recipeLink),
                    icon       = rd.icon,
                    isSpell    = rd.isSpell and true or false,
                    spellId    = rd.spellId,
                    itemLink   = asString(rd.itemLink),
                    recipeLink = asString(rd.recipeLink),
                    reagents   = mergeReagents(nil, rd.reagents),
                    crafters   = {},
                }
            else
                -- Self-heal: if the stored name is a "? <id>" placeholder OR
                -- an obsolete-marker leftover from a pre-v0.5.5 cache, replace
                -- it with whatever the new payload (or our existing links)
                -- can produce.
                if isBogusName(existing.name) or isObsoleteItemName(existing.name) then
                    local clean = cleanRecipeName(incomingName,
                        rd.itemLink   or existing.itemLink,
                        rd.recipeLink or existing.recipeLink)
                    if not isBogusName(clean) and not isObsoleteItemName(clean) then
                        existing.name = clean
                    else
                        existing.name = nil  -- let backfill repopulate via GetSpellInfo
                    end
                elseif incomingName and not existing.name then
                    existing.name = incomingName
                end
                if rd.icon    and not existing.icon    then existing.icon    = rd.icon    end
                if rd.isSpell ~= nil and existing.isSpell == nil then
                    existing.isSpell = rd.isSpell and true or false
                end
                if rd.spellId and not existing.spellId then existing.spellId = rd.spellId end
                if asString(rd.itemLink)   and not existing.itemLink   then existing.itemLink   = rd.itemLink   end
                if asString(rd.recipeLink) and not existing.recipeLink then existing.recipeLink = rd.recipeLink end
                if type(rd.reagents) == "table" then
                    local merged = mergeReagents(existing.reagents, rd.reagents)
                    if merged then existing.reagents = merged end
                end
            end
        end
    end
end

--- Merge incoming crafters set for one profession into gdb.recipes[profId].
--- @param senderClaimsOwnScan  true if the sender authoritatively claims this
---                             is their own scan output for this profession.
---                             Triggers wipe-then-re-add for the sender's
---                             charKey so unlearned recipes get removed.
---                             Relayed data (false) is union-add only.
function Scanner:MergeCraftersIntoGdb(gdb, profId, crafters, senderKey, senderClaimsOwnScan, originTag)
    if type(crafters) ~= "table" then return false end
    if not gdb.recipes[profId] then gdb.recipes[profId] = {} end
    local profRecipes = gdb.recipes[profId]

    -- Tracks whether this merge actually wrote NEW/different crafter data, so the
    -- caller can skip the UI redraw when a peer just re-sent data we already had.
    local changed = false

    -- Hide recipes the local addon DB doesn't know about (sender's addon is
    -- newer / has SoD content we don't ship yet). We could store them as
    -- unknown rows, but the UI hides them anyway — no point bloating the DB.
    local localProfDB = addon.recipeDB and addon.recipeDB[profId]

    -- Per-crafter guild tag. originTag is the SENDER's guild tag, derived from
    -- the payload's guildKey by OnGuildDataReceived — correct for both intra-
    -- guild data (equals our own tag) and cross-guild "sister" data (the
    -- sender's guild). Falls back to our current guild tag for legacy payloads
    -- that carry no guildKey, preserving the original receiver-tags behavior.
    local tag = originTag or addon:GetCurrentGuildTag()

    -- Federation merge gate: only STORE crafters whose guild tag is our home,
    -- our own alts, or a CONFIGURED sister. Data for a guild we don't federate
    -- with — even when it arrives relayed inside a home-guild broadcast — is
    -- dropped, never stored and never re-relayed. With no sisters configured the
    -- set collapses to {home, personal}, giving purely-local operation.
    local allowedTags = addon:GetAllowedGuildTagSet()

    if senderClaimsOwnScan and senderKey then
        for _, rd in pairs(profRecipes) do
            if rd.crafters and rd.crafters[senderKey] ~= nil then
                rd.crafters[senderKey] = nil
                changed = true
            end
        end
    end

    for recipeId, ckSet in pairs(crafters) do
        if type(ckSet) == "table" then
            -- v0.7.1: peers running on Vanilla (or v0.7.0 pre-key-fix on
            -- HC) may broadcast crafter sets keyed by crafted-item-ID
            -- instead of spell-ID. Resolve to spell-ID before storing so
            -- the cross-reference with addon.recipeDB works.
            local effectiveId = recipeId
            if localProfDB and not localProfDB[recipeId] then
                local spellId = addon:GetSpellIdForCraftedItem(profId, recipeId)
                if spellId then effectiveId = spellId end
            end
            if not localProfDB or localProfDB[effectiveId] then
                local existing = profRecipes[effectiveId]
                if not existing then
                    existing = { crafters = {} }
                    profRecipes[effectiveId] = existing
                end
                if not existing.crafters then existing.crafters = {} end
                for ck, v in pairs(ckSet) do
                    if v and type(ck) == "string" then
                        -- Resolve the crafter's effective tag.
                        local effTag
                        if type(v) == "string" then
                            -- Explicit shipped origin tag (v0.10.2+ peer) is
                            -- authoritative — preserves cross-guild attribution
                            -- through a relay.
                            effTag = v
                        else
                            -- Legacy bare `true`: tag by the sender's guild, BUT
                            -- never let it clobber an attribution we already hold.
                            -- An un-updated guildmate re-broadcasting a relayed
                            -- sister crafter strips the tag; without this guard a
                            -- single old client flips the crafter back to the home
                            -- guild → the gate purges it → endless add/purge churn
                            -- (mixed-version rollout). The roster gate, not the
                            -- tag, decides visibility, so a genuine leaver is still
                            -- purged — keeping a known tag here is always safe.
                            local cur = existing.crafters[ck]
                            if cur and cur ~= addon.PersonalTag and cur ~= tag then
                                effTag = cur
                            else
                                effTag = tag
                            end
                        end
                        -- Resurrection guard (v1.0.3): if we hold a COMPLETE
                        -- authoritative profession snapshot for this crafter and it
                        -- does NOT include this profession, they dropped it — a stale
                        -- relay of an old crafters leaf must not re-add them. An own
                        -- scan that genuinely re-learned it refreshes that snapshot to
                        -- include the profession first, so this only blocks stale
                        -- resurrections, never a legitimate re-add.
                        local ckSnap   = gdb.skills and gdb.skills[ck]
                        local ckHasSnap = gdb.lastScan and gdb.lastScan[ck]
                                          and gdb.lastScan[ck].professions
                        local ckDropped = ckHasSnap and not (ckSnap and ckSnap[profId])
                        -- Federation gate: store only home / own / configured-
                        -- sister tags. Unlisted-guild data is dropped (and an
                        -- existing allowed tag, if any, is preserved untouched).
                        if not ckDropped and allowedTags[effTag]
                           and existing.crafters[ck] ~= effTag then
                            existing.crafters[ck] = effTag
                            changed = true
                        end
                    end
                end
            end
        end
    end
    return changed
end

--- v0.2.0 — Called by DeltaSync when a peer's broadcast or whisper arrives.
-- Two payload shapes are accepted:
--   1. Subhashes response: { type = "subhashes", parent = ..., subhashes = ... }
--      Receiver compares per-character hashes locally and follows up with
--      leaf-data requests for each differing leaf.
--   2. Leaf-data broadcast: { leaves = { itemKey = { data, hash, updatedAt } } }
--      Receiver runs content-aware merge per leaf type.
function Scanner:OnGuildDataReceived(sender, data, bytes)
    addon:DebugPrint("Scanner: OnGuildDataReceived ENTRY sender=", sender, "bytes=", bytes or 0)
    if not data or type(data) ~= "table" then
        addon:DebugPrint("Scanner: BAIL — malformed data from", sender)
        return
    end

    local senderKey = data.charKey
    if not senderKey or type(senderKey) ~= "string" then
        addon:DebugPrint("Scanner: BAIL — no charKey in payload from", sender)
        return
    end

    local DS         = self.DS
    local GuildRoster = self.GuildRoster
    if GuildRoster then
        senderKey = GuildRoster:NormalizeName(senderKey) or senderKey
    end

    -- Ignore echoes of our own broadcast.
    if senderKey == addon:GetCharacterKey() then
        addon:DebugPrint("Scanner: BAIL — own echo from", sender, "(senderKey=", senderKey, ")")
        return
    end

    if not addon:GetGuildKey() then
        addon:DebugPrint("Scanner: BAIL — no guild key (not in a guild?) sender=", sender)
        return
    end
    local gdb = addon:GetGuildDb()
    if not gdb then
        addon:DebugPrint("Scanner: BAIL — no gdb sender=", sender)
        return
    end

    -- Cross-guild ACCEPT gate: a payload whose guildKey is neither our home
    -- guild nor a CONFIGURED sister comes from a guild we don't federate with —
    -- drop it whole. (Relayed sister data rides inside a home-guild payload with
    -- guildKey == ours and is filtered per-crafter by the merge gate instead;
    -- legacy payloads carry no guildKey and are treated as home/intra-guild.)
    if data.guildKey and data.guildKey ~= addon:GetGuildKey()
       and not addon:IsSisterGuildKey(data.guildKey) then
        addon:DebugPrint("Scanner: BAIL — cross-guild data from unlisted guild",
            data.guildKey, "sender=", sender)
        return
    end

    local now = GetServerTime()

    -- Sender's guild tag, derived from the payload's guildKey. For intra-guild
    -- data this equals our own tag; for cross-guild "sister" data it's the
    -- sender's guild, so merged crafters are attributed to the right guild.
    -- nil for legacy payloads without a guildKey (merge falls back to ours).
    local senderTag = data.guildKey and addon:GuildTagFromKey(data.guildKey) or nil

    -- Record per-player drill-down capability. Any payload carrying the subsync
    -- presence beacon means this peer speaks the optional crafters:<profId> player
    -- protocol, so future profession mismatches with them fetch per player instead
    -- of the whole leaf. Runtime-only (rebuilt as payloads arrive after a /reload).
    if data.subsync and senderKey then
        Scanner._subsyncPeers = Scanner._subsyncPeers or {}
        Scanner._subsyncPeers[senderKey] = true
    end

    -- Compare two hash entries on the HIGHEST REVISION BOTH ENDS ADVERTISE.
    -- Revision 1 renders a number and its string form identically, so a real
    -- difference can be invisible; revision 2 types each scalar. Shipping both
    -- and choosing per-pair is what makes the rollout coordination-free: a peer
    -- on an older build sends no hashV2, we fall back to revision 1 and still
    -- agree, while two updated peers get the collision-free comparison. Mirrors
    -- DeltaSync's own HashesDiffer, which does this for the OFFER protocol.
    -- Retiring revision 1 later is: stop minting `hash`, then delete the fallback.
    local function hashesDiffer(mine, theirs)
        if mine.hashV2 ~= nil and theirs.hashV2 ~= nil then
            return mine.hashV2 ~= theirs.hashV2
        end
        return mine.hash ~= theirs.hash
    end

    -- ── Subhashes response ─────────────────────────────────────────────────
    -- Peer broadcast their per-character sub-hashes for a roll-up parent.
    -- Compare locally, request individual leaves we differ on.
    if data.type == "subhashes" and type(data.subhashes) == "table" then
        local localHashes = gdb.hashes or {}
        local toRequest = {}
        local stamps    = nil   -- per-cooldown-key DTS so the responder can gate (v0.10.11)
        for itemKey, peerEntry in pairs(data.subhashes) do
            if type(peerEntry) == "table" and peerEntry.hash then
                local mine    = localHashes[itemKey]
                local differs = not mine or hashesDiffer(mine, peerEntry)
                if differs and itemKey:sub(1, 9) == "cooldown:" then
                    -- "Empty" means empty by DATA, never by hash. A leftover orphan
                    -- hash (data purged, hash lingered) must NOT let us claim we hold a
                    -- version: doing so sends the owner an inflated stamp, its copy
                    -- isn't "strictly newer", it stays silent, and we never merge the
                    -- cooldown we actually lack. So decide emptiness from gdb.cooldowns:
                    --   • hold the data as an authoritative absolute copy → trust the
                    --     strict-newer suppression and stamp with our own updatedAt;
                    --   • hold no data (or only a legacy/untrustworthy copy) → ALWAYS
                    --     pull and stamp -1 ("I have nothing"), so any real copy from
                    --     the owner wins and serves. This is the "empty → merge it in"
                    --     rule: an empty request must advertise -1, not a stale hash's ts.
                    local cdOwner  = itemKey:sub(10)
                    local haveData = gdb.cooldowns and gdb.cooldowns[cdOwner]
                                     and next(gdb.cooldowns[cdOwner]) ~= nil
                    local peerTs   = tonumber(peerEntry.updatedAt) or 0
                    if haveData and mine and mine.abs and peerTs <= (mine.updatedAt or 0) then
                        differs = false
                    end
                    if differs then
                        stamps = stamps or {}
                        stamps[itemKey] = (haveData and mine and mine.abs and mine.updatedAt) or -1
                    end
                end
                if differs and itemKey:sub(1, 12) == "professions:" then
                    -- Owner-authoritative professions (v1.0.3): like cooldowns, a bare
                    -- hash difference against an equal-or-older copy is just a drifted
                    -- peer. Pull ONLY a strictly newer version (or when we hold
                    -- nothing), so peers don't churn re-fetching equal-age snapshots.
                    local peerTs = tonumber(peerEntry.updatedAt) or 0
                    if mine and peerTs <= (mine.updatedAt or 0) then
                        differs = false
                    end
                end
                if differs and itemKey:sub(1, 7) == "skills:" then
                    -- Defer to the owner's authoritative professions leaf when we hold
                    -- it: don't re-fetch their legacy gathering skills leaf (we ignore
                    -- it on receive anyway). Stops us churning against an un-updated
                    -- peer that still carries a gathering profession the owner dropped.
                    local sOwner = itemKey:sub(8)
                    if gdb.lastScan[sOwner] and gdb.lastScan[sOwner].professions then
                        differs = false
                    end
                end
                if differs then
                    toRequest[#toRequest + 1] = itemKey
                end
            end
        end
        if #toRequest > 0 and DS and DS.RequestData then
            -- Ask the subhashes SENDER for everything it advertised, with the fixed
            -- data-based stamps (a cooldown we hold NO data for stamps -1, so an old
            -- still-gated peer's `myTs > reqStamp` passes and it serves us). Online
            -- gate mirrors onSyncAccepted — the peer may have gone offline between
            -- their subhashes broadcast and this follow-up landing on the wire.
            if Scanner:PeerIsOffline(sender) then
                addon:DebugPrint("Scanner:   -> skip leaf-data RequestData -- peer offline:", sender)
            else
                DS:RequestData(sender, { type = "leaf-data", keys = toRequest, stamps = stamps })
            end
        end
        -- Complete the parent session.  Without this, P2P keeps the parent
        -- itemKey (e.g., "guild:cooldowns") in ACTIVE state until the
        -- session timeout fires (~180s), which clogs the maxActiveSessions
        -- slot and blocks dispatch of any new sessions — including the
        -- per-character leaves we just requested.  The subhashes response
        -- IS the completion of the parent's request; child leaf sessions
        -- are tracked separately and complete on their own data arrival.
        if DS and DS.p2p and data.parent then
            DS.p2p:OnItemCompleted(data.parent, sender)
        end
        if addon.callbacks then
            addon.callbacks:Fire("SYNC_RECV", sender, bytes or 0,
                "subhashes: " .. tostring(data.parent) .. " (" .. #toRequest .. " differ)")
        end
        addon:DebugPrint("Scanner: received", #toRequest, "differing subhashes for",
            data.parent, "from", sender)
        return
    end

    -- ── Player-subhashes response ──────────────────────────────────────────
    -- Peer sent the per-player hash list for one profession (the optional
    -- crafters:<profId> drill-down). Recompute our own per-player hashes, diff,
    -- and pull only the players we differ on — newest scan first so recent
    -- activity lands quickest. The pulled data comes back as a scoped (partial)
    -- crafters:<profId> leaf and merges through the existing leaf path.
    if data.type == "player-subhashes" and data.profId and type(data.players) == "table" then
        local profId = data.profId
        local mine   = addon.HashManager:GetProfessionPlayerSubhashes(DS, gdb, profId)
        local diffs  = {}
        for ck, peerEntry in pairs(data.players) do
            if type(ck) == "string" and type(peerEntry) == "table" and peerEntry.h then
                local localEntry = mine[ck]
                if not localEntry or localEntry.h ~= peerEntry.h then
                    diffs[#diffs + 1] = { ck = ck, ts = tonumber(peerEntry.ts) or 0 }
                end
            end
        end
        -- Newest scan first.
        table.sort(diffs, function(a, b) return a.ts > b.ts end)
        local players = {}
        for _, d in ipairs(diffs) do players[#players + 1] = d.ck end
        if #players > 0 and DS and DS.RequestData then
            if Scanner:PeerIsOffline(sender) then
                addon:DebugPrint("Scanner:   -> skip player-leaf RequestData -- peer offline:", sender)
            else
                DS:RequestData(sender, { type = "player-leaf", profId = profId, players = players })
            end
        end
        -- Complete the parent crafters:<profId> session (mirrors the subhashes
        -- branch completing its roll-up parent) so the P2P slot frees up.
        if DS and DS.p2p then
            DS.p2p:OnItemCompleted("crafters:" .. tostring(profId), sender)
        end
        if addon.callbacks then
            addon.callbacks:Fire("SYNC_RECV", sender, bytes or 0,
                "player-subhashes: " .. profId .. self:_ProfSuffix(profId) .. " (" .. #players .. " differ)")
        end
        addon:DebugPrint("Scanner: received player-subhashes for prof", profId, "—",
            #players, "differing players from", sender)
        return
    end

    -- ── Leaf-data merge ────────────────────────────────────────────────────
    if type(data.leaves) ~= "table" then
        addon:DebugPrint("Scanner: payload from", sender, "has neither subhashes nor leaves")
        return
    end

    -- Merge incoming lastScan timestamps first (max wins).  HashManager reads
    -- these when computing content-derived updatedAt for invalidated leaves.
    if type(data.lastScan) == "table" then
        for ck, scopes in pairs(data.lastScan) do
            if type(ck) == "string" and type(scopes) == "table" then
                if not gdb.lastScan[ck] then gdb.lastScan[ck] = {} end
                for scope, ts in pairs(scopes) do
                    if type(ts) == "number" then
                        local existing = gdb.lastScan[ck][scope] or 0
                        if ts > existing then gdb.lastScan[ck][scope] = ts end
                    end
                end
            end
        end
    end

    local touchedAltGroups = false
    local touchedProfessions = {}
    -- Set the moment any leaf merge writes NEW/different data to gdb. Only then do
    -- we fire GUILD_DATA_UPDATED (the UI redraw). A peer re-sending data we already
    -- have (redundant full payloads, matched hashes) merges to nothing and must
    -- NOT trigger a redraw. Bookkeeping-only writes (syncTimes, lastScan) do NOT
    -- set these — the UI doesn't read them.
    --
    -- Tracked per leaf-TYPE (scope) so GUILD_DATA_UPDATED can carry which kind of
    -- data changed: a cooldown-only sync must not tear down and rebuild the recipe
    -- Browser, which renders none of it. MainWindow gates the redraw on the active
    -- tab's interest set.
    local changedCooldowns = false
    local changedCrafters  = false
    local changedAlts      = false
    local changedSkills    = false
    -- Owners whose authoritative profession snapshot we just adopted — after the
    -- leaf loop we prune their crafter rows against the new set (drops recipes for
    -- professions they no longer have). Set by the skills: leaf branch.
    local reconcileOwners  = nil
    -- Our own charKey — we are the sole authority for our own cooldowns, so a peer
    -- (even a relay holding a stale/drifted copy) must never overwrite them.
    local ownKey = addon:GetCharacterKey()

    for itemKey, leafEntry in pairs(data.leaves) do
        if type(leafEntry) == "table" then
            local leafData = leafEntry.data

            if itemKey:sub(1, 9) == "cooldown:" then
                local owner = itemKey:sub(10)
                -- v0.10.11: cooldowns are owner-authoritative, immutable-token
                -- leaves. The owner ships ABSOLUTE expiry timestamps (leafEntry.abs
                -- marks the new format) plus its own minted leaf hash (leafEntry.
                -- hash). Receivers ADOPT the owner's bucket and hash VERBATIM — never
                -- reconstruct a value against the local clock, never recompute the
                -- hash. That's what stops the latency-drift feedback loop that kept
                -- guild:cooldowns hashes from ever converging (endless re-sync +
                -- redraw churn). See StoreDeliveredCooldownLeaf in HashManager.
                if leafEntry.abs and type(leafData) == "table" then
                    -- Never let a peer overwrite our OWN cooldowns — we mint those
                    -- locally in ScanCooldowns; a relay can only hold a stale copy.
                    if owner ~= ownKey then
                        local token       = leafEntry.hash
                        local deliveredTs = tonumber(leafEntry.updatedAt) or 0
                        local storedHash  = gdb.hashes and gdb.hashes["cooldown:" .. owner]
                        -- Adopt-or-ignore by (token, updatedAt). Same token → same
                        -- version, no-op. Different token → take it ONLY if it's
                        -- STRICTLY newer than what we hold. Strict (not >=) matters
                        -- during the mixed-version rollout: two upgraded clients can
                        -- hold different DRIFTED legacy tokens for the same owner with
                        -- an identical owner-lastScan; `>=` would let them ping-pong
                        -- adopt each other's copy forever (churning the Cooldowns tab),
                        -- while `>` freezes both until the owner's next scan mints a
                        -- genuinely newer timestamp that cleanly wins for everyone.
                        -- Atomic per-leaf: the owner's whole bucket is versioned by the
                        -- one token, so we replace the bucket wholesale.
                        local adopt = false
                        if not storedHash then
                            adopt = true
                        elseif not storedHash.abs then
                            adopt = true   -- upgrade a legacy copy to the authoritative absolute one
                        elseif storedHash.hash ~= token
                               and deliveredTs > (storedHash.updatedAt or 0) then
                            adopt = true
                        end
                        if adopt then
                            local newBucket = {}
                            for spellId, expiresAt in pairs(leafData) do
                                -- Store the absolute expiry VERBATIM. Sanity-clamp to
                                -- a plausible window (past = Ready is fine; reject a
                                -- value more than 30 days out as corruption).
                                if type(expiresAt) == "number"
                                   and expiresAt > 0 and expiresAt < now + 2592000 then
                                    newBucket[spellId] = expiresAt
                                end
                            end
                            -- Only replace if the incoming leaf actually carried data.
                            -- An empty/all-rejected bucket must never wipe a good copy
                            -- we already hold (a healthy owner never ships an empty
                            -- cooldown leaf — BuildLeafPayload returns nil for that).
                            if next(newBucket) then
                                gdb.cooldowns[owner] = newBucket
                                -- Store the owner's token + updatedAt WITHOUT recomputing.
                                -- Mark it ABSOLUTE so a legacy copy can't override it.
                                if DS then
                                    addon.HashManager:StoreDeliveredCooldownLeaf(
                                        DS, gdb, owner, token, deliveredTs, true,
                                        leafEntry.hashV2)
                                end
                                changedCooldowns = true
                            end
                        end
                    end
                elseif owner ~= ownKey then
                    -- CLEAN BREAK (post-v1.0.0): the new framework is ABSOLUTE-format
                    -- only. A non-abs (legacy relative-remaining) cooldown leaf can't be
                    -- trusted without clock reconstruction that reignites the very drift
                    -- the absolute format exists to kill, so we IGNORE it outright — no
                    -- adopt, no reconstruct. The guild is all v1.0.x+; this path only
                    -- fires for a stray pre-v0.10.11 payload, which we simply drop.
                    addon:DebugPrint("Scanner: ignored non-abs cooldown leaf", itemKey, "from", sender)
                end
                if DS and DS.p2p then DS.p2p:OnItemCompleted(itemKey, sender) end

            elseif itemKey:sub(1, 13) == "accountchars:" then
                local owner = itemKey:sub(14)
                -- Never let a peer overwrite our OWN alt group — we mint that locally.
                if owner ~= ownKey and type(leafData) == "table" then
                    -- Owner-authoritative (like cooldowns / professions): the alt group
                    -- is minted only by its own account and adopted VERBATIM by everyone
                    -- else — token + updatedAt stored as delivered, NEVER recomputed and
                    -- NEVER union-merged. The old v0.7.0 path union-added incoming entries
                    -- then recomputed the hash from its own accumulated view, so every
                    -- client held a slightly different set, the leaf perpetually differed,
                    -- and peers re-requested it every cycle (the accountchars churn). Now
                    -- a relay just carries the owner's exact bytes, so everyone converges
                    -- on one hash — and because it's a verbatim REPLACE, a dropped alt
                    -- finally propagates (the grow-only union could never remove one).
                    -- Gate on strict-newer so two equal-age copies can't ping-pong.
                    local token       = leafEntry.hash or 0
                    local deliveredTs = tonumber(leafEntry.updatedAt) or 0
                    local storedHash  = gdb.hashes and gdb.hashes["accountchars:" .. owner]
                    local adopt = false
                    if not storedHash then
                        adopt = true
                    elseif storedHash.hash ~= token
                           and deliveredTs > (storedHash.updatedAt or 0) then
                        adopt = true
                    end
                    if adopt then
                        if not gdb.altClaims then gdb.altClaims = {} end
                        local arr = {}
                        for _, ck in ipairs(leafData) do
                            if type(ck) == "string" then arr[#arr + 1] = ck end
                        end
                        table.sort(arr)
                        -- Redraw only when the group actually changed.
                        local prev = gdb.altClaims[owner]
                        local same = prev and #prev == #arr
                        if same then
                            for i = 1, #arr do
                                if prev[i] ~= arr[i] then same = false; break end
                            end
                        end
                        gdb.altClaims[owner] = arr
                        -- Store the owner's token + updatedAt WITHOUT recomputing.
                        if DS then
                            addon.HashManager:StoreDeliveredAccountCharsLeaf(
                                DS, gdb, owner, token, deliveredTs, leafEntry.hashV2)
                        end
                        if not same then changedAlts = true end
                        touchedAltGroups = true
                    end
                end
                if DS and DS.p2p then DS.p2p:OnItemCompleted(itemKey, sender) end

            elseif itemKey:sub(1, 12) == "professions:" then
                -- v1.0.3: the professions leaf is the OWNER-AUTHORITATIVE profession
                -- registry. The owner mints its hash from its full profession set;
                -- everyone else ADOPTS the delivered snapshot + hash VERBATIM and
                -- NEVER recomputes (same rule as cooldowns — recompute-on-receive is
                -- what caused the drift/churn disasters). Adopting REPLACES the owner's
                -- profession set wholesale, which is how a DROPPED profession gets
                -- deleted everywhere; the crafter-reconcile after the loop then prunes
                -- their stale recipe rows. Separate leaf from skills: so un-updated
                -- clients (which don't know this key) are wholly undisturbed.
                local owner = itemKey:sub(13)
                -- Never let a peer overwrite our OWN snapshot — we mint it locally in
                -- ScanGatheringProfessions; a relay can only hold a stale copy.
                if owner ~= ownKey and type(leafData) == "table" then
                    local deliveredTs = tonumber(leafEntry.updatedAt) or 0
                    local storedHash  = gdb.hashes and gdb.hashes["professions:" .. owner]
                    -- Adopt-or-ignore by (token, updatedAt): unknown → take it;
                    -- different token → take ONLY if STRICTLY newer than what we hold
                    -- (strict, like cooldowns, so two drifted copies with equal
                    -- owner-timestamps can't ping-pong forever during a rollout).
                    -- CRITICAL: a professions leaf is AUTHORITATIVE only when the owner
                    -- minted it from their own scan (updatedAt > 0). A leaf with
                    -- updatedAt == 0 is a relayer's RebuildOnFirstLoad guess (fabricated
                    -- from relayed skills data) — adopting it would set a bogus, TRUTHY
                    -- lastScan.professions (0 is truthy in Lua!), which makes us ignore
                    -- the owner's real skills leaf (orphan hashes we can't serve) and
                    -- mis-filter their cooldowns. Non-positive timestamp NEVER adopts.
                    local adopt = false
                    if deliveredTs <= 0 then
                        adopt = false
                    elseif not storedHash then
                        adopt = true
                    elseif storedHash.hash ~= leafEntry.hash
                           and deliveredTs > (storedHash.updatedAt or 0) then
                        adopt = true
                    end
                    if adopt then
                        -- Replace the profession set wholesale — deletes any
                        -- profession the owner dropped.
                        local newset = {}
                        for profIdStr, rec in pairs(leafData) do
                            local profId = tonumber(profIdStr)
                            if profId and type(rec) == "table" then
                                newset[profId] = {
                                    skillRank = tonumber(rec.r) or 0,
                                    skillMax  = tonumber(rec.m) or 0,
                                }
                            end
                        end
                        gdb.skills[owner] = newset
                        if not gdb.lastScan[owner] then gdb.lastScan[owner] = {} end
                        -- `.professions` marks that we hold a COMPLETE authoritative
                        -- snapshot for this owner — the reconcile + resurrection guards
                        -- key off its presence/recency.
                        gdb.lastScan[owner].professions = deliveredTs
                        changedSkills = true
                        reconcileOwners = reconcileOwners or {}
                        reconcileOwners[owner] = true
                        -- Store the owner's hash VERBATIM — never recompute on receive.
                        if DS then
                            addon.HashManager:StoreDeliveredProfessionsLeaf(
                                DS, gdb, owner, leafEntry.hash, deliveredTs, leafEntry.hashV2)
                        end
                    end
                end
                if DS and DS.p2p then DS.p2p:OnItemCompleted(itemKey, sender) end

            elseif itemKey:sub(1, 7) == "skills:" then
                -- v1.0.0 gathering-profession skills (Herbalism / Skinning / Fishing /
                -- Archaeology), max-rank-wins. The leaf format is byte-identical to old
                -- clients (zero rollout churn), BUT: once we hold this owner's
                -- authoritative professions snapshot, that new-framework leaf is the
                -- SINGLE SOURCE OF TRUTH for them — we IGNORE their legacy skills: leaf
                -- entirely, so a stale relay can't resurrect a gathering profession
                -- they dropped. (professions: already carries their gathering skills.)
                -- We still merge skills: for owners we have NO snapshot for — i.e.
                -- un-updated clients, which is exactly the legacy behavior.
                local owner = itemKey:sub(8)
                local haveSnapshot = gdb.lastScan[owner]
                                     and gdb.lastScan[owner].professions
                if not haveSnapshot and type(leafData) == "table" then
                    if not gdb.skills[owner] then gdb.skills[owner] = {} end
                    for profIdStr, rec in pairs(leafData) do
                        local profId = tonumber(profIdStr)
                        if profId and type(rec) == "table" then
                            local incomingRank = tonumber(rec.r) or 0
                            local incomingMax  = tonumber(rec.m) or 0
                            local existing = gdb.skills[owner][profId]
                            if not existing or incomingRank > (existing.skillRank or 0) then
                                gdb.skills[owner][profId] = {
                                    skillRank = incomingRank,
                                    skillMax  = incomingMax,
                                }
                                changedSkills = true
                            end
                        end
                    end
                    if DS then addon.HashManager:InvalidateCharSkills(DS, gdb, owner) end
                end
                if DS and DS.p2p then DS.p2p:OnItemCompleted(itemKey, sender) end

            -- v0.7.0: recipemeta: leaf removed (metadata lives in shipped
            -- addon.recipeDB, not synced). Receivers ignore inbound recipemeta:
            -- payloads from any straggler peer that wasn't aware of the change;
            -- the namespace bump TOGPmv2 → TOGPmv3 means v0.6.x clients can't
            -- reach our OnGuildDataReceived in the first place.

            elseif itemKey:sub(1, 9) == "crafters:" then
                local profId = tonumber(itemKey:sub(10))
                if profId then
                    -- Sender is claiming an authoritative own-scan if they
                    -- include a skills entry for themselves at this profId.
                    local senderClaimsOwnScan =
                        type(data.skills) == "table"
                        and type(data.skills[profId]) == "table"
                        and data.skills[profId][senderKey] ~= nil
                    if self:MergeCraftersIntoGdb(gdb, profId, leafData,
                        senderKey, senderClaimsOwnScan, senderTag) then
                        changedCrafters = true
                    end
                    -- Skills (per-charKey rank/max) ride along on crafters payloads
                    -- (this is also what flags the sender's authoritative own-scan
                    -- above, so it must keep being sent). It may bump the RANK of a
                    -- profession we already hold, but it must NOT create a profession
                    -- row for a character whose authoritative snapshot (skills leaf)
                    -- already established their set — otherwise a stale relay of an
                    -- old crafters leaf would resurrect a profession they dropped.
                    if type(data.skills) == "table"
                       and type(data.skills[profId]) == "table" then
                        for ck, sk in pairs(data.skills[profId]) do
                            if type(sk) == "table" and type(ck) == "string" then
                                if not gdb.skills[ck] then gdb.skills[ck] = {} end
                                local existing = gdb.skills[ck][profId]
                                local incomingRank = sk.skillRank or 0
                                if existing then
                                    if incomingRank > (existing.skillRank or 0) then
                                        gdb.skills[ck][profId] = {
                                            skillRank = incomingRank,
                                            skillMax  = sk.skillMax or incomingRank,
                                        }
                                        changedCrafters = true
                                    end
                                elseif not (gdb.lastScan[ck] and gdb.lastScan[ck].professions) then
                                    -- No authoritative snapshot for this char yet (an
                                    -- un-updated-client owner): keep legacy behavior
                                    -- and create the row from the ride-along.
                                    gdb.skills[ck][profId] = {
                                        skillRank = incomingRank,
                                        skillMax  = sk.skillMax or incomingRank,
                                    }
                                    changedCrafters = true
                                end
                                -- else: we hold a complete authoritative snapshot that
                                -- omitted this profession → it was dropped; ignore the
                                -- stale ride-along. The owner's own next snapshot
                                -- re-adds it if they truly re-learned it.
                            end
                        end
                    end
                    -- Specializations (per-charKey spec spell ID) also ride along.
                    -- Last-write-wins is fine — a character's spec changes ~once
                    -- ever (or never), so divergence between peers is transient.
                    if type(data.specializations) == "table"
                       and type(data.specializations[profId]) == "table" then
                        if not gdb.specializations then gdb.specializations = {} end
                        for ck, sid in pairs(data.specializations[profId]) do
                            if type(ck) == "string" and type(sid) == "number" then
                                if not gdb.specializations[ck] then gdb.specializations[ck] = {} end
                                if gdb.specializations[ck][profId] ~= sid then
                                    gdb.specializations[ck][profId] = sid
                                    changedCrafters = true
                                end
                            end
                        end
                    end
                    touchedProfessions[profId] = true
                end
                if DS and DS.p2p then DS.p2p:OnItemCompleted(itemKey, sender) end
            end
        end
    end

    -- Rebuild altGroups derived view if any accountchars leaf was merged.
    if touchedAltGroups then self:RebuildAltGroups(gdb) end

    -- Prune crafter rows for any owner whose authoritative profession snapshot we
    -- just adopted — this is what makes a DROPPED profession's recipes disappear
    -- (the crafters leaf can't express the deletion; the skills registry does).
    if reconcileOwners then
        for owner in pairs(reconcileOwners) do
            if self:ReconcileCraftersAgainstSkills(gdb, owner) then
                changedCrafters = true
            end
        end
    end

    -- Recompute hashes for any professions touched (covers both recipemeta
    -- and crafters leaves; InvalidateProfession handles both leaves at once).
    if DS then
        for profId in pairs(touchedProfessions) do
            addon.HashManager:InvalidateProfession(DS, gdb, profId)
        end
    end

    -- Record sync time so /togpm status reflects "we heard from this peer".
    if type(data.timestamp) == "number" then
        gdb.syncTimes[senderKey] = data.timestamp
    end

    addon:DebugPrint("Scanner: merged leaves from", sender, "(", bytes or 0, "bytes)")

    if addon.callbacks then
        local leafKeys = {}
        for k in pairs(data.leaves) do
            leafKeys[#leafKeys + 1] = k .. self:_ProfSuffix(tonumber(k:match("^crafters:(%d+)")))
        end
        table.sort(leafKeys)
        local changed = changedCooldowns or changedCrafters or changedAlts or changedSkills
        -- SYNC_RECV always fires (the Sync Log records every receive). But
        -- GUILD_DATA_UPDATED — which drives the UI redraw — fires ONLY when the
        -- merge actually wrote new data, so a redundant re-send from a peer no
        -- longer tears down and rebuilds the active tab for nothing.
        addon.callbacks:Fire("SYNC_RECV", sender, bytes or 0,
            (changed and "" or "[no-op] ") ..
            "leaves: " .. table.concat(leafKeys, ", "))
        if changed then
            -- Carry WHICH kind of data changed so the UI can skip redraws it
            -- doesn't need — a cooldown-only sync must not rebuild the recipe
            -- Browser. MainWindow gates the redraw on the active tab's interests.
            local scopes = {}
            if changedCooldowns then scopes.cooldowns = true end
            if changedCrafters  then scopes.recipes   = true end
            if changedAlts      then scopes.altgroups = true end
            if changedSkills    then scopes.skills    = true end
            addon.callbacks:Fire("GUILD_DATA_UPDATED", senderKey, scopes)
        end
    end
end