fodda-mcp 1.38.0 → 1.46.97

package/dist/coverageRelevance.js

@@ -0,0 +1,1857 @@
+/**
+ * Coverage relevance heuristic — counts how many result rows are actually
+ * on-topic for the query, so the coverage annotation can flag "thin" when a
+ * cross-graph fan-out pads the result set with off-topic rows.
+ *
+ * Why raw count isn't enough: an all-graph search fans out to every accessible
+ * graph and each graph returns its own best matches. For a narrow query
+ * ("Chinese automotive trends EV brands"), unrelated graphs (women's health,
+ * beauty, social media) still contribute their locally-top rows, so the merged
+ * set can hit 10 rows while only 2–3 are on-topic — and the old count-only
+ * check reported coverage "ok" and never nudged the client toward
+ * get_supplemental_context.
+ *
+ * How a row is judged on-topic (positive-evidence-of-off-topic model — rows
+ * are only marked off-topic when we can actually tell):
+ *   1. Lexical: the row's text (title/summary/brands/places + its source
+ *      graph's name/domain/topics) contains at least one SPECIFIC query token
+ *      (generic research vocabulary like "trends", "market", "brands" is
+ *      stopworded out). Match → on-topic.
+ *   2. Score rescue: no lexical match, but the row's relevance score clears
+ *      ON_TOPIC_RESCUE_RATIO of its tier's scale. Scores are NOT comparable
+ *      across tiers (domain-graph composite scores cluster near ~2.0 for
+ *      on-topic matches; report-graph vector scores near ~0.8), so each tier
+ *      normalizes against max(nominal tier scale, best observed score in that
+ *      tier within this result set). Using the nominal as a floor prevents a
+ *      tier whose rows are ALL off-topic from normalizing itself to look good.
+ *   3. No score at all → counted on-topic (score-less rows from statistics /
+ *      insights endpoints must never regress coverage).
+ *
+ * If the query has no specific tokens left after stopwording (e.g. "top
+ * emerging trends"), relevance can't be judged and `evaluated: false` is
+ * returned — callers keep the legacy count-only behavior.
+ */
+import { getGraphs, getLiveGraphs, buildDisplayName, cleanDisplayName, getRelevantGraphs, getAnalysts } from './catalogCache.js';
+import { LUXURY_KEYWORDS, LUXURY_BRANDS, MASS_BUDGET_KEYWORDS, MASS_BUDGET_BRANDS } from './enrichment.js';
+/** Nominal on-topic relevance-score scale per graph tier (observed in QA:
+ *  domain composites ~2.0, report vector scores ~0.8; expert sits between). */
+export const TIER_NOMINAL_SCORE = {
+    domain: 2.0,
+    expert: 1.0,
+    report: 0.8,
+};
+/** Fallback tier when a row's graph can't be resolved — the most permissive
+ *  scale, so unresolved rows are rarely marked off-topic. */
+const FALLBACK_TIER = 'report';
+/** A row with no lexical overlap must score at least this fraction of its
+ *  tier scale to still count as on-topic. */
+export const ON_TOPIC_RESCUE_RATIO = 0.75;
+/** English function words + research vocabulary present in almost every graph
+ *  row — these carry no topical signal and are excluded from query tokens. */
+const GENERIC_QUERY_TOKENS = new Set([
+    // function words
+    'a', 'an', 'the', 'and', 'or', 'of', 'in', 'on', 'for', 'to', 'with', 'from', 'by', 'at',
+    'as', 'is', 'are', 'was', 'be', 'been', 'how', 'what', 'which', 'who', 'why', 'when',
+    'where', 'will', 'can', 'do', 'does', 'about', 'into', 'over', 'under', 'between', 'vs',
+    'versus', 'their', 'its', 'this', 'that', 'these', 'those', 'it', 'not', 'no', 'more',
+    'most', 'less', 'least', 'than', 'also', 'other', 'across', 'around', 'within', 'per',
+    'via', 'both', 'all', 'any', 'some', 'each', 'such', 'we', 'us', 'our', 'you', 'your',
+    // domain-generic research vocabulary
+    'trend', 'trends', 'market', 'markets', 'marketing', 'brand', 'brands', 'branding',
+    'consumer', 'consumers', 'industry', 'industries', 'growth', 'data', 'insight',
+    'insights', 'analysis', 'global', 'new', 'top', 'key', 'major', 'latest', 'future',
+    'emerging', 'current', 'recent', 'report', 'reports', 'research', 'sector', 'sectors',
+    'landscape', 'opportunity', 'opportunities', 'innovation', 'innovations', 'strategy',
+    'strategies', 'signal', 'signals', 'impact', 'update', 'updates', 'overview',
+]);
+const TIER_ALIASES = {
+    'industry report': 'report',
+    'analyst': 'expert',
+};
+/** Tokenize a query down to its topically-specific terms. */
+export function specificQueryTokens(query) {
+    return [...new Set(query.toLowerCase().split(/[^a-z0-9]+/)
+            .filter(t => t.length >= 2 && !GENERIC_QUERY_TOKENS.has(t)))];
+}
+export function rowScore(row) {
+    return row.relevance_score || row.semantic_score || row._score || row.score || 0;
+}
+export function rowGraphId(row) {
+    return row._use_this_graphId || row.graphId || row.graph_id || row.psfk_graph_slug || undefined;
+}
+export function resolveRowTier(row, searchedGraphs, catalog) {
+    const gid = rowGraphId(row);
+    let type;
+    if (gid) {
+        const g = catalog.find(x => x.graph_id === gid) || searchedGraphs.find(x => x?.graph_id === gid);
+        type = g?.graph_type;
+    }
+    if (!type && searchedGraphs.length === 1)
+        type = searchedGraphs[0]?.graph_type;
+    type = TIER_ALIASES[type || ''] || type;
+    return type && TIER_NOMINAL_SCORE[type] !== undefined ? type : FALLBACK_TIER;
+}
+/** Does the row's text (or its source graph's metadata) contain any specific query token? */
+export function rowMatchesQueryTokens(row, tokens, catalog) {
+    if (tokens.length === 0)
+        return false;
+    const parts = [
+        row.title, row.trendName, row.name, row.display, row.label,
+        row.summary, row.description, row.trendDescription, row.whyNow,
+        row.graphName, row.statistic, row.claim, row.insight, row.text,
+    ];
+    const gid = rowGraphId(row);
+    if (gid) {
+        parts.push(String(gid).replace(/[-_/,]/g, ' '));
+        const g = catalog.find(x => x.graph_id === gid);
+        if (g)
+            parts.push(g.name, g.domain, ...(Array.isArray(g.topics) ? g.topics : []));
+    }
+    for (const arr of [row.brandNames, row.place, row.sectors, row.topics]) {
+        if (Array.isArray(arr))
+            parts.push(...arr);
+    }
+    const words = new Set(parts.filter((x) => typeof x === 'string').join(' ').toLowerCase().split(/[^a-z0-9]+/));
+    // Exact word match always counts; prefix match only for tokens ≥4 chars
+    // (so "china" matches "chinas" but "car" never matches "carbon").
+    for (const t of tokens) {
+        if (words.has(t))
+            return true;
+        if (t.length >= 4) {
+            for (const w of words) {
+                if (w.startsWith(t))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+export function stemToken(token) {
+    let s = token.toLowerCase().trim();
+    if (s.endsWith('ies') && s.length > 4) {
+        s = s.slice(0, -3) + 'y';
+    }
+    else if (s.endsWith('es') && s.length > 4) {
+        s = s.slice(0, -2);
+    }
+    else if (s.endsWith('s') && !s.endsWith('ss') && s.length > 3) {
+        s = s.slice(0, -1);
+    }
+    return s;
+}
+/**
+ * Direct token match tier: checks if specific query tokens match directly
+ * against the row's core trend name, sectors, or trend slug/categories.
+ * Applies singular/plural folding and stem matching (e.g. "collectible" matches "Collectibles", "trading cards" matches "cards").
+ * (Used to rank direct niche matches above semantically adjacent mega-trends).
+ */
+export function rowHasDirectTokenMatch(row, tokens) {
+    if (!tokens || tokens.length === 0 || !row)
+        return false;
+    const parts = [
+        row.trendName, row.name, row.label, row.title,
+        row.trendSlug, row.slug,
+        row.sectorNames, row.sectors, row.sector,
+        row.categoryNames, row.categories, row.category,
+    ];
+    for (const arr of [row.sectors, row.sectorNames, row.categories, row.categoryNames, row.topics]) {
+        if (Array.isArray(arr))
+            parts.push(...arr);
+    }
+    const words = new Set(parts.filter((x) => typeof x === 'string').join(' ').toLowerCase().split(/[^a-z0-9]+/));
+    const stemmedWords = new Set();
+    for (const w of words) {
+        stemmedWords.add(stemToken(w));
+    }
+    for (const t of tokens) {
+        if (words.has(t))
+            return true;
+        const stemT = stemToken(t);
+        if (stemmedWords.has(stemT))
+            return true;
+        if (t.length >= 4) {
+            for (const w of words) {
+                if (w.startsWith(t) || (w.length >= 4 && t.startsWith(w)))
+                    return true;
+                const stemW = stemToken(w);
+                if (stemW.length >= 4 && stemT.length >= 4) {
+                    if (stemW.startsWith(stemT) || stemT.startsWith(stemW))
+                        return true;
+                }
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Row-level brand guard: returns true if the row is NOT a mega-trend brand roster.
+ * Excludes rows with brand_count > 30 (or brandNames.length >= 10 when brand_count is absent).
+ */
+export function isRowBrandEligible(row) {
+    if (!row)
+        return false;
+    const brandCount = typeof row.brand_count === 'number'
+        ? row.brand_count
+        : (typeof row.brandCount === 'number' ? row.brandCount : undefined);
+    if (brandCount !== undefined) {
+        if (brandCount > 30)
+            return false;
+    }
+    else {
+        const rawNames = Array.isArray(row.brandNames)
+            ? row.brandNames
+            : (Array.isArray(row.brands) ? row.brands : undefined);
+        if (rawNames && rawNames.length >= 10) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Evaluates whether a result row matches category/market tier qualifiers in the query
+ * (e.g. "luxury" vs "budget"). Returns a positive score boost for matching tiers,
+ * or a penalty for conflicting tiers.
+ */
+export function computeTierFit(row, query) {
+    if (!query || !row)
+        return 0;
+    const qLower = query.toLowerCase();
+    const isLuxuryQuery = [...LUXURY_KEYWORDS].some(k => qLower.includes(k));
+    const isBudgetQuery = [...MASS_BUDGET_KEYWORDS].some(k => qLower.includes(k));
+    const title = (row.trendName || row.title || row.label || row.name || '').toLowerCase();
+    const summary = (row.summary || row.description || row.trendDescription || '').toLowerCase();
+    let boost = 0;
+    // 1. Format alignment with query (e.g. pop-up / activation / experiential)
+    if (/\bpop-?ups?\b/i.test(qLower)) {
+        if (/\bpop-?ups?\b/i.test(title))
+            boost += 0.40;
+        else if (/\bpop-?ups?\b/i.test(summary))
+            boost += 0.15;
+    }
+    if (/\b(experiential|experiences?)\b/i.test(qLower)) {
+        if (/\b(experiential|experiences?)\b/i.test(title))
+            boost += 0.20;
+    }
+    if (/\bactivations?\b/i.test(qLower)) {
+        if (/\bactivations?\b/i.test(title))
+            boost += 0.15;
+    }
+    // 2. Luxury / Market Tier matching
+    if (isLuxuryQuery) {
+        // Title-level luxury match gets highest priority
+        const titleHasLuxWord = [...LUXURY_KEYWORDS].some(k => title.includes(k));
+        const titleHasLuxBrand = [...LUXURY_BRANDS].some(b => title.includes(b));
+        if (titleHasLuxWord || titleHasLuxBrand)
+            boost += 0.40;
+        // Summary-level luxury match
+        const summaryHasLux = [...LUXURY_KEYWORDS].some(k => summary.includes(k)) ||
+            [...LUXURY_BRANDS].some(b => summary.includes(b));
+        if (summaryHasLux)
+            boost += 0.25;
+        // Evidence-level luxury match
+        if (Array.isArray(row.evidence) && row.evidence.length > 0) {
+            const hasLuxEvidence = row.evidence.some((e) => {
+                const txt = `${e.title || ''} ${e.summary || ''}`.toLowerCase();
+                return [...LUXURY_BRANDS].some(b => txt.includes(b)) || [...LUXURY_KEYWORDS].some(k => txt.includes(k));
+            });
+            if (hasLuxEvidence)
+                boost += 0.35;
+            boost += 0.20; // Having verified on-topic evidence is a positive signal
+        }
+        else {
+            boost -= 0.20; // Having 0 valid evidence items penalizes the trend
+        }
+        // Mass-market penalty
+        const titleHasMass = [...MASS_BUDGET_BRANDS].some(b => title.includes(b));
+        const summaryHasMass = [...MASS_BUDGET_BRANDS].some(b => summary.includes(b));
+        if (titleHasMass || summaryHasMass)
+            boost -= 0.40;
+    }
+    else if (isBudgetQuery) {
+        const titleHasMass = [...MASS_BUDGET_BRANDS].some(b => title.includes(b)) ||
+            [...MASS_BUDGET_KEYWORDS].some(k => title.includes(k));
+        if (titleHasMass)
+            boost += 0.40;
+    }
+    return boost;
+}
+/** Normalize brand string for deduplication / comparison. */
+export function normalizeBrandKey(name) {
+    return name.toLowerCase().replace(/[^\w\s]/g, '').trim().replace(/\s+/g, ' ');
+}
+/** Build standard publisher / curator exclusion set. */
+export function buildPublisherExclusionSet(searchedGraphs = [], catalog = [], rows = []) {
+    const publisherTokens = new Set([
+        'dentsu', 'dentsu creative', 'havas', 'psfk', 'nielseniq', 'niq',
+        'wpp', 'omnicom', 'ipg', 'publicis', 'accenture', 'deloitte',
+        'mckinsey', 'bcg', 'bain', 'gartner', 'forrester', 'kantar', 'jwt',
+        'ogilvy', 'edelman', 'mccann', 'bbdo', 'tbwa', 'vml', 'leo burnett'
+    ]);
+    for (const sg of searchedGraphs) {
+        const gMeta = typeof sg === 'string' ? catalog.find(x => x.graph_id === sg) : sg;
+        if (gMeta) {
+            if (gMeta.curator)
+                publisherTokens.add(gMeta.curator.toLowerCase().trim());
+            if (gMeta.company)
+                publisherTokens.add(gMeta.company.toLowerCase().trim());
+            if (gMeta.name)
+                publisherTokens.add(gMeta.name.toLowerCase().trim());
+            for (const word of `${gMeta.curator || ''} ${gMeta.company || ''} ${gMeta.name || ''}`.toLowerCase().split(/[\s,.-]+/)) {
+                if (word.length > 2)
+                    publisherTokens.add(word);
+            }
+        }
+    }
+    for (const r of rows) {
+        if (r && r.source_label) {
+            const match = String(r.source_label).match(/\(([^)]+)\)/);
+            if (match && match[1]) {
+                const org = match[1].toLowerCase().trim();
+                publisherTokens.add(org);
+                for (const w of org.split(/[\s,.-]+/)) {
+                    if (w.length > 2)
+                        publisherTokens.add(w);
+                }
+            }
+        }
+    }
+    return publisherTokens;
+}
+/** Test whether a brand name matches publisher / curator tokens. */
+export function isPublisherBrand(brand, publisherTokens) {
+    const clean = brand.trim();
+    const norm = normalizeBrandKey(clean);
+    if (!norm)
+        return true;
+    if (publisherTokens.has(norm) || publisherTokens.has(clean.toLowerCase())) {
+        return true;
+    }
+    return [...publisherTokens].some(pt => norm === pt || norm.startsWith(`${pt} `) || norm.endsWith(` ${pt}`));
+}
+/** Extract clean, guarded brand names for a single row up to limit. */
+export function extractCleanRowBrands(row, publisherTokens, limit = 4) {
+    if (!isRowBrandEligible(row))
+        return [];
+    const rawList = [];
+    if (Array.isArray(row.brandNames))
+        rawList.push(...row.brandNames);
+    else if (typeof row.brandNames === 'string')
+        rawList.push(...row.brandNames.split('|'));
+    if (Array.isArray(row.brands))
+        rawList.push(...row.brands);
+    if (typeof row.brand === 'string' && row.brand)
+        rawList.push(row.brand);
+    if (typeof row.Brand === 'string' && row.Brand)
+        rawList.push(...row.Brand.split('|'));
+    else if (Array.isArray(row.Brand))
+        rawList.push(...row.Brand);
+    if (typeof row.company === 'string' && row.company)
+        rawList.push(row.company);
+    if (Array.isArray(row.entities?.brands))
+        rawList.push(...row.entities.brands);
+    const seen = new Set();
+    const result = [];
+    for (const b of rawList) {
+        if (typeof b === 'string' && b.trim().length > 1) {
+            const clean = b.trim();
+            const norm = normalizeBrandKey(clean);
+            if (!norm || seen.has(norm))
+                continue;
+            if (publisherTokens && isPublisherBrand(clean, publisherTokens))
+                continue;
+            seen.add(norm);
+            result.push(clean);
+            if (result.length >= limit)
+                break;
+        }
+    }
+    return result;
+}
+/**
+ * Count rows that are on-topic for the query. `catalog` is injectable for
+ * tests; defaults to the live graph catalog.
+ */
+export function countOnTopicRows(rows, query, searchedGraphs, catalog = getGraphs()) {
+    const tokens = specificQueryTokens(query);
+    if (tokens.length === 0 || rows.length === 0) {
+        return { onTopic: rows.length, evaluated: false };
+    }
+    const scored = rows.map(r => {
+        const score = rowScore(r);
+        const tier = resolveRowTier(r, searchedGraphs, catalog);
+        return { r, score, tier };
+    });
+    let onTopic = 0;
+    for (const { r, score, tier } of scored) {
+        if (rowMatchesQueryTokens(r, tokens, catalog)) {
+            onTopic++;
+            continue;
+        }
+        // No token match and no score: nothing supports the row being on-topic.
+        if (score <= 0)
+            continue;
+        // Rescue by score alone must be judged against the tier's NOMINAL scale,
+        // never the result set's own max — otherwise the top rows of any set
+        // (including a fully off-topic one) self-certify as on-topic.
+        const scale = TIER_NOMINAL_SCORE[tier] ?? 0.8;
+        if (score >= scale * ON_TOPIC_RESCUE_RATIO)
+            onTopic++;
+    }
+    return { onTopic, evaluated: true };
+}
+export function isDemandShaped(query) {
+    const q = query.toLowerCase();
+    const demandKeywords = [
+        /\binterest\b/,
+        /\bgrowing\b/,
+        /\bdemand\b/,
+        /\bsearch\b/,
+        /\battention\b/,
+        /\bvolume\b/,
+        /\bforecasts?\b/,
+        /\bpopularity\b/,
+        /\bpopular\b/,
+        /\bgrowth\b/,
+        /\bhistorical\b/,
+        /\bdata\s+series\b/,
+        /\bstatistics\b/,
+        /\bcharts?\b/
+    ];
+    return demandKeywords.some(pat => pat.test(q));
+}
+export async function addCoverageAnnotation(data, query, searchedGraphs, limit, skipEvidenceCheck = false, catalog = getGraphs(), options) {
+    if (!data || typeof data !== 'object')
+        return data;
+    let normalizedData = data;
+    if (Array.isArray(data)) {
+        normalizedData = { rows: data, dataStatus: 'ok' };
+    }
+    const layerMap = {
+        'industry report': 'report'
+    };
+    const uniqueTypes = new Set(searchedGraphs.map(g => layerMap[g.graph_type] || g.graph_type).filter(Boolean));
+    const layersSearched = Array.from(uniqueTypes);
+    // ── Check for explicit backend errors (e.g. NEO4J_AUTH_MISSING, auth failures, 5xx) ──
+    const errDetail = normalizedData.error || normalizedData.error_code || normalizedData.code;
+    const isErrStatus = normalizedData.dataStatus === 'error' || normalizedData.status === 'error';
+    if (errDetail || isErrStatus) {
+        normalizedData.coverage = {
+            status: 'error',
+            error: (typeof errDetail === 'string' ? errDetail : JSON.stringify(errDetail)) || 'Backend service error',
+            results_returned: 0,
+            layers_searched: layersSearched,
+        };
+        console.error(`[coverage] status: error (${normalizedData.coverage.error}), query: "${query}"`);
+        return normalizedData;
+    }
+    // Explicitly target rows/results/trends/matches fields, mirroring normalizeTrends
+    let rows = normalizedData.rows;
+    if (!Array.isArray(rows)) {
+        if (Array.isArray(normalizedData.results)) {
+            rows = normalizedData.results;
+        }
+        else if (Array.isArray(normalizedData.trends)) {
+            rows = normalizedData.trends;
+        }
+        else if (Array.isArray(normalizedData.matches)) {
+            rows = normalizedData.matches;
+        }
+        else if (Array.isArray(normalizedData.statistics)) {
+            rows = normalizedData.statistics;
+        }
+        else if (Array.isArray(normalizedData.items)) {
+            rows = normalizedData.items;
+        }
+        else {
+            // Find any array property
+            for (const key of Object.keys(normalizedData)) {
+                if (Array.isArray(normalizedData[key])) {
+                    rows = normalizedData[key];
+                    break;
+                }
+            }
+        }
+    }
+    if (!Array.isArray(rows)) {
+        rows = [];
+    }
+    const resultCount = rows.length;
+    let status = 'ok';
+    let onTopicCount;
+    let isThinRelevance = false;
+    if (resultCount === 0) {
+        status = 'empty';
+    }
+    else {
+        let isThinCount = resultCount < 3;
+        if (limit !== undefined && limit < 3 && resultCount === limit) {
+            isThinCount = false;
+        }
+        // Evidence check guard: only evaluate evidence thinness if rows actually contain
+        // evidence arrays AND evidence was not skipped or opted out.
+        // If resultCount >= 3 and query did not request inline evidence (or evidence was stripped),
+        // missing inline evidence must NOT flag healthy results as 'thin'.
+        const hasEvidenceArrays = rows.some((r) => (Array.isArray(r.evidence) && r.evidence.length > 0) ||
+            (Array.isArray(r.evidence_items) && r.evidence_items.length > 0) ||
+            (Array.isArray(r.evidenceItems) && r.evidenceItems.length > 0) ||
+            (Array.isArray(r.trendEvidence) && r.trendEvidence.length > 0));
+        let isThinEvidence = false;
+        const skipEvidence = skipEvidenceCheck || options?.include_evidence === false || !hasEvidenceArrays;
+        if (!skipEvidence && resultCount >= 3) {
+            isThinEvidence = rows.every((r) => {
+                const count = Array.isArray(r.evidence)
+                    ? r.evidence.length
+                    : Array.isArray(r.evidence_items)
+                        ? r.evidence_items.length
+                        : Array.isArray(r.evidenceItems)
+                            ? r.evidenceItems.length
+                            : Array.isArray(r.trendEvidence)
+                                ? r.trendEvidence.length
+                                : (r.evidence_count || r.evidenceCount || 0);
+                return count < 3;
+            });
+        }
+        // ── Relevance-aware thinness ──
+        // Raw count can look healthy while cross-graph fan-out pads the set with
+        // off-topic rows (each graph contributes its locally-best matches even
+        // for unrelated queries). Count only on-topic rows; requiring
+        // onTopic < resultCount means this never fires when every returned row
+        // is on-topic (that case is already governed by the count/limit rules).
+        const relevance = countOnTopicRows(rows, query, searchedGraphs, catalog);
+        if (relevance.evaluated) {
+            onTopicCount = relevance.onTopic;
+            if (relevance.onTopic < 3 && relevance.onTopic < resultCount) {
+                isThinRelevance = true;
+            }
+        }
+        if (isThinCount || isThinEvidence || isThinRelevance) {
+            status = 'thin';
+        }
+        // ── Respect Backend dataStatus / on_topic_total ──
+        // Fodda API evaluates vector similarity and relevance scores directly in the graph layer.
+        // When normalizedData.dataStatus === 'TREND_MATCH' or (on_topic_total >= 3),
+        // the backend has already confirmed that the returned trends are genuine on-topic matches.
+        // MCP's secondary heuristics should not downgrade a confirmed TREND_MATCH to 'thin'.
+        const backendOnTopicTotal = normalizedData.on_topic_total ?? options?.onTopicTotal;
+        const isBackendTrendMatch = normalizedData.dataStatus === 'TREND_MATCH' ||
+            (typeof backendOnTopicTotal === 'number' && backendOnTopicTotal >= 3);
+        if (isBackendTrendMatch && resultCount >= 3) {
+            status = 'ok';
+            if (onTopicCount !== undefined && onTopicCount < 3) {
+                onTopicCount = Math.min(resultCount, Math.max(3, typeof backendOnTopicTotal === 'number' ? backendOnTopicTotal : 3));
+            }
+        }
+    }
+    const isDemand = isDemandShaped(query);
+    let suggestedAction = undefined;
+    if (status === 'empty' || status === 'thin' || isDemand) {
+        let reason = '';
+        if (status === 'empty') {
+            reason = 'curated coverage empty; supplemental provides external trends and data series';
+        }
+        else if (status === 'thin') {
+            reason = isThinRelevance
+                ? `curated coverage thin: only ${onTopicCount} of ${resultCount} results are on-topic for this query; supplemental covers demand and participation signals for this domain`
+                : 'curated coverage thin; supplemental covers demand and participation signals for this domain';
+        }
+        else {
+            reason = 'curated coverage is OK, but query is explicitly demand- or attention-shaped; supplemental adds value via live signals';
+        }
+        const suggestedArgs = { query };
+        // Sourced from graph ids present in the result rows, fall back to searchedGraphs
+        const rowGraphIds = [...new Set(rows.map((r) => r.graphId || r._use_this_graphId || r.psfk_graph_slug || r.graph_id).filter(Boolean))];
+        if (rowGraphIds.length > 0) {
+            suggestedArgs.graph_ids = rowGraphIds;
+        }
+        else if (searchedGraphs.length > 0) {
+            suggestedArgs.graph_ids = searchedGraphs.map(g => g.graph_id);
+        }
+        suggestedAction = {
+            tool: 'get_supplemental_context',
+            arguments: suggestedArgs,
+            reason
+        };
+    }
+    normalizedData.coverage = {
+        status,
+        results_returned: resultCount,
+        layers_searched: layersSearched,
+    };
+    if (onTopicCount !== undefined) {
+        normalizedData.coverage.results_on_topic = onTopicCount;
+    }
+    if (suggestedAction) {
+        normalizedData.coverage.suggested_action = suggestedAction;
+    }
+    // Machine-only recovery ladder: thin/empty coverage is never announced to
+    // the user. The client recovers via suggested_action first; escalation
+    // exists only for when that recovery also comes back dry.
+    if (status === 'thin' || status === 'empty') {
+        normalizedData.coverage.presentation = 'internal';
+        normalizedData.coverage.escalation = {
+            when: 'Only if suggested_action also returns nothing usable for this query',
+            say: 'This is what we have on this right now.',
+            options: [
+                {
+                    tool: 'deep_research_topic',
+                    arguments: { query },
+                    reason: 'commission a Deep Dive report combining expert graph intelligence with live web research',
+                },
+                {
+                    action: 'web_llm_research',
+                    reason: 'run your own web/LLM research pass, clearly attributing non-Fodda findings',
+                },
+            ],
+        };
+    }
+    normalizedData.next_moves = await generateNextMoves(rows, query, searchedGraphs, status, onTopicCount, suggestedAction, catalog, options?.analysts || getAnalysts(), options);
+    console.error(`[coverage] status: ${status}, results: ${resultCount}/${limit || 'default'}${onTopicCount !== undefined ? `, on-topic: ${onTopicCount}` : ''}, query: "${query}"`);
+    return normalizedData;
+}
+const suggestCache = new Map();
+const SUGGEST_CACHE_TTL_MS = 10 * 60 * 1000; // 10 minutes
+const MAX_SUGGEST_CACHE_SIZE = 500;
+export function clearSuggestCacheForTesting() {
+    suggestCache.clear();
+}
+function setSuggestCacheEntry(key, sources) {
+    const now = Date.now();
+    if (suggestCache.size >= MAX_SUGGEST_CACHE_SIZE) {
+        for (const [k, v] of suggestCache.entries()) {
+            if (now - v.timestamp >= SUGGEST_CACHE_TTL_MS) {
+                suggestCache.delete(k);
+            }
+        }
+    }
+    if (suggestCache.size >= MAX_SUGGEST_CACHE_SIZE) {
+        const oldestKey = suggestCache.keys().next().value;
+        if (oldestKey)
+            suggestCache.delete(oldestKey);
+    }
+    suggestCache.set(key, { timestamp: now, sources });
+}
+export function truncateAtWordBoundary(str, maxLength) {
+    if (!str || str.length <= maxLength)
+        return str;
+    const sub = str.slice(0, maxLength);
+    const lastSpace = sub.lastIndexOf(' ');
+    if (lastSpace > 10) {
+        return sub.slice(0, lastSpace).trim();
+    }
+    return sub.trim();
+}
+export async function fetchSupplementalSuggest(query, options) {
+    const normQuery = query.toLowerCase().trim();
+    const sessionId = options?.sessionId || options?.userId || 'default';
+    const cacheKey = `${sessionId}:${normQuery}`;
+    const cached = suggestCache.get(cacheKey);
+    if (cached && (Date.now() - cached.timestamp) < SUGGEST_CACHE_TTL_MS) {
+        return cached.sources;
+    }
+    try {
+        let suggestPromise = null;
+        if (options?.suggestPromise) {
+            suggestPromise = options.suggestPromise;
+        }
+        else if (options?.suggestFn) {
+            suggestPromise = options.suggestFn(query);
+        }
+        else if (options?.foddaRequest && options?.apiKey) {
+            suggestPromise = options.foddaRequest('GET', `/v1/supplemental/suggest?query=${encodeURIComponent(query)}`, options.apiKey, options.userId || '');
+        }
+        if (!suggestPromise) {
+            return null;
+        }
+        let timer;
+        const timeoutPromise = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error('suggest timeout (3000ms)')), 3000);
+        });
+        const data = await Promise.race([suggestPromise, timeoutPromise]);
+        clearTimeout(timer);
+        const sources = Array.isArray(data) ? data : (Array.isArray(data?.sources) ? data.sources : []);
+        setSuggestCacheEntry(cacheKey, sources);
+        return sources;
+    }
+    catch (err) {
+        console.error(`[next_moves] suggest fetch failed: ${err.message}`);
+        return null;
+    }
+}
+/**
+ * Clean and truncate a single theme candidate to <= 3 words, lowercase.
+ */
+export function cleanThemeCandidate(raw) {
+    if (!raw || typeof raw !== 'string')
+        return null;
+    let cleaned = raw
+        .replace(/^\[(?:REVIW|REVIEW|DRAFT|WIP)\]\s*/i, '')
+        .replace(/[&/+,]+/g, ' ')
+        .replace(/[^a-zA-Z0-9\s-]/g, '')
+        .toLowerCase()
+        .trim();
+    if (!cleaned)
+        return null;
+    const stopWords = new Set(['and', 'or', 'the', 'in', 'of', 'for', 'with', 'to', 'a', 'an']);
+    let words = cleaned.split(/\s+/).filter(Boolean);
+    while (words.length > 0 && words[0] && stopWords.has(words[0]))
+        words.shift();
+    while (words.length > 0 && words[words.length - 1] && stopWords.has(words[words.length - 1]))
+        words.pop();
+    if (words.length === 0)
+        return null;
+    if (words.length > 3) {
+        words = words.slice(0, 3);
+        while (words.length > 0 && words[words.length - 1] && stopWords.has(words[words.length - 1]))
+            words.pop();
+    }
+    return words.length > 0 ? words.join(' ') : null;
+}
+/**
+ * Format raw theme candidates (topics, sectors, trend names, titles)
+ * into concise, lowercase theme phrases (<= 3 words each).
+ */
+export function formatThemePhrase(rawCandidates, fallback = 'emerging signals') {
+    const cleanedThemes = [];
+    const seen = new Set();
+    for (const raw of rawCandidates) {
+        const cleaned = cleanThemeCandidate(raw);
+        if (cleaned && !seen.has(cleaned)) {
+            seen.add(cleaned);
+            cleanedThemes.push(cleaned);
+        }
+    }
+    if (cleanedThemes.length === 0) {
+        return cleanThemeCandidate(fallback) || fallback.toLowerCase();
+    }
+    if (cleanedThemes.length === 1 && cleanedThemes[0]) {
+        return cleanedThemes[0];
+    }
+    return `${cleanedThemes[0]} and ${cleanedThemes[1]}`;
+}
+/**
+ * Cross-cutting or generic tech/strategy terms that appear across multiple domains.
+ * When evaluating domain fit, matching solely on these words does NOT constitute
+ * genuine domain overlap if the query contains a specific vertical or domain term.
+ */
+export const CROSS_CUTTING_MODIFIERS = new Set([
+    'ai', 'artificial intelligence', 'genai', 'tech', 'technology', 'trends', 'trend',
+    'insights', 'insight', 'strategy', 'strategic', 'systems', 'system',
+    'innovation', 'innovations', 'future', 'futures', 'management', 'data',
+    'analytics', 'research', 'market', 'markets', 'consumer', 'consumers',
+    'culture', 'experience', 'experiences', 'overview', 'summary', 'report',
+    'industry', 'growth', 'landscape', 'benchmarks', 'benchmark'
+]);
+/**
+ * Score and rank candidate experts for a query.
+ * Reuses the shared scoring spine: domain overlap, blind-spot exclusion,
+ * self-recommendation suppression, and honest failure.
+ */
+export function findCandidateExperts(query, options) {
+    const rawAnalysts = options?.analysts || getAnalysts();
+    const activeAnalysts = rawAnalysts.filter(a => {
+        const st = (a.status || a.Status || '').toLowerCase().trim();
+        return !st || st === 'active' || st === 'unclaimed' || st === 'on_request' || st === 'on request';
+    });
+    const isCurrentAnalyst = (a) => {
+        const excludeId = options?.currentAnalystId || options?.excludeAnalystId;
+        if (!excludeId)
+            return false;
+        const cur = excludeId.toLowerCase().trim();
+        return (a.analyst_id && a.analyst_id.toLowerCase().trim() === cur) ||
+            (a.name && a.name.toLowerCase().trim() === cur);
+    };
+    const qLower = (query || '').toLowerCase().trim();
+    const queryTokens = specificQueryTokens(query);
+    const allQueryWords = qLower.split(/[^a-z0-9]+/).filter((w) => w.length >= 3 && !GENERIC_QUERY_TOKENS.has(w));
+    const queryDomainWords = allQueryWords.filter(w => !CROSS_CUTTING_MODIFIERS.has(w));
+    const isBrandOrCorporateQuery = Boolean(options?.isBrandTracker ||
+        /brand|financial|earnings|corporate|cmo|ceo|cfo|executive|revenue|margin|quarterly|investor|q[1-4]|balance sheet/i.test(qLower));
+    const isPhilosophicalQuery = /art\b|aesthetic|philosophy|philosophical|criticism|craftsmanship|harlem renaissance|aesthetic theory|ethics of art|ruskin|locke\b/i.test(qLower);
+    function getCategory(a) {
+        if (a.category)
+            return a.category;
+        if (a.is_human_agent || a.is_verified_real_person)
+            return 'human_agent';
+        if (a.is_c_suite_agent || /brand-(cmo|ceo|cfo)/i.test(a.analyst_id || ''))
+            return 'c_suite_agent';
+        if (a.is_classic_agent)
+            return 'classic_agent';
+        const sub = (a.graphSubType || a.graph_sub_type || a.type || a.kind || '').toString().toLowerCase();
+        if (sub.includes('classic'))
+            return 'classic_agent';
+        if (sub.includes('digital twin') || sub.includes('human'))
+            return 'human_agent';
+        if (sub.includes('c-suite') || sub.includes('executive'))
+            return 'c_suite_agent';
+        return 'synthetic_agent';
+    }
+    const searchedGraphs = options?.searchedGraphs || (options?.graphs ? options.graphs : getRelevantGraphs(query, 4, 15, 0.10));
+    const rowsByGraph = options?.rowsByGraph || new Map();
+    const scoredAnalysts = [];
+    for (const a of activeAnalysts) {
+        if (isCurrentAnalyst(a))
+            continue;
+        let baseScore = 0;
+        let directMatch = false;
+        let hasExplicitMatch = false;
+        const category = getCategory(a);
+        // Extract expert name and slug parts for direct identification and blindspot immunity
+        const aName = (a.name || '').toLowerCase().trim();
+        const aSlug = (a.analyst_id || '').toLowerCase().trim();
+        const nameParts = new Set([
+            ...aName.split(/\s+/).filter((p) => p.length >= 3),
+            ...aSlug.split(/[-_]+/).filter((p) => p.length >= 3)
+        ]);
+        // 1. Negative signal: Blind spot / outside_their_lane
+        const rawBlindSpots = [
+            ...(Array.isArray(a.outside_their_lane) ? a.outside_their_lane : (typeof a.outside_their_lane === 'string' ? [a.outside_their_lane] : [])),
+            ...(Array.isArray(a.blind_spots) ? a.blind_spots : (typeof a.blind_spots === 'string' ? [a.blind_spots] : [])),
+        ].join(' ').toLowerCase();
+        let hasBlindSpot = false;
+        if (rawBlindSpots.length > 0) {
+            for (const t of queryTokens) {
+                if (nameParts.has(t))
+                    continue; // Never disqualify an expert for matching their own name or slug!
+                if (t.length >= 3 && rawBlindSpots.includes(t)) {
+                    hasBlindSpot = true;
+                    baseScore -= 20;
+                }
+            }
+            for (const w of allQueryWords) {
+                if (nameParts.has(w))
+                    continue; // Never disqualify an expert for matching their own name or slug!
+                if (w.length >= 4 && rawBlindSpots.includes(w)) {
+                    hasBlindSpot = true;
+                    baseScore -= 10;
+                }
+            }
+        }
+        // 2. Positive signal: expert_in & what_they_offer
+        const expertIn = [
+            ...(Array.isArray(a.expert_in) ? a.expert_in : (typeof a.expert_in === 'string' ? [a.expert_in] : [])),
+            ...(Array.isArray(a.what_they_offer) ? a.what_they_offer : (typeof a.what_they_offer === 'string' ? [a.what_they_offer] : [])),
+        ].join(' ').toLowerCase();
+        if (expertIn.length > 0) {
+            if (qLower.length > 5 && expertIn.includes(qLower)) {
+                baseScore += 8;
+                hasExplicitMatch = true;
+            }
+            for (const t of queryTokens) {
+                if (expertIn.includes(t)) {
+                    const isDomainToken = queryDomainWords.length === 0 || queryDomainWords.includes(t) || !CROSS_CUTTING_MODIFIERS.has(t);
+                    baseScore += isDomainToken ? 4 : 1.5;
+                    if (t.length >= 4 && isDomainToken)
+                        hasExplicitMatch = true;
+                }
+            }
+            for (const w of allQueryWords) {
+                if (expertIn.includes(w)) {
+                    const isDomainWord = queryDomainWords.length === 0 || queryDomainWords.includes(w) || !CROSS_CUTTING_MODIFIERS.has(w);
+                    baseScore += isDomainWord ? 1.5 : 0.5;
+                    if (w.length >= 4 && isDomainWord)
+                        hasExplicitMatch = true;
+                }
+            }
+        }
+        // 2b. Positive signal: direct name or analyst_id match (for lookup/booking/hiring intent)
+        if (qLower.includes(aName) && aName.length >= 4) {
+            baseScore += 15;
+            hasExplicitMatch = true;
+            directMatch = true;
+        }
+        else if (aSlug && (qLower.includes(aSlug) || aSlug.includes(qLower))) {
+            baseScore += 15;
+            hasExplicitMatch = true;
+            directMatch = true;
+        }
+        else {
+            for (const part of nameParts) {
+                if (queryTokens.includes(part) || allQueryWords.includes(part)) {
+                    baseScore += 10;
+                    hasExplicitMatch = true;
+                    directMatch = true;
+                    break;
+                }
+            }
+        }
+        // 3. Positive signal: topics
+        const aTopics = (Array.isArray(a.topics) ? a.topics : []).map((t) => (typeof t === 'string' ? t.toLowerCase() : '')).filter(Boolean);
+        for (const tp of aTopics) {
+            if (qLower.includes(tp) || tp.includes(qLower)) {
+                baseScore += 5;
+                hasExplicitMatch = true;
+            }
+            for (const t of queryTokens) {
+                if (tp.includes(t) || t.includes(tp)) {
+                    const isDomainToken = queryDomainWords.length === 0 || queryDomainWords.includes(t) || !CROSS_CUTTING_MODIFIERS.has(t);
+                    baseScore += isDomainToken ? 3 : 1;
+                    if (t.length >= 3 && tp.length >= 3 && isDomainToken)
+                        hasExplicitMatch = true;
+                }
+            }
+            for (const w of allQueryWords) {
+                if (tp.includes(w) || w.includes(tp)) {
+                    const isDomainWord = queryDomainWords.length === 0 || queryDomainWords.includes(w) || !CROSS_CUTTING_MODIFIERS.has(w);
+                    baseScore += isDomainWord ? 1.5 : 0.5;
+                    if (w.length >= 3 && tp.length >= 3 && isDomainWord)
+                        hasExplicitMatch = true;
+                }
+            }
+        }
+        // 4. Positive signal: description (supporting context)
+        const desc = (typeof a.description === 'string' ? a.description : '').toLowerCase();
+        if (desc.length > 0) {
+            if (qLower.length > 5 && desc.includes(qLower)) {
+                baseScore += 4;
+            }
+            for (const t of queryTokens) {
+                if (desc.includes(t)) {
+                    baseScore += 2;
+                }
+            }
+            for (const w of allQueryWords) {
+                if (desc.includes(w)) {
+                    baseScore += 1;
+                }
+            }
+        }
+        // 5. Positive signal: Searched graphs & graph relevance scores
+        for (const g of searchedGraphs) {
+            const gid = (typeof g === 'string' ? g : (g.graph_id || g.id || '')).toLowerCase().trim();
+            const gCurator = (typeof g === 'object' && g.curator ? g.curator : '').toLowerCase().trim();
+            const isOwner = (gid && (gid === aSlug || gid.includes(aSlug) || aSlug.includes(gid))) ||
+                (gCurator && (gCurator === aName || gCurator.includes(aName) || aName.includes(gCurator)));
+            if (isOwner) {
+                // If graph has a router relevance score, use it directly.
+                // If unscored (e.g. broadcast or unranked search), award positive score ONLY if
+                // this graph actually returned matching results in rowsByGraph.
+                const rowsForGraph = rowsByGraph.get(gid) || (aSlug ? rowsByGraph.get(aSlug) : null) || [];
+                const relScore = (typeof g === 'object' && typeof g.relevanceScore === 'number')
+                    ? g.relevanceScore
+                    : (rowsForGraph.length > 0 ? 0.8 : 0);
+                if (relScore > 0) {
+                    baseScore += relScore * 5.0;
+                    hasExplicitMatch = true;
+                    if (relScore >= 0.5)
+                        directMatch = true;
+                }
+            }
+        }
+        let score = baseScore;
+        // ── Tier Intent Weighting ──
+        // Require base token relevance score >= 6 before applying any status preference boost
+        // so irrelevant profiles (sam-horn, taxtalk-online) are excluded on local fallback.
+        if (baseScore >= 6) {
+            if (category === 'c_suite_agent') {
+                if (isBrandOrCorporateQuery) {
+                    score += 6.0;
+                }
+                else {
+                    score -= 5.0;
+                }
+            }
+            else if (category === 'classic_agent') {
+                if (isPhilosophicalQuery) {
+                    score += 5.0;
+                }
+                else {
+                    score -= 10.0; // Classic thinkers must never outrank living practitioners on contemporary queries
+                }
+            }
+            else if (category === 'human_agent' || a.is_verified_real_person) {
+                score += 3.0; // Prioritize living human practitioners over synthetic agents
+            }
+        }
+        scoredAnalysts.push({ analyst: a, score, hasBlindSpot, hasExplicitMatch, directMatch });
+    }
+    // Require minimum threshold score (>= 6.0), explicit domain/topic match, and no disqualifying blind spot match
+    const MIN_EXPERT_FIT_SCORE = 6.0;
+    const validCandidates = scoredAnalysts
+        .filter(s => s.score >= MIN_EXPERT_FIT_SCORE && (s.directMatch || (s.hasExplicitMatch && !s.hasBlindSpot)))
+        .sort((a, b) => b.score - a.score);
+    const maxLimit = Math.min(Math.max(options?.limit || 3, 1), 3);
+    const topCandidates = validCandidates.slice(0, maxLimit);
+    const status = options?.status;
+    return topCandidates.map(c => {
+        const matchedAnalyst = c.analyst;
+        let lane = '';
+        const expertInStr = Array.isArray(matchedAnalyst.expert_in)
+            ? matchedAnalyst.expert_in.filter(Boolean).join(', ')
+            : (typeof matchedAnalyst.expert_in === 'string' ? matchedAnalyst.expert_in : '');
+        if (expertInStr.trim().length > 0) {
+            lane = truncateAtWordBoundary(expertInStr.trim(), 60);
+        }
+        else if (matchedAnalyst.description && matchedAnalyst.description.trim().length > 0) {
+            const firstClause = (matchedAnalyst.description.split(/[,.;]/)[0] || '').trim();
+            lane = truncateAtWordBoundary(firstClause, 60);
+        }
+        else if (matchedAnalyst.what_they_offer && typeof matchedAnalyst.what_they_offer === 'string' && matchedAnalyst.what_they_offer.trim().length > 0) {
+            lane = truncateAtWordBoundary(matchedAnalyst.what_they_offer.trim(), 60);
+        }
+        const reason = (status === 'thin' || status === 'empty')
+            ? (lane && lane.length > 3 ? `closest expert lane for ${lane}` : 'closest expert lane for this topic')
+            : (lane && lane.length > 3 ? `covers ${lane} directly` : 'covers this domain directly');
+        const cat = matchedAnalyst.category || getCategory(matchedAnalyst);
+        const statusRaw = (matchedAnalyst.status || matchedAnalyst.Status || '').toLowerCase().trim();
+        const isOnRequest = statusRaw === 'unclaimed' || statusRaw === 'on request' || statusRaw === 'on_request';
+        const expertStatus = isOnRequest ? 'on_request' : 'active';
+        const consult_tool = (matchedAnalyst.consult_tool === 'consult_human_agent' || matchedAnalyst.consult_tool === 'consult_analyst')
+            ? matchedAnalyst.consult_tool
+            : (cat === 'human_agent' ? 'consult_human_agent' : 'consult_analyst');
+        return {
+            analyst_id: matchedAnalyst.analyst_id,
+            display_name: cleanDisplayName(matchedAnalyst.name),
+            category: cat,
+            status: expertStatus,
+            consult_tool,
+            reason,
+            out_of_lane: false
+        };
+    });
+}
+export async function generateNextMoves(rows, query, searchedGraphs, status, onTopicCount, suggestedAction, catalog = getGraphs(), analysts = getAnalysts(), options) {
+    const nextMoves = {
+        scope_prompt: true,
+        presentation: 'internal',
+    };
+    if (options?.knownBrand) {
+        nextMoves.known_brand = options.knownBrand;
+    }
+    const searchedGraphIds = new Set();
+    for (const g of searchedGraphs) {
+        const gid = typeof g === 'string' ? g : (g.graph_id || g.id || g.slug);
+        if (gid)
+            searchedGraphIds.add(gid);
+    }
+    for (const r of rows) {
+        const gid = rowGraphId(r);
+        if (gid)
+            searchedGraphIds.add(gid);
+    }
+    // ── 1. Thread (Pull the thread) ──
+    const tokens = specificQueryTokens(query);
+    const rowsByGraph = new Map();
+    for (const r of rows) {
+        const gid = rowGraphId(r) || (searchedGraphs[0]?.graph_id) || 'unknown';
+        if (!rowsByGraph.has(gid))
+            rowsByGraph.set(gid, []);
+        rowsByGraph.get(gid).push(r);
+    }
+    let maxRemainder = 0;
+    let bestGraphId;
+    let bestGraphTheme;
+    // First pass: check per-graph on_topic_total / total attached to gRows[0]
+    for (const [gid, gRows] of rowsByGraph.entries()) {
+        const onTopicRows = gRows.filter(r => rowMatchesQueryTokens(r, tokens, catalog) || (rowScore(r) >= 0.75 * (TIER_NOMINAL_SCORE[resolveRowTier(r, searchedGraphs, catalog)] ?? 0.8)));
+        const renderedCount = gRows.length;
+        const gTotal = gRows[0]?.on_topic_total ?? gRows[0]?.total_count ?? gRows[0]?.total;
+        let remainder = 0;
+        if (typeof gTotal === 'number' && gTotal > renderedCount) {
+            remainder = gTotal - renderedCount;
+        }
+        if (remainder > maxRemainder) {
+            maxRemainder = remainder;
+            bestGraphId = gid;
+            const themes = [];
+            for (const r of onTopicRows) {
+                if (Array.isArray(r.topics))
+                    themes.push(...r.topics);
+                if (Array.isArray(r.sectors))
+                    themes.push(...r.sectors);
+            }
+            const graphMeta = catalog.find(g => g.graph_id === gid);
+            if (graphMeta?.topics?.length)
+                themes.push(...graphMeta.topics);
+            for (const r of onTopicRows) {
+                if (r.title)
+                    themes.push(r.title);
+                if (r.trend_name)
+                    themes.push(r.trend_name);
+            }
+            bestGraphTheme = formatThemePhrase(themes, graphMeta?.domain || 'emerging signals');
+        }
+    }
+    // Second pass: if per-graph totals were not present on rows, check aggregate multi-graph totals in options
+    if (maxRemainder === 0) {
+        const totalMulti = options?.onTopicTotal ?? options?.total;
+        if (typeof totalMulti === 'number' && totalMulti > rows.length) {
+            maxRemainder = totalMulti - rows.length;
+            let maxCount = 0;
+            for (const [gid, gRows] of rowsByGraph.entries()) {
+                if (gRows.length > maxCount) {
+                    maxCount = gRows.length;
+                    bestGraphId = gid;
+                }
+            }
+            if (bestGraphId) {
+                const gRows = rowsByGraph.get(bestGraphId) || [];
+                const themes = [];
+                for (const r of gRows) {
+                    if (Array.isArray(r.topics))
+                        themes.push(...r.topics);
+                    if (Array.isArray(r.sectors))
+                        themes.push(...r.sectors);
+                }
+                const graphMeta = catalog.find(g => g.graph_id === bestGraphId);
+                if (graphMeta?.topics?.length)
+                    themes.push(...graphMeta.topics);
+                for (const r of gRows) {
+                    if (r.title)
+                        themes.push(r.title);
+                    if (r.trend_name)
+                        themes.push(r.trend_name);
+                }
+                bestGraphTheme = formatThemePhrase(themes, graphMeta?.domain || 'emerging signals');
+            }
+        }
+    }
+    if (options?.isBrandTracker) {
+        if (rows.length > 0) {
+            let maxCount = 0;
+            let topGraphId;
+            for (const [gid, gRows] of rowsByGraph.entries()) {
+                if (gRows.length > maxCount) {
+                    maxCount = gRows.length;
+                    topGraphId = gid;
+                }
+            }
+            if (topGraphId) {
+                const gRows = rowsByGraph.get(topGraphId) || [];
+                const themes = [];
+                for (const r of gRows) {
+                    if (Array.isArray(r.topics))
+                        themes.push(...r.topics);
+                    if (Array.isArray(r.sectors))
+                        themes.push(...r.sectors);
+                }
+                const gMeta = catalog.find(g => g.graph_id === topGraphId);
+                if (gMeta?.topics?.length)
+                    themes.push(...gMeta.topics);
+                for (const r of gRows) {
+                    if (r.trend_name)
+                        themes.push(r.trend_name);
+                    if (r.title)
+                        themes.push(r.title);
+                }
+                const bestTheme = formatThemePhrase(themes, gMeta?.domain || 'emerging signals');
+                const display = gMeta ? buildDisplayName(gMeta) : (gRows[0]?.graphName || topGraphId);
+                nextMoves.thread = {
+                    kind: 'more_in_graph',
+                    graph_id: topGraphId,
+                    graph_display: display,
+                    remaining_count: maxCount,
+                    theme: bestTheme,
+                };
+            }
+        }
+        else {
+            // Empty brand footprint: try to find relevant unsearched domain graph if score >= 0.10
+            let relevantCandidates = [];
+            try {
+                relevantCandidates = getRelevantGraphs(query);
+            }
+            catch {
+                relevantCandidates = [];
+            }
+            const unsearchedDomain = relevantCandidates.find(cand => cand.graph && !searchedGraphIds.has(cand.graph.graph_id) && (cand.score ?? 0) >= 0.10)?.graph;
+            const primarySearched = searchedGraphs[0];
+            const primaryGid = typeof primarySearched === 'string' ? primarySearched : primarySearched?.graph_id;
+            const primaryMeta = catalog.find(g => g.graph_id === primaryGid);
+            const primaryDisplay = primaryMeta ? buildDisplayName(primaryMeta) : (primaryGid || 'the graph');
+            if (unsearchedDomain) {
+                const topDisplay = buildDisplayName(unsearchedDomain);
+                nextMoves.thread = {
+                    kind: 'honest_thin',
+                    graph_id: primaryGid || unsearchedDomain.graph_id,
+                    graph_display: primaryDisplay,
+                    adjacent: {
+                        graph_id: unsearchedDomain.graph_id,
+                        graph_display: topDisplay,
+                        reason: unsearchedDomain.headline || unsearchedDomain.domain || unsearchedDomain.name,
+                    }
+                };
+            }
+            else {
+                nextMoves.thread = {
+                    kind: 'honest_thin',
+                    graph_id: primaryGid,
+                    graph_display: primaryDisplay,
+                    text: `That's what Fodda holds on this right now.`,
+                };
+            }
+        }
+    }
+    else {
+        const bestMeta = bestGraphId ? catalog.find(g => g.graph_id === bestGraphId) : undefined;
+        const trendCount = bestMeta?.trend_count;
+        const gOnTopicTotal = bestGraphId
+            ? (rowsByGraph.get(bestGraphId)?.[0]?.on_topic_total ?? options?.onTopicTotal ?? (maxRemainder + rows.length))
+            : undefined;
+        const isSmallReportOrExhausted = (typeof trendCount === 'number' && trendCount > 0 && trendCount <= 15) ||
+            (typeof trendCount === 'number' && trendCount > 0 && typeof gOnTopicTotal === 'number' && gOnTopicTotal >= 0.6 * trendCount);
+        const canEmitMoreInGraph = maxRemainder > 0 && bestGraphId && !isSmallReportOrExhausted;
+        if (canEmitMoreInGraph && bestGraphId) {
+            const display = bestMeta ? buildDisplayName(bestMeta) : bestGraphId;
+            nextMoves.thread = {
+                kind: 'more_in_graph',
+                graph_id: bestGraphId,
+                graph_display: display,
+                remaining_count: maxRemainder,
+                theme: bestGraphTheme,
+            };
+        }
+        else {
+            // Fall through to unsearched adjacent_room or honest_thin
+            let relevantCandidates = [];
+            try {
+                relevantCandidates = getRelevantGraphs(query);
+            }
+            catch {
+                relevantCandidates = [];
+            }
+            const unsearchedCandidate = relevantCandidates.find(cand => cand.graph && !searchedGraphIds.has(cand.graph.graph_id) && (cand.score ?? 0) >= 0.10);
+            const primarySearched = searchedGraphs[0];
+            const primaryGid = typeof primarySearched === 'string' ? primarySearched : primarySearched?.graph_id;
+            const primaryMeta = catalog.find(g => g.graph_id === primaryGid);
+            const primaryDisplay = primaryMeta ? buildDisplayName(primaryMeta) : (primaryGid || 'the graph');
+            if (unsearchedCandidate) {
+                const adjG = unsearchedCandidate.graph;
+                const adjDisplay = buildDisplayName(adjG);
+                nextMoves.thread = {
+                    kind: (status === 'thin' || status === 'empty' || isSmallReportOrExhausted) ? 'honest_thin' : 'adjacent_room',
+                    graph_id: primaryGid || adjG.graph_id,
+                    graph_display: primaryDisplay,
+                    adjacent: {
+                        graph_id: adjG.graph_id,
+                        graph_display: adjDisplay,
+                        reason: adjG.headline || adjG.domain || adjG.description || adjG.name,
+                    }
+                };
+            }
+            else if (status === 'thin' || status === 'empty' || isSmallReportOrExhausted) {
+                // Honest thin without hallucinated adjacent graph: never fabricate catalog[0] or blind unsearched fallback
+                nextMoves.thread = {
+                    kind: 'honest_thin',
+                    graph_id: primaryGid,
+                    graph_display: primaryDisplay,
+                    text: `That's what Fodda holds on this right now.`,
+                };
+            }
+            else {
+                nextMoves.thread = undefined;
+            }
+        }
+    }
+    // ── 2. Specific (Go specific: brands, statistics_source, expert) ──
+    const specific = {};
+    // Brands: extract competitive landscape or top 2 brand entities present in returned rows
+    if (options?.competitiveLandscape && options.competitiveLandscape.length > 0) {
+        specific.brands = options.competitiveLandscape.slice(0, 2);
+    }
+    else if (options?.isBrandTracker) {
+        // For brand reports, if competitiveLandscape is empty or omitted, leave specific.brands undefined — never pad!
+        specific.brands = undefined;
+    }
+    else {
+        const tokens = specificQueryTokens(query);
+        const onTopicRows = rows.filter(r => rowMatchesQueryTokens(r, tokens, catalog) || (rowScore(r) >= 0.75 * (TIER_NOMINAL_SCORE[resolveRowTier(r, searchedGraphs, catalog)] ?? 0.8)));
+        // If no on-topic rows exist, leave specific.brands undefined (do not fall back to off-topic noise rows)
+        if (onTopicRows.length > 0) {
+            const publisherTokens = buildPublisherExclusionSet(searchedGraphs, catalog, onTopicRows);
+            const brandCounts = new Map();
+            for (const r of onTopicRows) {
+                if (!isRowBrandEligible(r))
+                    continue;
+                const brandList = [];
+                if (Array.isArray(r.brandNames))
+                    brandList.push(...r.brandNames);
+                else if (typeof r.brandNames === 'string')
+                    brandList.push(...r.brandNames.split('|'));
+                if (Array.isArray(r.brands))
+                    brandList.push(...r.brands);
+                if (typeof r.brand === 'string' && r.brand)
+                    brandList.push(r.brand);
+                if (typeof r.Brand === 'string' && r.Brand)
+                    brandList.push(...r.Brand.split('|'));
+                else if (Array.isArray(r.Brand))
+                    brandList.push(...r.Brand);
+                if (typeof r.company === 'string' && r.company)
+                    brandList.push(r.company);
+                if (Array.isArray(r.entities?.brands))
+                    brandList.push(...r.entities.brands);
+                for (const b of brandList) {
+                    if (typeof b === 'string' && b.trim().length > 1) {
+                        const clean = b.trim();
+                        const norm = normalizeBrandKey(clean);
+                        if (!norm)
+                            continue;
+                        if (isPublisherBrand(clean, publisherTokens))
+                            continue;
+                        const existing = brandCounts.get(norm);
+                        if (existing) {
+                            existing.count++;
+                        }
+                        else {
+                            brandCounts.set(norm, { count: 1, displayName: clean });
+                        }
+                    }
+                }
+            }
+            if (brandCounts.size > 0) {
+                const qLow = query.toLowerCase();
+                const sortedBrands = [...brandCounts.values()]
+                    .filter(b => {
+                    const bLow = b.displayName.toLowerCase();
+                    return bLow !== qLow && !qLow.includes(bLow) && !bLow.includes(qLow);
+                })
+                    .sort((a, b) => b.count - a.count)
+                    .map(b => b.displayName)
+                    .slice(0, 2);
+                if (sortedBrands.length > 0) {
+                    specific.brands = sortedBrands;
+                }
+            }
+        }
+    }
+    // Statistics source: supplemental source or scored stat dataset
+    if (options?.earningsStatsSource) {
+        specific.statistics_source = options.earningsStatsSource;
+    }
+    else if (options?.earningsTicker || options?.isBrandTracker) {
+        // Format with brand display name: "Lululemon's latest earnings and financial results"
+        const brandName = options?.brandDisplayName || options?.brandName || query || 'the company';
+        const cleanName = brandName.trim();
+        let possessiveName = `${cleanName}'s`;
+        if (cleanName.endsWith("'s") || cleanName.endsWith("’s")) {
+            possessiveName = cleanName;
+        }
+        else if (cleanName.endsWith("s") || cleanName.endsWith("S")) {
+            possessiveName = `${cleanName}'`;
+        }
+        if (options?.earningsTicker) {
+            specific.statistics_source = `${possessiveName} latest earnings and financial results`;
+        }
+        else if (options?.isBrandTracker) {
+            // If no competitor brands were found, fall back to market demand signals so line 2 is never empty
+            if (!specific.brands || specific.brands.length === 0) {
+                specific.statistics_source = 'Google Trends and market demand signals';
+            }
+        }
+    }
+    else {
+        const qLower = query.toLowerCase();
+        const isStatOrMarketShaped = suggestedAction !== undefined ||
+            status === 'thin' ||
+            status === 'empty' ||
+            isDemandShaped(query) ||
+            options?.knownBrand !== undefined ||
+            (specific.brands && specific.brands.length > 0) ||
+            /(?:market|spend|sales|growth|size|volume|rate|adoption|share|stats?|numbers?|forecast|demographics?|economic|inflation|pricing|consumer|retail|cpg|beauty|fashion|auto|tech|work|travel|food|drink|beverage|culture|trends?|brand|performance|activity)/i.test(qLower);
+        if (isStatOrMarketShaped) {
+            let suggestHandled = false;
+            if (options?.foddaRequest || options?.suggestFn || options?.suggestPromise) {
+                const sources = await fetchSupplementalSuggest(query, options);
+                if (sources && sources.length > 0) {
+                    const validSources = sources.filter(s => s && s.returns_draft !== true && s.name);
+                    if (validSources.length > 0) {
+                        const topSources = validSources.slice(0, 2);
+                        if (topSources.length === 2 && topSources[0] && topSources[1]) {
+                            specific.statistics_source = `${topSources[0].name} and ${topSources[1].name}`;
+                        }
+                        else if (topSources[0]) {
+                            specific.statistics_source = topSources[0].name;
+                        }
+                        suggestHandled = true;
+                        options?.sessionTracker?.recordSuggestPath?.('suggest');
+                        console.error(`[next_moves] statistics_source from suggest: "${specific.statistics_source}"`);
+                    }
+                }
+            }
+            if (!suggestHandled) {
+                options?.sessionTracker?.recordSuggestPath?.('regex-fallback');
+                console.error(`[next_moves] statistics_source from regex-fallback`);
+                if (/(?:retail|spend|sales|commerce|shopping|store|grocery|cpg|consumer)/i.test(qLower)) {
+                    specific.statistics_source = 'Census retail trade and spending data';
+                }
+                else if (/(?:search|demand|interest|popular|google|volume|buzz|social)/i.test(qLower)) {
+                    specific.statistics_source = 'Google Trends search volume and breakout queries';
+                }
+                else if (/(?:employment|labor|job|wage|worker|workplace|talent|hiring)/i.test(qLower)) {
+                    specific.statistics_source = 'BLS labor and employment metrics';
+                }
+                else if (/(?:economic|inflation|cpi|interest\s+rate|gdp|macro|fed|recession)/i.test(qLower)) {
+                    specific.statistics_source = 'FRED macroeconomic series';
+                }
+                else if (/(?:beauty|fashion|apparel|luxury|sport|wellness|food|beverage)/i.test(qLower)) {
+                    specific.statistics_source = 'Census and Google Trends market demand data';
+                }
+                else {
+                    specific.statistics_source = 'Census and FRED market statistics';
+                }
+            }
+        }
+    }
+    // Expert: scored lane-fit picker over active analysts using shared findCandidateExperts
+    const candidateExperts = findCandidateExperts(query, {
+        analysts,
+        graphs: catalog,
+        limit: 1,
+        currentAnalystId: options?.currentAnalystId,
+        searchedGraphs,
+        rowsByGraph,
+        status,
+        isBrandTracker: options?.isBrandTracker
+    });
+    if (candidateExperts.length > 0 && candidateExperts[0]) {
+        specific.expert = candidateExperts[0];
+    }
+    if (Object.keys(specific).length > 0) {
+        nextMoves.specific = specific;
+    }
+    nextMoves.scope = options?.knownBrand
+        ? `Want this cut to ${options.knownBrand} specifically?`
+        : `If you tell me the brand or brief you're working on, I'll cut this to that.`;
+    const cleanTopic = options?.knownBrand || options?.brandDisplayName || nextMoves.thread?.theme || query.trim();
+    const isOnRequestExpert = specific.expert?.status === 'on_request';
+    const isExpertHuman = specific.expert?.category === 'human_agent' || specific.expert?.consult_tool === 'consult_human_agent';
+    let expertTargetTool = 'find_expert';
+    let expertName = 'Consult specialist';
+    let expertDescription = 'Get practitioner judgment and domain depth on this topic.';
+    let expertReason = 'Consult a domain specialist to interpret qualitative nuances.';
+    let expertPrompt = `Who should I consult about ${cleanTopic}?`;
+    let expertParams = { query: cleanTopic };
+    if (specific.expert) {
+        if (isOnRequestExpert) {
+            expertTargetTool = 'request_expert_intro';
+            expertName = `Request intro to ${specific.expert.display_name}`;
+            expertDescription = 'Request an advisory introduction or consultation with this prospective Human Agent.';
+            expertReason = `Connect with ${specific.expert.display_name} for human advisory or consultation.`;
+            expertPrompt = `Request an introduction or advisory consultation with ${specific.expert.display_name} regarding ${cleanTopic}.`;
+            expertParams = { expert_id: specific.expert.analyst_id, query: cleanTopic };
+        }
+        else if (isExpertHuman) {
+            expertTargetTool = 'consult_human_agent';
+            expertName = `Consult ${specific.expert.display_name}`;
+            expertDescription = 'Consult this verified Human Agent twin for practitioner depth and proprietary frameworks.';
+            expertReason = `Consult ${specific.expert.display_name} for authoritative interpretation and practitioner depth.`;
+            expertPrompt = `Ask ${specific.expert.display_name} about ${cleanTopic}`;
+            expertParams = { analyst_id: specific.expert.analyst_id, query: `How should we evaluate the strategic opportunity and risks in ${cleanTopic}?` };
+        }
+        else {
+            expertTargetTool = specific.expert.consult_tool || 'consult_analyst';
+            expertName = `Consult ${specific.expert.display_name}`;
+            expertDescription = 'Consult this specialist analyst for domain intelligence.';
+            expertReason = `Consult ${specific.expert.display_name} for authoritative interpretation and practitioner depth.`;
+            expertPrompt = `Ask ${specific.expert.display_name} about ${cleanTopic}`;
+            expertParams = { analyst_id: specific.expert.analyst_id, query: cleanTopic };
+        }
+    }
+    const actions = [
+        {
+            action: 'pressure_test',
+            name: 'Pressure-test thesis',
+            description: 'Evaluate assertions against counter-evidence and executive divergence.',
+            reason: 'Evaluate whether findings rely on untested assumptions',
+            target_tool: 'verify_market_claim',
+            tool_display_name: 'Market Claim Verifier',
+            suggested_prompt: `Pressure-test whether the market momentum around ${cleanTopic} holds up against counter-evidence.`,
+            suggested_parameters: { claim: `Pressure-test whether ${cleanTopic} strategy and market momentum holds up` },
+            available: true,
+        },
+        {
+            action: 'ask_expert',
+            name: expertName,
+            description: expertDescription,
+            reason: expertReason,
+            target_tool: expertTargetTool,
+            suggested_prompt: expertPrompt,
+            suggested_parameters: expertParams,
+            available: true,
+        },
+        {
+            action: 'create_brief',
+            name: 'Commission executive brief',
+            description: 'Turn this intelligence into a finished strategic deliverable.',
+            reason: `Package verified evidence, quantitative statistics, and executive quotes on ${cleanTopic} into a deliverable.`,
+            target_tool: 'request_deliverable',
+            suggested_prompt: `Commission an executive brief on ${cleanTopic}`,
+            suggested_parameters: { skill_slug: 'research_brief', brief: `Synthesize verified findings, market metrics, and strategic implications for ${cleanTopic}` },
+            available: true,
+        },
+        {
+            action: 'track_topic',
+            name: 'Track topic shifts',
+            description: 'Establish automated weekly monitoring on this subject.',
+            reason: `Detect newly emerging signals, shifts in executive tone, and trend momentum on ${cleanTopic} weekly.`,
+            target_tool: 'manage_scheduled_reports',
+            suggested_prompt: `Set up weekly tracking on ${cleanTopic}`,
+            suggested_parameters: { action: 'create', topic: cleanTopic, cadence: 'weekly' },
+            available: true,
+        },
+    ];
+    nextMoves.actions = actions;
+    return nextMoves;
+}
+/**
+ * Generate consult-specific next moves envelope adhering to Render Spec 1.3.
+ *
+ * Sentence 1 (Thread): Expert's 1st-person next move (using expert_thread.next_angle,
+ *   with fallback to uncited themes / remaining count; out-of-lane declination uses top referral).
+ * Sentence 2 (Shelf): Fodda platform merchandising via catalogCache.getRelevantGraphs()
+ *   (strictly excluding the expert's own graph).
+ * Sentence 3 (Scope): Deliverable / project scope line.
+ */
+export function generateConsultNextMoves(result, query, analystId, options, catalog = getGraphs(), analysts = getAnalysts()) {
+    const nextMoves = {
+        scope_prompt: true,
+        presentation: 'internal',
+    };
+    if (options?.knownBrand) {
+        nextMoves.known_brand = options.knownBrand;
+    }
+    const cleanAnalystId = (analystId || '').toLowerCase().trim();
+    const matchedAnalyst = analysts.find(a => {
+        const aId = (a.analyst_id || a.id || a.slug || '').toLowerCase().trim();
+        const aName = (a.name || '').toLowerCase().trim();
+        return aId === cleanAnalystId || aName === cleanAnalystId;
+    });
+    const expertDisplayName = matchedAnalyst?.name || analystId;
+    const expertGraphId = matchedAnalyst?.analyst_id || analystId;
+    const expertThread = result?.expert_thread || {};
+    // Read next_angle strictly from expert_thread.next_angle per §2.A.5
+    const nextAngleRaw = expertThread?.next_angle;
+    const uncitedThemes = Array.isArray(expertThread?.uncited_themes) ? expertThread.uncited_themes : [];
+    const coverage = (result?.coverage || 'ok').toLowerCase().trim();
+    const isOutOfLane = coverage === 'out' || expertThread?.on_topic_total === 0;
+    // ── Sentence 1: Thread (Expert's 1st Person / Referral on decline) ──
+    let threadSentence = '';
+    if (isOutOfLane) {
+        const activeReferrals = Array.isArray(result?.referrals)
+            ? result.referrals.filter((r) => {
+                const rStatus = (r.status || r.Status || '').toLowerCase().trim();
+                return !rStatus || rStatus === 'active';
+            })
+            : [];
+        if (activeReferrals.length > 0) {
+            const topRef = activeReferrals[0];
+            const refName = topRef.name || topRef.curator || 'another expert';
+            const refReason = topRef.reason ? `who covers ${topRef.reason}` : 'who covers this topic directly';
+            threadSentence = `For inquiries on this topic, I'd recommend connecting with ${refName} ${refReason}.`;
+            nextMoves.thread = {
+                kind: 'adjacent_room',
+                graph_id: topRef.id || topRef.analyst_id || topRef.slug,
+                graph_display: refName,
+                adjacent: {
+                    graph_id: topRef.id || topRef.analyst_id || topRef.slug,
+                    graph_display: refName,
+                    reason: topRef.reason || 'related expertise',
+                },
+                text: threadSentence,
+            };
+        }
+        else {
+            threadSentence = `That's what Fodda holds on this right now; if you have a related topic in my graph, let me know.`;
+            nextMoves.thread = {
+                kind: 'honest_thin',
+                graph_id: expertGraphId,
+                graph_display: expertDisplayName,
+                text: threadSentence,
+            };
+        }
+    }
+    else {
+        // Next angle token check per §2.A.5: must share >=1 content token (>=3 chars) with sources_used, uncited_themes, query, or expert topics
+        let nextAngleValid = false;
+        if (typeof nextAngleRaw === 'string' && nextAngleRaw.trim().length > 0) {
+            const angleTokens = specificQueryTokens(nextAngleRaw);
+            const sourceTitles = (result?.sources_used || [])
+                .filter((s) => s.origin !== 'profile' && !(s.title || '').includes('Official Profile'))
+                .map((s) => (s.title || s.name || '').toLowerCase());
+            const themeTexts = uncitedThemes.map((t) => t.toLowerCase());
+            const expertTopics = Array.isArray(matchedAnalyst?.topics) ? matchedAnalyst.topics.join(' ').toLowerCase() : '';
+            const groundingCorpus = [...sourceTitles, ...themeTexts, expertTopics, query.toLowerCase()].join(' ');
+            const hasSharedToken = angleTokens.some(tok => tok.length >= 3 && groundingCorpus.includes(tok));
+            if (hasSharedToken || (sourceTitles.length === 0 && themeTexts.length === 0)) {
+                nextAngleValid = true;
+            }
+        }
+        if (nextAngleValid && typeof nextAngleRaw === 'string') {
+            let cleanNextAngle = nextAngleRaw.trim();
+            if (!/[.!?]$/.test(cleanNextAngle)) {
+                cleanNextAngle += '.';
+            }
+            threadSentence = cleanNextAngle;
+            nextMoves.thread = {
+                kind: 'expert_thread',
+                graph_id: expertGraphId,
+                graph_display: expertDisplayName,
+                next_angle: cleanNextAngle,
+                text: threadSentence,
+            };
+        }
+        else if (uncitedThemes.length > 0) {
+            const topTheme = uncitedThemes[0];
+            threadSentence = `If you want to stay on this, we can look into ${topTheme} in my graph.`;
+            nextMoves.thread = {
+                kind: 'expert_thread',
+                graph_id: expertGraphId,
+                graph_display: expertDisplayName,
+                theme: topTheme,
+                uncited_themes: uncitedThemes,
+                text: threadSentence,
+            };
+        }
+        else {
+            const onTopicTotal = typeof expertThread?.on_topic_total === 'number' ? expertThread.on_topic_total : undefined;
+            const citedCount = typeof expertThread?.cited_count === 'number' ? expertThread.cited_count : (Array.isArray(result?.sources_used) ? result.sources_used.length : 0);
+            let remainder = (onTopicTotal !== undefined && onTopicTotal > citedCount) ? (onTopicTotal - citedCount) : 0;
+            if (remainder >= 10) {
+                threadSentence = `There are many more trends in my graph exploring this topic — want me to pull those?`;
+            }
+            else if (remainder > 0) {
+                threadSentence = `There are several more trends in my graph exploring this topic — want me to pull those?`;
+            }
+            else {
+                threadSentence = `If you want to stay on this, we can explore deeper signals in my graph.`;
+            }
+            nextMoves.thread = {
+                kind: 'expert_thread',
+                graph_id: expertGraphId,
+                graph_display: expertDisplayName,
+                remaining_count: remainder > 0 ? remainder : undefined,
+                text: threadSentence,
+            };
+        }
+    }
+    // ── Sentence 2: Shelf (Platform Voice Merchandising) ──
+    let relevantCandidates = [];
+    try {
+        relevantCandidates = getRelevantGraphs(query);
+    }
+    catch {
+        relevantCandidates = [];
+    }
+    const expertOwnIds = new Set([cleanAnalystId, expertGraphId.toLowerCase()]);
+    if (matchedAnalyst) {
+        if (matchedAnalyst.analyst_id)
+            expertOwnIds.add(matchedAnalyst.analyst_id.toLowerCase());
+        if (matchedAnalyst.id)
+            expertOwnIds.add(String(matchedAnalyst.id).toLowerCase());
+        if (matchedAnalyst.slug)
+            expertOwnIds.add(String(matchedAnalyst.slug).toLowerCase());
+    }
+    const SHELF_RELEVANCE_FLOOR = 0.50;
+    const queryTokens = specificQueryTokens(query);
+    const shelfCandidateGraphs = [];
+    for (const cand of relevantCandidates) {
+        if ((cand.score ?? 0) < SHELF_RELEVANCE_FLOOR)
+            continue;
+        const g = cand.graph;
+        if (!g)
+            continue;
+        const gid = (g.graph_id || g.id || '').toLowerCase();
+        if (expertOwnIds.has(gid))
+            continue;
+        if (g.curator && g.curator.toLowerCase() === expertDisplayName.toLowerCase())
+            continue;
+        if (g.name && g.name.toLowerCase() === expertDisplayName.toLowerCase())
+            continue;
+        // Shelf on an expert consult must only suggest published research/trend graphs (report, domain),
+        // never other individual expert agents or classic historical figures.
+        const gType = (g.graph_type || '').toLowerCase();
+        if (gType === 'expert' || gType === 'analyst' || cand.graphTier === 'static_expert' || cand.graphTier === 'living') {
+            continue;
+        }
+        // Must match at least 2 distinct domain tokens from the query, or have a direct topic match
+        let tokenMatchCount = 0;
+        if (queryTokens.length > 0) {
+            const graphText = `${g.name || ''} ${g.domain || ''} ${(Array.isArray(g.topics) ? g.topics : []).join(' ')} ${g.headline || ''} ${g.one_liner || ''} ${g.description || ''}`.toLowerCase();
+            const words = new Set(graphText.split(/[^a-z0-9]+/));
+            for (const t of queryTokens) {
+                if (t.length >= 3 && words.has(t)) {
+                    tokenMatchCount++;
+                }
+            }
+        }
+        const minMatchesNeeded = queryTokens.length >= 2 ? 2 : 1;
+        if (tokenMatchCount < minMatchesNeeded)
+            continue;
+        if (shelfCandidateGraphs.length < 2 && !shelfCandidateGraphs.some(sg => sg.graph_id === g.graph_id)) {
+            shelfCandidateGraphs.push(g);
+        }
+    }
+    let shelfSentence = '';
+    const hasDeliverableOffering = Array.isArray(matchedAnalyst?.offerings) && matchedAnalyst.offerings.length > 0;
+    if (shelfCandidateGraphs.length > 0) {
+        const shelfGraphs = shelfCandidateGraphs.map(g => ({
+            graph_id: g.graph_id,
+            graph_display: buildDisplayName(g),
+            domain: g.domain,
+            headline: g.headline,
+            reason: g.headline || g.domain || g.name,
+        }));
+        nextMoves.shelf = shelfGraphs;
+        if (shelfGraphs.length >= 2 && shelfGraphs[0]?.graph_display && shelfGraphs[1]?.graph_display) {
+            shelfSentence = `Fodda also holds trend signals on this in ${shelfGraphs[0].graph_display} and ${shelfGraphs[1].graph_display} if you want the wider picture`;
+        }
+        else if (shelfGraphs.length >= 1 && shelfGraphs[0]?.graph_display) {
+            shelfSentence = `Fodda also holds trend signals on this in ${shelfGraphs[0].graph_display} if you want the wider picture`;
+        }
+        if (hasDeliverableOffering) {
+            shelfSentence += `, and ${expertDisplayName} takes scoped briefs on this if you need a deliverable.`;
+        }
+        else {
+            shelfSentence += `.`;
+        }
+    }
+    else if (hasDeliverableOffering) {
+        shelfSentence = `${expertDisplayName} takes scoped briefs on this if you need a deliverable.`;
+        nextMoves.shelf = undefined;
+    }
+    else {
+        // Empty candidate list and no deliverable offerings — omit sentence 2 per Brief 1.46.29
+        shelfSentence = '';
+        nextMoves.shelf = undefined;
+    }
+    const specific = {};
+    if (nextMoves.shelf && nextMoves.shelf.length > 0) {
+        specific.shelf_graphs = nextMoves.shelf;
+    }
+    if (Array.isArray(expertThread?.brands) && expertThread.brands.length > 0) {
+        specific.brands = expertThread.brands.slice(0, 2);
+    }
+    if (Array.isArray(result?.referrals) && result.referrals.length > 0) {
+        const topRef = result.referrals[0];
+        specific.expert = {
+            analyst_id: topRef.id || topRef.analyst_id || topRef.slug,
+            display_name: cleanDisplayName(topRef.name || topRef.curator),
+            reason: topRef.reason || 'related expertise',
+        };
+    }
+    if (Object.keys(specific).length > 0) {
+        nextMoves.specific = specific;
+    }
+    // ── Sentence 3: Scope (Platform Voice, Render Spec 1.2 Copy) ──
+    let scopeSentence = '';
+    if (options?.knownBrand) {
+        scopeSentence = `Want this cut to ${options.knownBrand} specifically?`;
+    }
+    else {
+        scopeSentence = `If you tell me the brand or brief you're working on, I'll cut this to that.`;
+    }
+    nextMoves.scope = scopeSentence;
+    nextMoves.consult_envelope = {
+        thread_line: threadSentence,
+        shelf_line: shelfSentence || undefined,
+        scope_line: scopeSentence,
+    };
+    const consultActions = [
+        {
+            action: 'pressure_test',
+            name: 'Pressure-test perspective',
+            description: "Verify expert assertions and claims against broader market data.",
+            reason: `Verify ${expertDisplayName}'s perspective against empirical market evidence and executive divergence.`,
+            target_tool: 'verify_market_claim',
+            tool_display_name: 'Market Claim Verifier',
+            suggested_prompt: `Pressure-test ${expertDisplayName}'s perspective on ${query.trim()}`,
+            suggested_parameters: { claim: `Pressure-test ${expertDisplayName}'s thesis and assertions on ${query.trim()}` },
+            available: true,
+        },
+        {
+            action: 'create_brief',
+            name: 'Commission deliverable',
+            description: `Commission a finished deliverable from ${expertDisplayName}.`,
+            reason: `Turn ${expertDisplayName}'s insights and framework into a formatted deliverable.`,
+            target_tool: 'request_deliverable',
+            suggested_prompt: `Commission a strategic briefing from ${expertDisplayName} on ${query.trim()}`,
+            suggested_parameters: { analyst_id: cleanAnalystId || expertGraphId, skill_slug: 'research_brief', brief: `Strategic brief incorporating ${expertDisplayName}'s framework on ${query.trim()}` },
+            available: true,
+        },
+        {
+            action: 'track_topic',
+            name: 'Track topic shifts',
+            description: 'Establish automated weekly monitoring on this subject.',
+            reason: `Monitor new signals and developments in ${expertDisplayName}'s coverage area.`,
+            target_tool: 'manage_scheduled_reports',
+            suggested_prompt: `Set up weekly tracking on ${query.trim()}`,
+            suggested_parameters: { action: 'create', topic: query.trim(), cadence: 'weekly' },
+            available: true,
+        },
+    ];
+    nextMoves.actions = consultActions;
+    return nextMoves;
+}
+/**
+ * Render the consult 3-sentence closing envelope complying with Render Spec 1.3.
+ */
+export function renderConsultClosingEnvelope(nextMoves) {
+    if (!nextMoves?.consult_envelope) {
+        return renderClosingBlock(nextMoves);
+    }
+    const { thread_line, shelf_line, scope_line } = nextMoves.consult_envelope;
+    const lines = [thread_line, shelf_line, scope_line].filter((l) => Boolean(l));
+    return {
+        lines,
+        text: lines.join(' '),
+    };
+}
+/**
+ * Universal closing block renderer supporting both general research (Render Spec 1.2/1.3)
+ * and consult-specific responses (Render Spec 1.3).
+ */
+export function renderClosingBlock(nextMoves) {
+    if (!nextMoves)
+        return { lines: [], text: '' };
+    if (nextMoves.consult_envelope) {
+        const { thread_line, shelf_line, scope_line } = nextMoves.consult_envelope;
+        const lines = [thread_line, shelf_line, scope_line].filter((l) => Boolean(l));
+        return {
+            lines,
+            text: lines.join(' '),
+        };
+    }
+    const lines = [];
+    // Line 1: Pull the thread
+    if (nextMoves.thread) {
+        const t = nextMoves.thread;
+        if (t.text) {
+            lines.push(t.text);
+        }
+        else if (t.kind === 'more_in_graph' && t.remaining_count && t.remaining_count > 0) {
+            const countPhrase = t.remaining_count >= 10 ? 'many more trends' : 'several more trends';
+            lines.push(`There are ${countPhrase} in ${t.graph_display || 'the graph'} exploring ${t.theme || 'this topic'} — want me to pull those?`);
+        }
+        else if (t.kind === 'adjacent_room' && t.adjacent) {
+            lines.push(`We also have related coverage in ${t.adjacent.graph_display} — want me to pull that?`);
+        }
+        else if (t.kind === 'honest_thin' && t.adjacent) {
+            lines.push(`That's what Fodda holds on this right now; the closest adjacent hit is ${t.adjacent.reason || 'related research'} in ${t.adjacent.graph_display} — want it?`);
+        }
+    }
+    // Line 2: Go specific
+    if (nextMoves.specific) {
+        const s = nextMoves.specific;
+        const options = [];
+        if (s.brands && s.brands.length > 0) {
+            options.push(`look into ${s.brands.join(' or ')}`);
+        }
+        if (s.statistics_source) {
+            options.push(`pull quantitative data from ${s.statistics_source}`);
+        }
+        if (s.expert && options.length < 2) {
+            options.push(`consult ${s.expert.display_name}`);
+        }
+        if (options.length > 0) {
+            lines.push(`Or we can ${options.slice(0, 2).join(' or ')}.`);
+        }
+    }
+    // Line 3: Scope to the job
+    if (nextMoves.known_brand) {
+        lines.push(`Want this cut to ${nextMoves.known_brand} specifically?`);
+    }
+    else {
+        lines.push(`If you tell me the brand or brief you're working on, I'll cut this to that.`);
+    }
+    return { lines, text: lines.join(' ') };
+}
+//# sourceMappingURL=coverageRelevance.js.map