ebay-mcp-remote-edition 3.2.0 → 3.3.1

package/build/validation/providers/terapeak.js

@@ -0,0 +1,30 @@
+import { buildResolvedValidationQueryPlan } from './query-utils.js';
+export async function getTerapeakValidationSignals(_api, request) {
+    await Promise.resolve();
+    const { queryPlan, queryResolution } = buildResolvedValidationQueryPlan(request);
+    const queryCandidates = queryPlan.map((candidate) => candidate.query);
+    const currentQuery = queryCandidates[0] ?? null;
+    const previousPobQuery = queryCandidates[1] ?? null;
+    return {
+        avgWatchersPerListing: null,
+        preOrderListingsCount: null,
+        marketPriceUsd: null,
+        avgShippingCostUsd: null,
+        competitionLevel: null,
+        previousPobAvgPriceUsd: null,
+        previousPobSellThroughPct: null,
+        currentListingsCount: null,
+        soldListingsCount: null,
+        provider: 'none',
+        confidence: 'Low',
+        queryDebug: {
+            currentQuery,
+            previousPobQuery,
+            selectedMode: 'combined',
+            currentResultCount: null,
+            previousPobResultCount: null,
+            queryResolution,
+            notes: 'Terapeak/eBay research provider contract is in place, but live authenticated research retrieval is not implemented yet.',
+        },
+    };
+}

package/build/validation/recommendation.js

