ebay-mcp-remote-edition 4.0.0 → 4.1.0

package/README.md

@@ -626,7 +626,7 @@ Provider behavior:
 - **Authenticated research session source:** [`src/validation/providers/ebay-research.ts`](src/validation/providers/ebay-research.ts) can source eBay Research authentication from cookie JSON, persisted KV-backed session state, Playwright storage state, or a browser profile directory. Parsed ACTIVE and SOLD tab responses are cached, but automatically invalidated when the authenticated cookie fingerprint changes.
 - **Social provider:** [`src/validation/providers/social.ts`](src/validation/providers/social.ts) supports phase-1 Twitter/X recent activity, YouTube average-daily-views proxy data exposed through the `youtubeViews24hMillions` field, and Reddit recent post counts. These signals degrade gracefully on provider/API failure and are used as supportive indicators rather than authoritative demand truth.
 - **Chart provider:** [`src/validation/providers/chart.ts`](src/validation/providers/chart.ts) is still a stub and does not currently contribute chart-based metrics.
-- **Previous comeback research provider:** [`src/validation/providers/research.ts`](src/validation/providers/research.ts) is currently a stable placeholder contract for orchestration-side historical research. It returns the future-facing `previousComebackFirstWeekSales` field shape, and it documents `PERPLEXITY_API_KEY` for a later external-research implementation, but it does not yet perform live historical lookup.
+- **Previous comeback research provider:** [`src/validation/providers/research.ts`](src/validation/providers/research.ts) now performs Perplexity-backed historical research when `PERPLEXITY_API_KEY` is configured. It attempts to resolve the prior comeback, normalize previous first-week sales when support exists, assign a `perplexityHistoricalContextScore`, generate concise `historicalContextNotes`, and emit debug diagnostics covering the research query, citations/snippets, resolved prior release, confidence, and score reasoning.
 
 Recommendation behavior:
 
@@ -641,7 +641,7 @@ Known limitations in the current implementation:
 - If those sold-data variables are missing, validation still runs but sold enrichment degrades to an unavailable/error state rather than providing full historical-sales signals.
 - The sold-data provider is temporary and intended to be replaced by an internal implementation later.
 - Authenticated eBay Research requires a valid session source such as `EBAY_RESEARCH_COOKIES_JSON`, a persisted KV session, Playwright storage state, or a browser profile directory; without one, the provider degrades to diagnostic-only output.
-- The previous-comeback research provider contract is present, but no live historical inference or Perplexity-backed lookup is implemented yet even when `PERPLEXITY_API_KEY` is configured.
+- The previous-comeback research provider depends on grounded external research and therefore degrades to low-confidence notes with a zero historical score when `PERPLEXITY_API_KEY` is missing, the response cannot be normalized, or reliable evidence is not found.
 - The browse provider still relies on heuristic query selection and fallback matching.
 - The YouTube-backed `youtubeViews24hMillions` field is currently an **average daily views proxy**, not a true trailing 24-hour delta.
 - Social signals are supportive/proxy data only and should not be presented as decisive automated buy logic.

package/build/validation/providers/research.js

@@ -1,16 +1,497 @@
 import { getValidationEffectiveContext } from '../effective-context.js';