@@ -13,11 +13,22 @@ export function buildValidationRecommendation(request, signals) {
         : trackingCadence === 'Hourly'
             ? addHours(request.timestamp, 1)
             : addHours(request.timestamp, 24);
-    const marketPrice = signals.sold.soldMedianPriceUsd ?? signals.ebay.marketPriceUsd;
-    const wholesale = request.item.wholesalePrice;
+    const marketPrice = signals.terapeak.marketPriceUsd ??
+        signals.sold.soldMedianPriceUsd ??
+        signals.ebay.marketPriceUsd;
+    const preorderListingsCount = signals.terapeak.preOrderListingsCount ?? signals.ebay.preOrderListingsCount;
+    const wholesale = signals.effectiveContext.hasItem ? request.item.wholesalePrice : null;
     const marginRatio = marketPrice !== null && wholesale !== null && wholesale > 0
         ? (marketPrice - wholesale) / wholesale
         : null;
+    const subjectLabel = signals.effectiveContext.sourceType === 'event'
+        ? (signals.effectiveContext.searchEvent ??
+            signals.effectiveContext.effectiveSearchQuery ??
+            'event opportunity')
+        : (signals.effectiveContext.searchAlbum ??
+            signals.effectiveContext.searchItem ??
+            request.item.name ??
+            'release');
     const recentSoldCount = [
         signals.sold.soldVelocity.day1Sold,
         signals.sold.soldVelocity.day2Sold,
@@ -25,18 +36,17 @@ export function buildValidationRecommendation(request, signals) {
     ].reduce((sum, value) => sum + (value ?? 0), 0);
     let latestAiRecommendation = 'Continue watching until stronger market signal appears.';
     let latestAiConfidence = 'Medium';
-    let monitoringNotes = 'Baseline recommendation generated from current validation state.';
+    let monitoringNotes = `Baseline recommendation generated from current ${signals.effectiveContext.mode} validation state for ${subjectLabel}.`;
     if (!shouldAutoTrack) {
         latestAiRecommendation =
             'Automatic tracking paused because the validation is no longer in a watchable state.';
         latestAiConfidence = 'High';
-        monitoringNotes =
-            'Stop conditions were met, so automation will not schedule another validation run.';
+        monitoringNotes = `Stop conditions were met, so automation will not schedule another ${signals.effectiveContext.mode} validation run for ${subjectLabel}.`;
     }
     else if (marginRatio !== null &&
         marginRatio >= 1 &&
-        signals.ebay.preOrderListingsCount !== null &&
-        signals.ebay.preOrderListingsCount >= 25) {
+        preorderListingsCount !== null &&
+        preorderListingsCount >= 25) {
         latestAiRecommendation =
             'Demand and pricing look constructive. Continue tracking closely and be ready to upgrade from watch status if sell-through strengthens.';
         latestAiConfidence = 'High';
@@ -63,13 +73,26 @@ export function buildValidationRecommendation(request, signals) {
         monitoringNotes =
             'Temporary sold-provider data is present, but sample depth is not yet strong enough to justify an automatic buy-decision change.';
     }
-    else if (signals.social.youtubeViews24hMillions !== null ||
-        signals.social.redditPostsCount7d !== null) {
+    else if (signals.social.twitterTrending === true ||
+        (signals.social.youtubeViews24hMillions !== null &&
+            signals.social.youtubeViews24hMillions >= 0.1) ||
+        (signals.social.redditPostsCount7d !== null && signals.social.redditPostsCount7d >= 5)) {
         latestAiRecommendation =
             'Demand signals are mixed. Keep monitoring until eBay pricing and social momentum become more decisive.';
         latestAiConfidence = 'Medium';
         monitoringNotes =
-            'Cross-channel activity exists, but the combined signal is not strong enough for an automatic buy change.';
+            'Cross-channel social activity exists, but it is only being used as a supporting confidence signal and is not strong enough to justify an automatic buy change.';
+    }
+    if (signals.terapeak.previousPobSellThroughPct !== null &&
+        signals.terapeak.previousPobSellThroughPct >= 50) {
+        monitoringNotes +=
+            ' Previous POB sell-through research suggests the comparable release sold through efficiently.';
+        if (latestAiConfidence !== 'High') {
+            latestAiConfidence = 'Medium';
+        }
+    }
+    if (signals.research.previousComebackFirstWeekSales !== null) {
+        monitoringNotes += ` Previous comeback first-week sales reference: ${signals.research.previousComebackFirstWeekSales}.`;
     }
     return {
         buyDecision: request.validation.buyDecision,

package/build/validation/run-validation.js

@@ -1,9 +1,13 @@
 import { validationRunRequestSchema } from './schemas.js';
 import { getEbayValidationSignals } from './providers/ebay.js';
 import { getEbaySoldValidationSignals } from './providers/ebay-sold.js';
+import { getTerapeakValidationSignals } from './providers/terapeak.js';
 import { getSocialValidationSignals } from './providers/social.js';
 import { getChartValidationSignals } from './providers/chart.js';
+import { getPreviousComebackResearchSignals } from './providers/research.js';
+import { buildProviderQueryResolutionDebug } from './providers/query-utils.js';
 import { buildValidationRecommendation } from './recommendation.js';
+import { buildValidationEffectiveContext } from './effective-context.js';
 function addMinutes(timestamp, minutes) {
     return new Date(new Date(timestamp).getTime() + minutes * 60 * 1000).toISOString();
 }
@@ -23,35 +27,171 @@ function getValidationId(input) {
     }
     return '';
 }
-function buildProviderDebug(ebay, sold, social, chart) {
+function isMeaningfulWriteValue(value) {
+    if (value === null || value === undefined) {
+        return false;
+    }
+    return typeof value !== 'string' || value.length > 0;
+}
+function getFieldPresence(fields) {
+    const contributed = [];
+    const omitted = [];
+    for (const [field, value] of Object.entries(fields)) {
+        if (isMeaningfulWriteValue(value)) {
+            contributed.push(field);
+        }
+        else {
+            omitted.push(field);
+        }
+    }
+    return { contributed, omitted };
+}
+function getWriteSource(value, source) {
+    return isMeaningfulWriteValue(value) ? source : 'none';
+}
+function buildProviderDebug(request, ebay, sold, terapeak, social, chart, research) {
+    const requestQueryResolution = buildProviderQueryResolutionDebug(request, Boolean(ebay.queryResolution?.queryContextUsed));
+    const ebayFields = getFieldPresence({
+        avgWatchersPerListing: ebay.avgWatchersPerListing,
+        preOrderListingsCount: ebay.preOrderListingsCount,
+        marketPriceUsd: ebay.marketPriceUsd,
+        avgShippingCostUsd: ebay.avgShippingCostUsd,
+        competitionLevel: ebay.competitionLevel,
+    });
+    const soldFields = getFieldPresence({
+        soldAveragePriceUsd: sold.soldAveragePriceUsd,
+        soldMedianPriceUsd: sold.soldMedianPriceUsd,
+        soldMinPriceUsd: sold.soldMinPriceUsd,
+        soldMaxPriceUsd: sold.soldMaxPriceUsd,
+        day1Sold: sold.soldVelocity.day1Sold,
+        day2Sold: sold.soldVelocity.day2Sold,
+        day3Sold: sold.soldVelocity.day3Sold,
+        day4Sold: sold.soldVelocity.day4Sold,
+        day5Sold: sold.soldVelocity.day5Sold,
+        daysTracked: sold.soldVelocity.daysTracked,
+    });
+    const terapeakFields = getFieldPresence({
+        avgWatchersPerListing: terapeak.avgWatchersPerListing,
+        preOrderListingsCount: terapeak.preOrderListingsCount,
+        marketPriceUsd: terapeak.marketPriceUsd,
+        avgShippingCostUsd: terapeak.avgShippingCostUsd,
+        competitionLevel: terapeak.competitionLevel,
+        previousPobAvgPriceUsd: terapeak.previousPobAvgPriceUsd,
+        previousPobSellThroughPct: terapeak.previousPobSellThroughPct,
+    });
+    const socialFields = getFieldPresence({
+        twitterTrending: social.twitterTrending,
+        youtubeViews24hMillions: social.youtubeViews24hMillions,
+        redditPostsCount7d: social.redditPostsCount7d,
+    });
+    const researchFields = getFieldPresence({
+        previousAlbumTitle: research.previousAlbumTitle,
+        previousComebackFirstWeekSales: research.previousComebackFirstWeekSales,
+    });
+    const ebayStatus = (ebay.queryCandidates?.length ?? 0) === 0
+        ? 'unavailable'
+        : ebay.sampleSize > 0
+            ? 'ok'
+            : 'partial';
+    const socialStatus = socialFields.contributed.length > 0 ? 'ok' : social.debug ? 'partial' : 'unavailable';
+    const terapeakStatus = terapeak.provider === 'none'
+        ? 'stub'
+        : terapeakFields.contributed.length > 0
+            ? 'ok'
+            : 'partial';
+    const researchStatus = research.previousComebackFirstWeekSales !== null || research.previousAlbumTitle !== null
+        ? 'ok'
+        : 'stub';
     return {
         ebay: {
-            status: ebay.sampleSize > 0 ? 'ok' : 'partial',
+            status: ebayStatus,
             confidence: ebay.sampleSize >= 10 ? 'medium' : 'low',
-            sampleSize: ebay.sampleSize,
-            hasMarketPrice: ebay.marketPriceUsd !== null,
-            hasShipping: ebay.avgShippingCostUsd !== null,
-            hasWatchers: ebay.avgWatchersPerListing !== null,
+            browseSampleSize: ebay.sampleSize,
+            queryCandidates: ebay.queryCandidates ?? [],
+            selectedQuery: ebay.selectedQuery,
+            selectedQueryTier: ebay.selectedQueryTier,
+            queryDiagnostics: ebay.queryDiagnostics ?? [],
+            queryContextUsed: ebay.queryResolution?.queryContextUsed ?? requestQueryResolution.queryContextUsed,
+            querySource: ebay.queryResolution?.querySource ?? requestQueryResolution.querySource,
+            resolvedSearchQuery: ebay.queryResolution?.resolvedSearchQuery ?? requestQueryResolution.resolvedSearchQuery,
+            validationScope: ebay.queryResolution?.validationScope ?? requestQueryResolution.validationScope,
+            queryScope: ebay.queryResolution?.queryScope ?? requestQueryResolution.queryScope,
+            selectionReason: ebay.selectionReason,
+            errorMessage: ebay.errorMessage,
+            responseStatus: ebay.responseStatus,
+            responseBodyExcerpt: ebay.responseBodyExcerpt,
+            contributedFields: ebayFields.contributed,
+            omittedFields: ebayFields.omitted,
         },
         sold: {
             status: sold.status,
             provider: sold.provider,
             confidence: sold.confidence.toLowerCase(),
-            results: sold.soldResultsCount,
-            hasMedianPrice: sold.soldMedianPriceUsd !== null,
-            hasVelocity: sold.soldVelocity.daysTracked !== null,
+            soldResultsCount: sold.soldResultsCount,
+            queryCandidates: sold.queryCandidates ?? [],
+            selectedQuery: sold.selectedQuery,
+            selectedQueryTier: sold.selectedQueryTier,
+            queryContextUsed: sold.queryResolution?.queryContextUsed ?? requestQueryResolution.queryContextUsed,
+            querySource: sold.queryResolution?.querySource ?? requestQueryResolution.querySource,
+            resolvedSearchQuery: sold.queryResolution?.resolvedSearchQuery ?? requestQueryResolution.resolvedSearchQuery,
+            validationScope: sold.queryResolution?.validationScope ?? requestQueryResolution.validationScope,
+            queryScope: sold.queryResolution?.queryScope ?? requestQueryResolution.queryScope,
+            contributedFields: soldFields.contributed,
+            omittedFields: soldFields.omitted,
+            errorMessage: sold.errorMessage,
+        },
+        terapeak: {
+            status: terapeakStatus,
+            provider: terapeak.provider,
+            confidence: terapeak.confidence.toLowerCase(),
+            queryCandidates: [
+                terapeak.queryDebug.currentQuery,
+                terapeak.queryDebug.previousPobQuery,
+            ].filter((value) => typeof value === 'string' && value.length > 0),
+            currentQuery: terapeak.queryDebug.currentQuery,
+            previousPobQuery: terapeak.queryDebug.previousPobQuery,
+            queryContextUsed: terapeak.queryDebug.queryResolution?.queryContextUsed ??
+                requestQueryResolution.queryContextUsed,
+            querySource: terapeak.queryDebug.queryResolution?.querySource ?? requestQueryResolution.querySource,
+            resolvedSearchQuery: terapeak.queryDebug.queryResolution?.resolvedSearchQuery ??
+                requestQueryResolution.resolvedSearchQuery,
+            validationScope: terapeak.queryDebug.queryResolution?.validationScope ??
+                requestQueryResolution.validationScope,
+            queryScope: terapeak.queryDebug.queryResolution?.queryScope ?? requestQueryResolution.queryScope,
+            selectedMode: terapeak.queryDebug.selectedMode,
+            currentResultCount: terapeak.queryDebug.currentResultCount,
+            previousPobResultCount: terapeak.queryDebug.previousPobResultCount,
+            contributedFields: terapeakFields.contributed,
+            omittedFields: terapeakFields.omitted,
+            notes: terapeak.queryDebug.notes,
         },
         social: {
-            status: 'stub',
+            status: socialStatus,
             confidence: 'low',
-            hasSignals: social.twitterTrending ||
-                social.youtubeViews24hMillions !== null ||
-                social.redditPostsCount7d !== null,
+            queryContextUsed: requestQueryResolution.queryContextUsed,
+            querySource: requestQueryResolution.querySource,
+            resolvedSearchQuery: requestQueryResolution.resolvedSearchQuery,
+            validationScope: requestQueryResolution.validationScope,
+            queryScope: requestQueryResolution.queryScope,
+            contributedFields: socialFields.contributed,
+            omittedFields: socialFields.omitted,
+            details: social.debug,
         },
         chart: {
             status: 'stub',
             confidence: 'low',
-            hasSignals: Object.keys(chart).length > 0,
+            contributedFields: [],
+            omittedFields: ['chartMomentum'],
+        },
+        research: {
+            status: researchStatus,
+            confidence: research.confidence.toLowerCase(),
+            previousAlbumTitle: research.previousAlbumTitle,
+            previousComebackFirstWeekSales: research.previousComebackFirstWeekSales,
+            contributedFields: researchFields.contributed,
+            omittedFields: researchFields.omitted,
+            notes: research.notes,
+            sources: research.sources ?? [],
         },
     };
 }
@@ -71,11 +211,22 @@ export async function runValidation(api, input) {
         };
     }
     try {
-        const ebay = await getEbayValidationSignals(api, request);
-        const sold = await getEbaySoldValidationSignals(request);
-        const social = getSocialValidationSignals(request);
-        const chart = getChartValidationSignals(request);
-        const marketPriceUsd = sold.soldMedianPriceUsd ?? ebay.marketPriceUsd;
+        const effectiveContext = buildValidationEffectiveContext(request);
+        const effectiveRequest = {
+            ...request,
+            effectiveContext,
+        };
+        const ebay = await getEbayValidationSignals(api, effectiveRequest);
+        const sold = await getEbaySoldValidationSignals(effectiveRequest);
+        const terapeak = await getTerapeakValidationSignals(api, effectiveRequest);
+        const social = await getSocialValidationSignals(effectiveRequest);
+        const chart = getChartValidationSignals(effectiveRequest);
+        const research = await getPreviousComebackResearchSignals(effectiveRequest);
+        const mergedAvgWatchers = terapeak.avgWatchersPerListing ?? ebay.avgWatchersPerListing;
+        const mergedPreorderListings = terapeak.preOrderListingsCount ?? ebay.preOrderListingsCount;
+        const marketPriceUsd = terapeak.marketPriceUsd ?? sold.soldMedianPriceUsd ?? ebay.marketPriceUsd;
+        const mergedAvgShippingCostUsd = terapeak.avgShippingCostUsd ?? ebay.avgShippingCostUsd;
+        const mergedCompetitionLevel = terapeak.competitionLevel ?? ebay.competitionLevel;
         const soldVelocity = {
             day1Sold: sold.soldVelocity.day1Sold ?? ebay.soldVelocity.day1Sold,
             day2Sold: sold.soldVelocity.day2Sold ?? ebay.soldVelocity.day2Sold,
@@ -84,20 +235,95 @@ export async function runValidation(api, input) {
             day5Sold: sold.soldVelocity.day5Sold ?? ebay.soldVelocity.day5Sold,
             daysTracked: sold.soldVelocity.daysTracked ?? ebay.soldVelocity.daysTracked,
         };
-        const recommendation = buildValidationRecommendation(request, { ebay, sold, social, chart });
-        const mergedSignals = { ebay, sold, social, chart };
+        const recommendation = buildValidationRecommendation(effectiveRequest, {
+            ebay,
+            sold,
+            terapeak,
+            social,
+            chart,
+            research,
+            effectiveContext,
+        });
+        const requestQueryResolution = buildProviderQueryResolutionDebug(effectiveRequest, Boolean(ebay.queryResolution?.queryContextUsed));
+        const mergedSignals = { effectiveContext, ebay, sold, terapeak, social, chart, research };
+        const socialWrites = {
+            ...(social.twitterTrending !== null ? { twitterTrending: social.twitterTrending } : {}),
+            ...(social.youtubeViews24hMillions !== null
+                ? { youtubeViews24hMillions: social.youtubeViews24hMillions }
+                : {}),
+            ...(social.redditPostsCount7d !== null
+                ? { redditPostsCount7d: social.redditPostsCount7d }
+                : {}),
+        };
+        const terapeakWrites = {
+            ...(terapeak.previousPobAvgPriceUsd !== null
+                ? { previousPobAvgPriceUsd: terapeak.previousPobAvgPriceUsd }
+                : {}),
+            ...(terapeak.previousPobSellThroughPct !== null
+                ? { previousPobSellThroughPct: terapeak.previousPobSellThroughPct }
+                : {}),
+        };
+        const researchWrites = {
+            ...(research.previousComebackFirstWeekSales !== null
+                ? { previousComebackFirstWeekSales: research.previousComebackFirstWeekSales }
+                : {}),
+        };
+        const writeResolution = {
+            avgWatchersPerListing: terapeak.avgWatchersPerListing !== null
+                ? 'terapeak'
+                : getWriteSource(ebay.avgWatchersPerListing, 'ebay'),
+            preOrderListingsCount: terapeak.preOrderListingsCount !== null
+                ? 'terapeak'
+                : getWriteSource(ebay.preOrderListingsCount, 'ebay'),
+            marketPriceUsd: terapeak.marketPriceUsd !== null
+                ? 'terapeak'
+                : sold.soldMedianPriceUsd !== null
+                    ? 'sold'
+                    : getWriteSource(ebay.marketPriceUsd, 'ebay'),
+            avgShippingCostUsd: terapeak.avgShippingCostUsd !== null
+                ? 'terapeak'
+                : getWriteSource(ebay.avgShippingCostUsd, 'ebay'),
+            competitionLevel: terapeak.competitionLevel !== null
+                ? 'terapeak'
+                : getWriteSource(ebay.competitionLevel, 'ebay'),
+            twitterTrending: getWriteSource(social.twitterTrending, 'social'),
+            youtubeViews24hMillions: getWriteSource(social.youtubeViews24hMillions, 'social'),
+            redditPostsCount7d: getWriteSource(social.redditPostsCount7d, 'social'),
+            day1Sold: sold.soldVelocity.day1Sold !== null
+                ? 'sold'
+                : getWriteSource(ebay.soldVelocity.day1Sold, 'ebay'),
+            day2Sold: sold.soldVelocity.day2Sold !== null
+                ? 'sold'
+                : getWriteSource(ebay.soldVelocity.day2Sold, 'ebay'),
+            day3Sold: sold.soldVelocity.day3Sold !== null
+                ? 'sold'
+                : getWriteSource(ebay.soldVelocity.day3Sold, 'ebay'),
+            day4Sold: sold.soldVelocity.day4Sold !== null
+                ? 'sold'
+                : getWriteSource(ebay.soldVelocity.day4Sold, 'ebay'),
+            day5Sold: sold.soldVelocity.day5Sold !== null
+                ? 'sold'
+                : getWriteSource(ebay.soldVelocity.day5Sold, 'ebay'),
+            daysTracked: sold.soldVelocity.daysTracked !== null
+                ? 'sold'
+                : getWriteSource(ebay.soldVelocity.daysTracked, 'ebay'),
+            previousPobAvgPriceUsd: getWriteSource(terapeak.previousPobAvgPriceUsd, 'terapeak'),
+            previousPobSellThroughPct: getWriteSource(terapeak.previousPobSellThroughPct, 'terapeak'),
+            previousComebackFirstWeekSales: getWriteSource(research.previousComebackFirstWeekSales, 'research'),
+        };
+        const omittedOptionalWrites = Object.entries(writeResolution)
+            .filter(([, source]) => source === 'none')
+            .map(([field]) => field);
         return {
             status: 'ok',
             validationId: request.validationId,
             writes: {
-                avgWatchersPerListing: ebay.avgWatchersPerListing,
-                preOrderListingsCount: ebay.preOrderListingsCount,
-                twitterTrending: social.twitterTrending,
-                youtubeViews24hMillions: social.youtubeViews24hMillions,
-                redditPostsCount7d: social.redditPostsCount7d,
+                avgWatchersPerListing: mergedAvgWatchers,
+                preOrderListingsCount: mergedPreorderListings,
+                ...socialWrites,
                 marketPriceUsd,
-                avgShippingCostUsd: ebay.avgShippingCostUsd,
-                competitionLevel: ebay.competitionLevel,
+                avgShippingCostUsd: mergedAvgShippingCostUsd,
+                competitionLevel: mergedCompetitionLevel,
                 marketPriceTrend: ebay.marketPriceTrend,
                 day1Sold: soldVelocity.day1Sold,
                 day2Sold: soldVelocity.day2Sold,
@@ -105,6 +331,8 @@ export async function runValidation(api, input) {
                 day4Sold: soldVelocity.day4Sold,
                 day5Sold: soldVelocity.day5Sold,
                 daysTracked: soldVelocity.daysTracked,
+                ...terapeakWrites,
+                ...researchWrites,
                 monitoringNotes: recommendation.monitoringNotes,
                 lastDataSnapshot: JSON.stringify(mergedSignals),
                 latestAiRecommendation: recommendation.latestAiRecommendation,
@@ -119,11 +347,31 @@ export async function runValidation(api, input) {
                 nextCheckAt: recommendation.nextCheckAt,
             },
             debug: {
+                sourceContext: effectiveRequest.sourceContext ?? null,
+                effectiveSourceType: effectiveContext.sourceType,
+                effectiveContextMode: effectiveContext.mode,
+                effectiveSearchQuery: effectiveContext.effectiveSearchQuery,
+                hasItem: effectiveContext.hasItem,
+                hasEvent: effectiveContext.hasEvent,
+                effectiveContext,
                 ebayQuery: ebay.ebayQuery,
                 soldQuery: sold.query,
-                sampleSize: ebay.sampleSize,
-                sourceSet: ['ebay', 'sold', 'social', 'chart'],
-                providers: buildProviderDebug(ebay, sold, social, chart),
+                queryCandidates: {
+                    ebay: ebay.queryCandidates ?? [],
+                    sold: sold.queryCandidates ?? [],
+                    terapeak: [terapeak.queryDebug.currentQuery, terapeak.queryDebug.previousPobQuery].filter((value) => typeof value === 'string' && value.length > 0),
+                },
+                browseSampleSize: ebay.sampleSize,
+                soldResultsCount: sold.soldResultsCount,
+                omittedOptionalWrites,
+                writeResolution,
+                sourceSet: ['ebay', 'sold', 'terapeak', 'social', 'chart', 'research'],
+                providers: buildProviderDebug(effectiveRequest, ebay, sold, terapeak, social, chart, research),
+                queryContextUsed: requestQueryResolution.queryContextUsed,
+                querySource: requestQueryResolution.querySource,
+                resolvedSearchQuery: requestQueryResolution.resolvedSearchQuery,
+                validationScope: requestQueryResolution.validationScope,
+                queryScope: requestQueryResolution.queryScope,
             },
         };
     }

package/build/validation/schemas.js

@@ -17,25 +17,46 @@ export const validationCurrentMetricsSchema = z.object({
     day5Sold: z.number().nullable(),
     daysTracked: z.number().nullable(),
 });
-export const validationRunRequestSchema = z.object({
+export const validationQueryContextSchema = z.object({
+    directQueryActive: z.boolean().nullable().optional(),
+    directSearchQuery: z.string().nullable().optional(),
+    resolvedSearchArtist: z.string().nullable().optional(),
+    resolvedSearchItem: z.string().nullable().optional(),
+    resolvedSearchEvent: z.string().nullable().optional(),
+    resolvedSearchLocation: z.string().nullable().optional(),
+    resolvedSearchQuery: z.string().nullable().optional(),
+    validationScope: z.string().nullable().optional(),
+    queryScope: z.string().nullable().optional(),
+});
+export const validationSourceContextSchema = z.object({
+    sourceType: z.enum(['item', 'event']).optional(),
+    hasItem: z.boolean().optional(),
+    hasEvent: z.boolean().optional(),
+    itemRecordId: z.string().nullable().optional(),
+    eventRecordId: z.string().nullable().optional(),
+});
+const validationItemSchema = z.object({
+    recordId: z.string().min(1).nullable(),
+    name: z.string(),
+    variation: z.array(z.string()),
+    itemType: z.array(z.string()),
+    releaseType: z.array(z.string()),
+    releaseDate: z.string().datetime({ offset: true }).nullable(),
+    releasePeriod: z.array(z.string()),
+    availability: z.array(z.string()),
+    wholesalePrice: z.number().nullable(),
+    supplierNames: z.array(z.string()),
+    canonicalArtists: z.array(z.string()),
+    relatedAlbums: z.array(z.string()),
+});
+export const validationRunRequestSchema = z
+    .object({
     validationId: z.string().min(1),
     runType: z.enum(['scheduled', 'manual']),
     cadence: trackingCadenceSchema,
     timestamp: z.string().datetime({ offset: true }),
-    item: z.object({
-        recordId: z.string().min(1),
-        name: z.string().min(1),
-        variation: z.array(z.string()),
-        itemType: z.array(z.string()),
-        releaseType: z.array(z.string()),
-        releaseDate: z.string().datetime({ offset: true }).nullable(),
-        releasePeriod: z.array(z.string()),
-        availability: z.array(z.string()),
-        wholesalePrice: z.number().nullable(),
-        supplierNames: z.array(z.string()),
-        canonicalArtists: z.array(z.string()),
-        relatedAlbums: z.array(z.string()),
-    }),
+    sourceContext: validationSourceContextSchema.optional(),
+    item: validationItemSchema,
     validation: z.object({
         validationType: z.string(),
         buyDecision: z.string(),
@@ -45,8 +66,31 @@ export const validationRunRequestSchema = z.object({
         artistTier: z.string(),
         initialBudget: z.number().nullable(),
         reserveBudget: z.number().nullable(),
+        queryContext: validationQueryContextSchema.optional(),
         currentMetrics: validationCurrentMetricsSchema,
     }),
+})
+    .superRefine((value, ctx) => {
+    const sourceType = value.sourceContext?.sourceType ?? 'item';
+    const itemRecordId = value.item.recordId?.trim() ?? '';
+    const itemName = value.item.name.trim();
+    if (sourceType === 'event') {
+        return;
+    }
+    if (itemRecordId.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['item', 'recordId'],
+            message: 'Item-driven validations require item.recordId.',
+        });
+    }
+    if (itemName.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['item', 'name'],
+            message: 'Item-driven validations require item.name.',
+        });
+    }
 });
 export const validationWritesSchema = z.object({
     avgWatchersPerListing: z.number().nullable().optional(),
@@ -64,6 +108,9 @@ export const validationWritesSchema = z.object({
     day4Sold: z.number().nullable().optional(),
     day5Sold: z.number().nullable().optional(),
     daysTracked: z.number().nullable().optional(),
+    previousPobAvgPriceUsd: z.number().nullable().optional(),
+    previousPobSellThroughPct: z.number().nullable().optional(),
+    previousComebackFirstWeekSales: z.number().nullable().optional(),
     monitoringNotes: z.string().optional(),
     lastDataSnapshot: z.string().optional(),
     latestAiRecommendation: z.string().optional(),