-export async function getPreviousComebackResearchSignals(request) {
-    await Promise.resolve();
-    const hasPerplexityKey = (process.env.PERPLEXITY_API_KEY ?? '').trim().length > 0;
+function sanitizeText(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function uniqueStrings(values, max = 6) {
+    const normalized = values
+        .map((value) => sanitizeText(value))
+        .filter((value) => value !== null);
+    return Array.from(new Set(normalized)).slice(0, max);
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+function truncateText(value, maxLength) {
+    return value.length <= maxLength ? value : `${value.slice(0, maxLength - 1).trimEnd()}…`;
+}
+function detectResearchSubtype(request) {
     const effectiveContext = getValidationEffectiveContext(request);
-    const primaryAlbum = effectiveContext.searchAlbum ?? effectiveContext.searchEvent ?? effectiveContext.searchItem;
+    if (effectiveContext.sourceType === 'event') {
+        return 'event';
+    }
+    const combined = [
+        request.validation.validationType,
+        request.validation.queryContext?.validationScope,
+        request.validation.queryContext?.queryScope,
+    ]
+        .map((value) => sanitizeText(value)?.toLowerCase() ?? '')
+        .join(' ');
+    if (/\bpob\b|benefit|photocard/.test(combined)) {
+        return 'pob';
+    }
+    if (/pre\s*order|preorder/.test(combined)) {
+        return 'preorder';
+    }
+    if (combined.includes('album')) {
+        return 'album';
+    }
+    return 'general';
+}
+function buildResearchQuery(request) {
+    const effectiveContext = getValidationEffectiveContext(request);
+    const parts = effectiveContext.sourceType === 'event'
+        ? [
+            effectiveContext.searchArtist,
+            effectiveContext.searchEvent,
+            effectiveContext.searchItem,
+            effectiveContext.searchLocation,
+        ]
+        : [effectiveContext.searchArtist, effectiveContext.searchAlbum, effectiveContext.searchItem];
+    return uniqueStrings(parts, 8).join(' ');
+}
+function buildPromptFocus(subtype) {
+    switch (subtype) {
+        case 'pob':
+            return [
+                'identify the most likely previous comeback or prior comparable release',
+                'look for collector, POB, or preorder demand commentary from the prior cycle',
+                'note whether prior demand was strong enough to support current collector-focused monitoring',
+            ];
+        case 'preorder':
+            return [
+                'identify the most likely previous comeback or prior comparable release',
+                'look for prior preorder momentum and collector demand signals',
+                'summarize whether earlier release performance supports current preorder confidence',
+            ];
+        case 'event':
+            return [
+                'identify the closest prior comparable release or event context',
+                'summarize prior demand continuity and historical commercial strength',
+                'call out ambiguities so live market data can be weighted appropriately',
+            ];
+        case 'album':
+            return [
+                'identify the immediately previous comeback or album release',
+                'find previous first-week sales where support exists',
+                'summarize prior release momentum and demand continuity for album tracking',
+            ];
+        default:
+            return [
+                'identify the best prior comparable release if one exists',
+                'summarize commercial strength and demand continuity',
+                'flag ambiguity when evidence is weak or mixed',
+            ];
+    }
+}
+function buildPerplexityPrompt(request) {
+    const effectiveContext = getValidationEffectiveContext(request);
+    const subtype = detectResearchSubtype(request);
+    const query = buildResearchQuery(request);
+    const promptFocus = buildPromptFocus(subtype);
+    const subjectLabel = effectiveContext.sourceType === 'event'
+        ? (effectiveContext.searchEvent ?? effectiveContext.searchItem ?? 'event context')
+        : (effectiveContext.searchAlbum ?? effectiveContext.searchItem ?? request.item.name);
+    const userPrompt = [
+        'Research the historical commercial context for the following release or validation target.',
+        `Primary query: ${query || subjectLabel}`,
+        `Artist: ${effectiveContext.searchArtist ?? 'Unknown'}`,
+        `Subject: ${subjectLabel}`,
+        `Release date: ${effectiveContext.eventDate ?? 'Unknown'}`,
+        `Validation type: ${request.validation.validationType}`,
+        `Subtype: ${subtype}`,
+        `Focus requirements: ${promptFocus.join('; ')}`,
+        'Return JSON only with this exact shape:',
+        '{',
+        '  "previousAlbumTitle": string | null,',
+        '  "previousComebackFirstWeekSales": number | string | null,',
+        '  "historicalContextNotes": string,',
+        '  "researchConfidence": "Low" | "Medium" | "High",',
+        '  "commercialStrengthContext": string | null,',
+        '  "collectorDemandContext": string | null,',
+        '  "preorderDemandContext": string | null,',
+        '  "sourceSnippets": string[],',
+        '  "ambiguities": string[],',
+        '  "confidenceReason": string | null,',
+        '  "scoreReason": string | null,',
+        '  "notEnoughEvidence": boolean',
+        '}',
+        'Guidance:',
+        '- Prefer factual prior-release context and first-week sales if supported.',
+        '- For POB or preorder cases, emphasize prior collector/preorder demand momentum.',
+        '- If evidence is uncertain, use nulls, concise ambiguity notes, and lower confidence.',
+        '- Keep historicalContextNotes concise and operational for Airtable.',
+    ].join('\n');
+    return { query, promptFocus, userPrompt };
+}
+function extractFirstJsonObject(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        return null;
+    }
+    const fencedMatch = /```(?:json)?\s*([\s\S]*?)```/i.exec(trimmed);
+    const candidate = fencedMatch?.[1]?.trim() ?? trimmed;
+    const firstBrace = candidate.indexOf('{');
+    if (firstBrace === -1) {
+        return null;
+    }
+    let depth = 0;
+    let inString = false;
+    let isEscaped = false;
+    for (let index = firstBrace; index < candidate.length; index += 1) {
+        const character = candidate[index];
+        if (inString) {
+            if (isEscaped) {
+                isEscaped = false;
+            }
+            else if (character === '\\') {
+                isEscaped = true;
+            }
+            else if (character === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (character === '"') {
+            inString = true;
+            continue;
+        }
+        if (character === '{') {
+            depth += 1;
+        }
+        else if (character === '}') {
+            depth -= 1;
+            if (depth === 0) {
+                return candidate.slice(firstBrace, index + 1);
+            }
+        }
+    }
+    return null;
+}
+function parseResearchResponse(rawContent) {
+    const jsonObject = extractFirstJsonObject(rawContent);
+    if (jsonObject === null) {
+        return null;
+    }
+    try {
+        return JSON.parse(jsonObject);
+    }
+    catch {
+        return null;
+    }
+}
+function parseNormalizedSalesValue(amount, unit) {
+    const numericPortion = Number(amount);
+    if (!Number.isFinite(numericPortion) || numericPortion <= 0) {
+        return null;
+    }
+    const normalizedUnit = unit?.toLowerCase() ?? null;
+    const multiplier = normalizedUnit === 'm' || normalizedUnit === 'million'
+        ? 1_000_000
+        : normalizedUnit === 'k' || normalizedUnit === 'thousand'
+            ? 1_000
+            : 1;
+    return Math.round(numericPortion * multiplier);
+}
+function parseSalesFigure(value) {
+    if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+        return Math.round(value);
+    }
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const normalized = value.trim().toLowerCase().replace(/,/g, '');
+    if (normalized.length === 0) {
+        return null;
+    }
+    if (/^\d+(?:\.\d+)?$/.test(normalized)) {
+        return parseNormalizedSalesValue(normalized);
+    }
+    const directSalesLike = /^(?:~|about|approximately|approx\.?|around|over|under|nearly|more than|at least)?\s*(\d+(?:\.\d+)?)\s*(m|million|k|thousand)?\s*(copies|albums|units|sales|sold)?\s*$/i.exec(normalized);
+    if (directSalesLike !== null && (directSalesLike[2] || directSalesLike[3])) {
+        return parseNormalizedSalesValue(directSalesLike[1], directSalesLike[2]);
+    }
+    const numericTokens = Array.from(normalized.matchAll(/\d+(?:\.\d+)?/g)).length;
+    if (numericTokens !== 1) {
+        return null;
+    }
+    const contextualSalesLike = /(?:first[-\s]?week(?:\s+\w+){0,3}\s+sales|first[-\s]?week|sales|sold|copies|albums|units)[^\d]{0,24}(\d+(?:\.\d+)?)\s*(m|million|k|thousand)?\b/i.exec(normalized);
+    if (contextualSalesLike === null) {
+        return null;
+    }
+    return parseNormalizedSalesValue(contextualSalesLike[1], contextualSalesLike[2]);
+}
+function normalizeConfidence(value, hasSubstantiveEvidence) {
+    if (!hasSubstantiveEvidence) {
+        return 'Low';
+    }
+    if (typeof value === 'string') {
+        const normalized = value.trim().toLowerCase();
+        if (normalized === 'high') {
+            return 'High';
+        }
+        if (normalized === 'medium') {
+            return 'Medium';
+        }
+        if (normalized === 'low') {
+            return 'Low';
+        }
+    }
+    return 'Medium';
+}
+function buildHistoricalNotes(parsed, subtype) {
+    const explicitNotes = sanitizeText(parsed.historicalContextNotes);
+    if (explicitNotes !== null) {
+        return truncateText(explicitNotes, 320);
+    }
+    const parts = [
+        sanitizeText(parsed.previousAlbumTitle)
+            ? `Previous release identified as ${sanitizeText(parsed.previousAlbumTitle)}.`
+            : null,
+        parseSalesFigure(parsed.previousComebackFirstWeekSales)
+            ? `Reported first-week sales were approximately ${parseSalesFigure(parsed.previousComebackFirstWeekSales)}.`
+            : null,
+        sanitizeText(parsed.commercialStrengthContext),
+        subtype === 'pob' || subtype === 'preorder'
+            ? (sanitizeText(parsed.preorderDemandContext) ?? sanitizeText(parsed.collectorDemandContext))
+            : sanitizeText(parsed.collectorDemandContext),
+        sanitizeText(parsed.ambiguities?.[0]),
+    ];
+    const joined = uniqueStrings(parts, 5).join(' ');
+    return joined.length > 0
+        ? truncateText(joined, 320)
+        : 'Limited prior-market evidence found. Context weak; rely more on live market signals.';
+}
+function computeHistoricalContextScore(input) {
+    const hasSubstantiveEvidence = input.previousAlbumTitle !== null ||
+        input.previousComebackFirstWeekSales !== null ||
+        input.demandContextPresent;
+    if (!hasSubstantiveEvidence) {
+        return 0;
+    }
+    if (input.notEnoughEvidence &&
+        input.previousAlbumTitle === null &&
+        input.previousComebackFirstWeekSales === null &&
+        !input.demandContextPresent) {
+        return 0;
+    }
+    let score = 0;
+    if (input.previousAlbumTitle !== null) {
+        score += 6;
+    }
+    if (input.previousComebackFirstWeekSales !== null) {
+        score += 6;
+    }
+    if (input.demandContextPresent) {
+        score += 4;
+    }
+    if (input.snippetCount >= 2) {
+        score += 2;
+    }
+    if (input.snippetCount >= 3) {
+        score += 2;
+    }
+    if (score === 0) {
+        return 0;
+    }
+    if (input.confidence === 'High') {
+        return clamp(Math.max(score, 15), 15, 20);
+    }
+    if (input.confidence === 'Medium') {
+        return clamp(Math.max(score, 8), 8, 14);
+    }
+    return clamp(Math.max(score, 1), 1, 7);
+}
+function buildScoreAssignmentReason(input) {
+    const factors = [
+        input.previousAlbumTitle !== null ? 'resolved prior release' : null,
+        input.previousComebackFirstWeekSales !== null ? 'supported first-week sales' : null,
+        input.demandContextPresent ? 'collector/preorder demand context' : null,
+        input.snippetCount > 0
+            ? `${input.snippetCount} supporting snippet${input.snippetCount === 1 ? '' : 's'}`
+            : null,
+    ].filter((value) => value !== null);
+    const defaultReason = factors.length > 0
+        ? `${input.confidence} confidence based on ${factors.join(', ')}; assigned normalized historical score ${input.score}.`
+        : `No reliable historical evidence was normalized, so the historical score remained ${input.score}.`;
+    const parsedReason = sanitizeText(input.parsedScoreReason);
+    return parsedReason !== null ? truncateText(parsedReason, 240) : defaultReason;
+}
+function buildFallbackResearchSignals(input) {
+    const confidence = input.confidence ?? 'Low';
+    const historicalContextNotes = truncateText(input.notes, 320);
     return {
         previousAlbumTitle: null,
         previousComebackFirstWeekSales: null,
-        confidence: 'Low',
-        notes: hasPerplexityKey
-            ? `Research provider contract is ready, but historical comeback lookup for ${primaryAlbum ?? 'this release'} is not implemented yet.`
-            : 'Research provider contract is ready, but PERPLEXITY_API_KEY is not configured and historical comeback lookup is not implemented yet.',
+        perplexityHistoricalContextScore: 0,
+        historicalContextNotes,
+        confidence,
+        notes: historicalContextNotes,
         sources: [],
+        debug: {
+            providerStatus: input.providerStatus,
+            parseStatus: input.parseStatus,
+            query: input.query ?? null,
+            promptFocus: input.promptFocus ?? [],
+            citations: [],
+            sourceSnippets: [],
+            resolvedPriorRelease: null,
+            extractedConfidence: null,
+            computedConfidence: confidence,
+            confidenceReason: null,
+            scoreAssignmentReason: input.providerStatus === 'error'
+                ? 'Historical research request failed, so the provider returned a zero historical score.'
+                : 'Historical research did not yield structured evidence, so the provider returned a zero historical score.',
+            rawResponseText: input.rawResponseText ?? null,
+            errorMessage: input.errorMessage ?? null,
+        },
     };
 }
+export async function getPreviousComebackResearchSignals(request) {
+    const hasPerplexityKey = (process.env.PERPLEXITY_API_KEY ?? '').trim().length > 0;
+    const effectiveContext = getValidationEffectiveContext(request);
+    const primaryAlbum = effectiveContext.searchAlbum ?? effectiveContext.searchEvent ?? effectiveContext.searchItem;
+    const { query, promptFocus, userPrompt } = buildPerplexityPrompt(request);
+    if (!hasPerplexityKey) {
+        return buildFallbackResearchSignals({
+            notes: `PERPLEXITY_API_KEY is not configured. Historical context for ${primaryAlbum ?? 'this release'} remains unverified; rely more on live market signals.`,
+            providerStatus: 'unconfigured',
+            parseStatus: 'unconfigured',
+            query,
+            promptFocus,
+        });
+    }
+    if (query.length === 0) {
+        return buildFallbackResearchSignals({
+            notes: 'Historical research query could not be derived from the current validation context.',
+            providerStatus: 'no_evidence',
+            parseStatus: 'fallback',
+            query: null,
+            promptFocus,
+        });
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 30_000);
+    try {
+        const response = await fetch('https://api.perplexity.ai/chat/completions', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${process.env.PERPLEXITY_API_KEY ?? ''}`,
+            },
+            body: JSON.stringify({
+                model: 'sonar',
+                temperature: 0.1,
+                max_tokens: 900,
+                messages: [
+                    {
+                        role: 'system',
+                        content: 'You are a historical music market research assistant. Use grounded web research, stay cautious with ambiguous evidence, and return JSON only.',
+                    },
+                    {
+                        role: 'user',
+                        content: userPrompt,
+                    },
+                ],
+            }),
+            signal: controller.signal,
+        });
+        const responseText = await response.text();
+        if (!response.ok) {
+            return buildFallbackResearchSignals({
+                notes: `Perplexity historical research request failed for ${primaryAlbum ?? 'this release'}.`,
+                providerStatus: 'error',
+                parseStatus: 'error',
+                query,
+                promptFocus,
+                rawResponseText: responseText,
+                errorMessage: `HTTP ${response.status}`,
+            });
+        }
+        const parsedResponse = JSON.parse(responseText);
+        const rawContent = parsedResponse.choices?.[0]?.message?.content?.trim() ?? '';
+        const parsed = parseResearchResponse(rawContent);
+        if (parsed === null) {
+            return buildFallbackResearchSignals({
+                notes: `Perplexity returned an unstructured historical response for ${primaryAlbum ?? 'this release'}, so live market signals should carry more weight.`,
+                providerStatus: 'error',
+                parseStatus: 'error',
+                query,
+                promptFocus,
+                rawResponseText: rawContent,
+                errorMessage: 'Unable to normalize Perplexity response into structured JSON.',
+            });
+        }
+        const previousAlbumTitle = sanitizeText(parsed.previousAlbumTitle);
+        const previousComebackFirstWeekSales = parseSalesFigure(parsed.previousComebackFirstWeekSales);
+        const demandContextPresent = sanitizeText(parsed.commercialStrengthContext) !== null ||
+            sanitizeText(parsed.collectorDemandContext) !== null ||
+            sanitizeText(parsed.preorderDemandContext) !== null;
+        const sourceSnippets = uniqueStrings(parsed.sourceSnippets ?? [], 4);
+        const citations = uniqueStrings(parsedResponse.citations ?? [], 6);
+        const hasSubstantiveEvidence = previousAlbumTitle !== null ||
+            previousComebackFirstWeekSales !== null ||
+            demandContextPresent;
+        const confidence = normalizeConfidence(parsed.researchConfidence, hasSubstantiveEvidence);
+        const score = computeHistoricalContextScore({
+            confidence,
+            previousAlbumTitle,
+            previousComebackFirstWeekSales,
+            demandContextPresent,
+            snippetCount: sourceSnippets.length + Math.min(citations.length, 2),
+            notEnoughEvidence: parsed.notEnoughEvidence === true,
+        });
+        const historicalContextNotes = buildHistoricalNotes(parsed, detectResearchSubtype(request));
+        const scoreAssignmentReason = buildScoreAssignmentReason({
+            confidence,
+            previousAlbumTitle,
+            previousComebackFirstWeekSales,
+            demandContextPresent,
+            snippetCount: sourceSnippets.length + citations.length,
+            score,
+            parsedScoreReason: sanitizeText(parsed.scoreReason),
+        });
+        return {
+            previousAlbumTitle,
+            previousComebackFirstWeekSales,
+            perplexityHistoricalContextScore: score,
+            historicalContextNotes,
+            confidence,
+            notes: historicalContextNotes,
+            sources: citations,
+            debug: {
+                providerStatus: hasSubstantiveEvidence ? 'ok' : 'no_evidence',
+                parseStatus: 'ok',
+                query,
+                promptFocus,
+                citations,
+                sourceSnippets,
+                resolvedPriorRelease: previousAlbumTitle,
+                extractedConfidence: sanitizeText(parsed.researchConfidence)
+                    ? normalizeConfidence(parsed.researchConfidence, hasSubstantiveEvidence)
+                    : null,
+                computedConfidence: confidence,
+                confidenceReason: sanitizeText(parsed.confidenceReason),
+                scoreAssignmentReason,
+                rawResponseText: rawContent,
+                errorMessage: null,
+            },
+        };
+    }
+    catch (error) {
+        return buildFallbackResearchSignals({
+            notes: `Historical research lookup failed for ${primaryAlbum ?? 'this release'}. Context remains weak until live market data improves.`,
+            providerStatus: 'error',
+            parseStatus: 'error',
+            query,
+            promptFocus,
+            errorMessage: error instanceof Error ? error.message : String(error),
+        });
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

package/build/validation/recommendation.js

@@ -35,8 +35,15 @@ function hasUsableTrackingQuery(effectiveContext) {
     }
     return buildFallbackTrackingQuery(effectiveContext) !== null;
 }
-function resolvePreferredSoldValue(soldValue, researchValue) {
-    return soldValue ?? researchValue;
+function resolvePreferredSoldValue(researchValue, soldValue) {
+    return researchValue ?? soldValue;
+}
+function hasResearchSoldEvidence(signals) {
+    return (signals.terapeak.provider === 'ebay_research_ui' &&
+        (signals.terapeak.researchSoldPriceUsd !== null ||
+            signals.terapeak.soldListingsCount !== null ||
+            signals.terapeak.recentSoldCount7d !== null ||
+            Object.values(signals.terapeak.soldVelocity).some((value) => value !== null)));
 }
 export function buildValidationRecommendation(request, signals) {
     const dDay = request.validation.dDay;
@@ -73,9 +80,9 @@ export function buildValidationRecommendation(request, signals) {
             request.item.name ??
             'release');
     const mergedSoldVelocity = {
-        day1Sold: resolvePreferredSoldValue(signals.sold.soldVelocity.day1Sold, signals.terapeak.soldVelocity.day1Sold),
-        day2Sold: resolvePreferredSoldValue(signals.sold.soldVelocity.day2Sold, signals.terapeak.soldVelocity.day2Sold),
-        day3Sold: resolvePreferredSoldValue(signals.sold.soldVelocity.day3Sold, signals.terapeak.soldVelocity.day3Sold),
+        day1Sold: resolvePreferredSoldValue(signals.terapeak.soldVelocity.day1Sold, signals.sold.soldVelocity.day1Sold),
+        day2Sold: resolvePreferredSoldValue(signals.terapeak.soldVelocity.day2Sold, signals.sold.soldVelocity.day2Sold),
+        day3Sold: resolvePreferredSoldValue(signals.terapeak.soldVelocity.day3Sold, signals.sold.soldVelocity.day3Sold),
     };
     const recentSoldCount = [
         mergedSoldVelocity.day1Sold,
@@ -85,17 +92,19 @@ export function buildValidationRecommendation(request, signals) {
     const hasSoldProviderEvidence = signals.sold.soldMedianPriceUsd !== null ||
         signals.sold.soldResultsCount !== null ||
         Object.values(signals.sold.soldVelocity).some((value) => value !== null);
-    const hasResearchSoldEvidence = signals.terapeak.provider === 'ebay_research_ui' &&
-        (signals.terapeak.soldListingsCount !== null ||
-            signals.terapeak.recentSoldCount7d !== null ||
-            Object.values(signals.terapeak.soldVelocity).some((value) => value !== null));
-    const effectiveSoldComparablePrice = signals.sold.soldMedianPriceUsd ??
-        (hasResearchSoldEvidence ? signals.terapeak.researchSoldPriceUsd : null);
-    const effectiveSoldConfidence = hasSoldProviderEvidence
-        ? signals.sold.confidence
-        : hasResearchSoldEvidence
-            ? signals.terapeak.confidence
+    const researchSoldEvidence = hasResearchSoldEvidence(signals);
+    const effectiveSoldComparablePrice = (researchSoldEvidence ? signals.terapeak.researchSoldPriceUsd : null) ??
+        signals.sold.soldMedianPriceUsd;
+    const effectiveSoldConfidence = researchSoldEvidence
+        ? signals.terapeak.confidence
+        : hasSoldProviderEvidence
+            ? signals.sold.confidence
             : 'Low';
+    const hasUsableHistoricalResearch = signals.research.debug?.providerStatus !== undefined
+        ? signals.research.debug.providerStatus === 'ok'
+        : signals.research.previousAlbumTitle !== null ||
+            signals.research.previousComebackFirstWeekSales !== null ||
+            signals.research.perplexityHistoricalContextScore > 0;
     let latestAiRecommendation = 'Continue watching until stronger market signal appears.';
     let latestAiConfidence = 'Medium';
     let monitoringNotes = `Baseline recommendation generated from current ${signals.effectiveContext.mode} validation state for ${subjectLabel}.`;
@@ -157,9 +166,12 @@ export function buildValidationRecommendation(request, signals) {
             latestAiConfidence = 'Medium';
         }
     }
-    if (signals.research.previousComebackFirstWeekSales !== null) {
+    if (hasUsableHistoricalResearch && signals.research.previousComebackFirstWeekSales !== null) {
         monitoringNotes += ` Previous comeback first-week sales reference: ${signals.research.previousComebackFirstWeekSales}.`;
     }
+    if (hasUsableHistoricalResearch && signals.research.historicalContextNotes.length > 0) {
+        monitoringNotes += ` Historical context (${signals.research.confidence}, score ${signals.research.perplexityHistoricalContextScore}/20): ${signals.research.historicalContextNotes}`;
+    }
     return {
         buyDecision: request.validation.buyDecision,
         automationStatus: shouldAutoTrack ? 'Watching' : 'Paused',

package/build/validation/run-validation.js

@@ -49,13 +49,69 @@ function getFieldPresence(fields) {
 function getWriteSource(value, source) {
     return isMeaningfulWriteValue(value) ? source : 'none';
 }
-function resolvePreferredSoldMetric(soldValue, terapeakValue, ebayValue) {
-    if (soldValue !== null) {
-        return { value: soldValue, source: 'sold' };
-    }
+function hasSoldVelocityEvidence(soldVelocity) {
+    return Object.values(soldVelocity).some((value) => value !== null);
+}
+function hasPrimaryResearchSoldSignals(terapeak) {
+    return (terapeak.provider === 'ebay_research_ui' &&
+        (terapeak.researchSoldPriceUsd !== null ||
+            terapeak.soldListingsCount !== null ||
+            terapeak.recentSoldCount7d !== null ||
+            hasSoldVelocityEvidence(terapeak.soldVelocity)));
+}
+function createSkippedSoldSignals() {
+    return {
+        provider: 'third_party_sold_api',
+        confidence: 'Low',
+        soldResultsCount: null,
+        soldAveragePriceUsd: null,
+        soldMedianPriceUsd: null,
+        soldMinPriceUsd: null,
+        soldMaxPriceUsd: null,
+        soldItemsSample: [],
+        soldVelocity: {
+            day1Sold: null,
+            day2Sold: null,
+            day3Sold: null,
+            day4Sold: null,
+            day5Sold: null,
+            daysTracked: null,
+        },
+        recentSoldCount7d: null,
+        soldBucketDebug: {
+            status: 'skipped',
+            notes: [
+                'legacy sold fallback was skipped because first-party research sold signals were sufficient',
+            ],
+            totalItemsExamined: 0,
+            withSoldAt: 0,
+            missingSoldAt: 0,
+            dateParseFailures: 0,
+            futureDated: 0,
+            bucketedItems: 0,
+        },
+        query: null,
+        queryCandidates: [],
+        queryDiagnostics: [],
+        selectedQuery: undefined,
+        selectedQueryTier: null,
+        selectedQueryFamily: null,
+        broadAlbumQuery: null,
+        subtypeSpecificQuery: null,
+        querySelectionReason: 'Legacy sold fallback was skipped because first-party research sold signals were sufficient.',
+        responseUrl: null,
+        status: 'skipped',
+        errorMessage: undefined,
+        queryResolution: undefined,
+    };
+}
+function resolvePreferredSoldMetric(terapeakValue, soldValue, ebayValue) {
     if (terapeakValue !== null) {
         return { value: terapeakValue, source: 'terapeak' };
     }
+    if (soldValue !== null) {
+        return { value: soldValue, source: 'sold' };
+    }
     if (ebayValue !== null) {
         return { value: ebayValue, source: 'ebay' };
     }
@@ -105,6 +161,9 @@ function buildProviderDebug(request, ebay, sold, terapeak, social, chart, resear
     const researchFields = getFieldPresence({
         previousAlbumTitle: research.previousAlbumTitle,
         previousComebackFirstWeekSales: research.previousComebackFirstWeekSales,
+        perplexityHistoricalContextScore: research.perplexityHistoricalContextScore,
+        historicalContextNotes: research.historicalContextNotes,
+        researchConfidence: research.confidence,
     });
     const ebayStatus = (ebay.queryCandidates?.length ?? 0) === 0
         ? 'unavailable'
@@ -117,9 +176,15 @@ function buildProviderDebug(request, ebay, sold, terapeak, social, chart, resear
         : terapeakFields.contributed.length > 0
             ? 'ok'
             : 'partial';
-    const researchStatus = research.previousComebackFirstWeekSales !== null || research.previousAlbumTitle !== null
-        ? 'ok'
-        : 'stub';
+    const researchStatus = research.debug?.providerStatus === 'unconfigured'
+        ? 'unavailable'
+        : research.debug?.providerStatus === 'error'
+            ? 'partial'
+            : research.previousComebackFirstWeekSales !== null ||
+                research.previousAlbumTitle !== null ||
+                research.perplexityHistoricalContextScore > 0
+                ? 'ok'
+                : 'partial';
     return {
         ebay: {
             status: ebayStatus,
@@ -225,10 +290,23 @@ function buildProviderDebug(request, ebay, sold, terapeak, social, chart, resear
             confidence: research.confidence.toLowerCase(),
             previousAlbumTitle: research.previousAlbumTitle,
             previousComebackFirstWeekSales: research.previousComebackFirstWeekSales,
+            perplexityHistoricalContextScore: research.perplexityHistoricalContextScore,
+            historicalContextNotes: research.historicalContextNotes,
             contributedFields: researchFields.contributed,
             omittedFields: researchFields.omitted,
             notes: research.notes,
             sources: research.sources ?? [],
+            query: research.debug?.query ?? null,
+            promptFocus: research.debug?.promptFocus ?? [],
+            sourceSnippets: research.debug?.sourceSnippets ?? [],
+            resolvedPriorRelease: research.debug?.resolvedPriorRelease ?? research.previousAlbumTitle,
+            extractedConfidence: research.debug?.extractedConfidence ?? null,
+            computedConfidence: research.debug?.computedConfidence ?? research.confidence,
+            confidenceReason: research.debug?.confidenceReason ?? null,
+            scoreAssignmentReason: research.debug?.scoreAssignmentReason ?? null,
+            providerStatus: research.debug?.providerStatus ?? null,
+            parseStatus: research.debug?.parseStatus ?? null,
+            errorMessage: research.debug?.errorMessage ?? null,
         },
     };
 }
@@ -254,8 +332,11 @@ export async function runValidation(api, input) {
             effectiveContext,
         };
         const ebay = await getEbayValidationSignals(api, effectiveRequest);
-        const sold = await getEbaySoldValidationSignals(effectiveRequest);
         const terapeak = await getTerapeakValidationSignals(api, effectiveRequest);
+        const primaryResearchSoldSignalsAvailable = hasPrimaryResearchSoldSignals(terapeak);
+        const sold = primaryResearchSoldSignalsAvailable
+            ? createSkippedSoldSignals()
+            : await getEbaySoldValidationSignals(effectiveRequest);
         const social = await getSocialValidationSignals(effectiveRequest);
         const chart = getChartValidationSignals(effectiveRequest);
         const research = await getPreviousComebackResearchSignals(effectiveRequest);
@@ -264,12 +345,12 @@ export async function runValidation(api, input) {
         const marketPriceUsd = terapeak.marketPriceUsd ?? sold.soldMedianPriceUsd ?? ebay.marketPriceUsd;
         const mergedAvgShippingCostUsd = terapeak.avgShippingCostUsd ?? ebay.avgShippingCostUsd;
         const mergedCompetitionLevel = terapeak.competitionLevel ?? ebay.competitionLevel;
-        const day1Sold = resolvePreferredSoldMetric(sold.soldVelocity.day1Sold, terapeak.soldVelocity.day1Sold, ebay.soldVelocity.day1Sold);
-        const day2Sold = resolvePreferredSoldMetric(sold.soldVelocity.day2Sold, terapeak.soldVelocity.day2Sold, ebay.soldVelocity.day2Sold);
-        const day3Sold = resolvePreferredSoldMetric(sold.soldVelocity.day3Sold, terapeak.soldVelocity.day3Sold, ebay.soldVelocity.day3Sold);
-        const day4Sold = resolvePreferredSoldMetric(sold.soldVelocity.day4Sold, terapeak.soldVelocity.day4Sold, ebay.soldVelocity.day4Sold);
-        const day5Sold = resolvePreferredSoldMetric(sold.soldVelocity.day5Sold, terapeak.soldVelocity.day5Sold, ebay.soldVelocity.day5Sold);
-        const daysTracked = resolvePreferredSoldMetric(sold.soldVelocity.daysTracked, terapeak.soldVelocity.daysTracked, ebay.soldVelocity.daysTracked);
+        const day1Sold = resolvePreferredSoldMetric(terapeak.soldVelocity.day1Sold, sold.soldVelocity.day1Sold, ebay.soldVelocity.day1Sold);
+        const day2Sold = resolvePreferredSoldMetric(terapeak.soldVelocity.day2Sold, sold.soldVelocity.day2Sold, ebay.soldVelocity.day2Sold);
+        const day3Sold = resolvePreferredSoldMetric(terapeak.soldVelocity.day3Sold, sold.soldVelocity.day3Sold, ebay.soldVelocity.day3Sold);
+        const day4Sold = resolvePreferredSoldMetric(terapeak.soldVelocity.day4Sold, sold.soldVelocity.day4Sold, ebay.soldVelocity.day4Sold);
+        const day5Sold = resolvePreferredSoldMetric(terapeak.soldVelocity.day5Sold, sold.soldVelocity.day5Sold, ebay.soldVelocity.day5Sold);
+        const daysTracked = resolvePreferredSoldMetric(terapeak.soldVelocity.daysTracked, sold.soldVelocity.daysTracked, ebay.soldVelocity.daysTracked);
         const soldVelocity = {
             day1Sold: day1Sold.value,
             day2Sold: day2Sold.value,
@@ -289,6 +370,39 @@ export async function runValidation(api, input) {
         });
         const requestQueryResolution = buildProviderQueryResolutionDebug(effectiveRequest, Boolean(ebay.queryResolution?.queryContextUsed));
         const mergedSignals = { effectiveContext, ebay, sold, terapeak, social, chart, research };
+        const activeSource = terapeak.avgWatchersPerListing !== null ||
+            terapeak.preOrderListingsCount !== null ||
+            terapeak.competitionLevel !== null
+            ? 'ebay_research_ui'
+            : ebay.preOrderListingsCount !== null ||
+                ebay.marketPriceUsd !== null ||
+                ebay.competitionLevel !== null
+                ? 'ebay_browse'
+                : 'none';
+        const soldSource = primaryResearchSoldSignalsAvailable
+            ? 'ebay_research_ui'
+            : sold.soldMedianPriceUsd !== null ||
+                sold.soldResultsCount !== null ||
+                hasSoldVelocityEvidence(sold.soldVelocity)
+                ? 'third_party_sold_api'
+                : ebay.marketPriceUsd !== null
+                    ? 'ebay_browse'
+                    : 'none';
+        const providerResolution = {
+            activeSource,
+            soldSource,
+            soldFallbackUsed: !primaryResearchSoldSignalsAvailable && soldSource === 'third_party_sold_api',
+            fallbackReason: primaryResearchSoldSignalsAvailable
+                ? null
+                : soldSource === 'third_party_sold_api'
+                    ? 'First-party research sold signals were unavailable or insufficient, so the legacy sold provider was used as automatic fallback.'
+                    : 'First-party research sold signals were unavailable or insufficient, but no legacy sold fallback data was available.',
+        };
+        const hasUsableHistoricalResearch = research.debug?.providerStatus !== undefined
+            ? research.debug.providerStatus === 'ok'
+            : research.previousAlbumTitle !== null ||
+                research.previousComebackFirstWeekSales !== null ||
+                research.perplexityHistoricalContextScore > 0;
         const socialWrites = {
             ...(social.twitterTrending !== null ? { twitterTrending: social.twitterTrending } : {}),
             ...(social.youtubeViews24hMillions !== null
@@ -307,7 +421,14 @@ export async function runValidation(api, input) {
                 : {}),
         };
         const researchWrites = {
-            ...(research.previousComebackFirstWeekSales !== null
+            ...(hasUsableHistoricalResearch
+                ? {
+                    perplexityHistoricalContextScore: research.perplexityHistoricalContextScore,
+                    historicalContextNotes: research.historicalContextNotes,
+                    researchConfidence: research.confidence,
+                }
+                : {}),
+            ...(hasUsableHistoricalResearch && research.previousComebackFirstWeekSales !== null
                 ? { previousComebackFirstWeekSales: research.previousComebackFirstWeekSales }
                 : {}),
         };
@@ -356,7 +477,10 @@ export async function runValidation(api, input) {
             previousPobSellThroughPct: terapeak.previousPobSellThroughPct !== null
                 ? (terapeak.queryDebug.writeSources?.previousPobSellThroughPct ?? 'terapeak')
                 : 'none',
-            previousComebackFirstWeekSales: getWriteSource(research.previousComebackFirstWeekSales, 'research'),
+            previousComebackFirstWeekSales: getWriteSource(hasUsableHistoricalResearch ? research.previousComebackFirstWeekSales : null, 'research'),
+            perplexityHistoricalContextScore: hasUsableHistoricalResearch ? 'research' : 'none',
+            historicalContextNotes: hasUsableHistoricalResearch ? 'research' : 'none',
+            researchConfidence: hasUsableHistoricalResearch ? 'research' : 'none',
         };
         const omittedOptionalWrites = Object.entries(writeResolution)
             .filter(([, source]) => source === 'none')
@@ -412,6 +536,7 @@ export async function runValidation(api, input) {
                 soldResultsCount: sold.soldResultsCount,
                 omittedOptionalWrites,
                 writeResolution,
+                providerResolution,
                 sourceSet: ['ebay', 'sold', 'terapeak', 'social', 'chart', 'research'],
                 providers: buildProviderDebug(effectiveRequest, ebay, sold, terapeak, social, chart, research),
                 queryContextUsed: requestQueryResolution.queryContextUsed,

package/build/validation/schemas.js

@@ -111,6 +111,9 @@ export const validationWritesSchema = z.object({
     previousPobAvgPriceUsd: z.number().nullable().optional(),
     previousPobSellThroughPct: z.number().nullable().optional(),
     previousComebackFirstWeekSales: z.number().nullable().optional(),
+    perplexityHistoricalContextScore: z.number().optional(),
+    historicalContextNotes: z.string().optional(),
+    researchConfidence: z.enum(['High', 'Medium', 'Low']).optional(),
     monitoringNotes: z.string().optional(),
     lastDataSnapshot: z.string().optional(),
     latestAiRecommendation: z.string().optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ebay-mcp-remote-edition",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Remote + Local MCP server for eBay APIs - provides access to eBay developer functionality through MCP (Model Context Protocol)",
   "type": "module",
   "main": "build/index.js",