@ainyc/canonry 4.115.1 → 4.117.0

package/dist/{chunk-Z3OGDQHB.js → chunk-FVVKNMZW.js}

@@ -2,6 +2,7 @@ import {
   AGENT_PROVIDER_IDS,
   AI_ENGINE_DOMAINS,
   AI_PROVIDER_INFRA_DOMAINS,
+  AiReferralTrafficClasses,
   AppError,
   BacklinkSources,
   CcReleaseSyncStatuses,
@@ -20,7 +21,6 @@ import {
   DiscoveryBuckets,
   DiscoveryCompetitorTypes,
   DiscoverySessionStatuses,
-  GA4AiReferralTrafficClasses,
   RunKinds,
   RunStatuses,
   RunTriggers,
@@ -50,6 +50,7 @@ import {
   adsSyncResponseSchema,
   agentProvidersResponseDtoSchema,
   aggregateHarvestedQueries,
+  aiReferralClassCounts,
   apiKeyDtoSchema,
   apiKeyListDtoSchema,
   applyHarvestSemanticNovelty,
@@ -87,8 +88,8 @@ import {
   citationStateSchema,
   citationStateToCited,
   citationVisibilityResponseSchema,
+  classifyAiReferralTrafficClass,
   classifyCitedSurface,
-  classifyGa4AiReferralTrafficClass,
   classifySkillFile,
   classifySurfaceFromCategory,
   classifyTrafficPath,
@@ -132,6 +133,7 @@ import {
   filterBrandedSeedCandidates,
   findDuplicateLocationLabels,
   forbidden,
+  formatAiReferralClassSummary,
   formatAverageDelta,
   formatDate,
   formatDateRange,
@@ -171,6 +173,7 @@ import {
   gscSitemapListResponseDtoSchema,
   gscUrlInspectionDtoSchema,
   hasLocationLabel,
+  hostOf,
   indexingRequestResponseDtoSchema,
   internalError,
   isReadOnlyKey,
@@ -257,8 +260,10 @@ import {
   trafficSyncResponseSchema,
   unsupportedKind,
   validationError,
+  visibilityCompareDtoSchema,
   visibilityStateFromAnswerMentioned,
   visibilityStatsDtoSchema,
+  wilsonInterval,
   windowCutoff,
   winnabilityClassLabel,
   winnabilityClassSchema,
@@ -275,7 +280,7 @@ import {
   wordpressSchemaDeployResultDtoSchema,
   wordpressSchemaStatusResultDtoSchema,
   wordpressStatusDtoSchema
-} from "./chunk-6LOKMEL3.js";
+} from "./chunk-IAJ5TQ4S.js";
 
 // src/intelligence-service.ts
 import { eq as eq38, desc as desc18, asc as asc6, and as and30, ne as ne5, or as or6, inArray as inArray14, gte as gte7, lte as lte4 } from "drizzle-orm";
@@ -1100,6 +1105,17 @@ var aiReferralEventsHourly = sqliteTable("ai_referral_events_hourly", {
   landingPathNormalized: text("landing_path_normalized").notNull(),
   status: integer("status").notNull(),
   sessionsOrHits: integer("sessions_or_hits").notNull().default(0),
+  /**
+   * Paid/organic splits the MEASURE, not the primary key. The paid marker lives
+   * in the request's UTM tags, which `landing_path_normalized` strips, so one
+   * bucket can legitimately hold both kinds and the class is NOT functionally
+   * determined by the key. Unclassified arrivals are the residual
+   * `sessions_or_hits - paid - organic`, which leaves rows written before the
+   * ingest classifier shipped (both columns 0) visibly unknown rather than
+   * silently organic — the regression migration v95 shipped on the GA4 side.
+   */
+  paidSessionsOrHits: integer("paid_sessions_or_hits").notNull().default(0),
+  organicSessionsOrHits: integer("organic_sessions_or_hits").notNull().default(0),
   usersEstimated: integer("users_estimated"),
   createdAt: text("created_at").notNull(),
   updatedAt: text("updated_at").notNull()
@@ -3512,7 +3528,7 @@ var MIGRATION_VERSIONS = [
     //
     // Every row is re-classified, not only the "unclassified" ones: v95's
     // default is indistinguishable from a genuinely-organic classification, so
-    // there is no way to tell the two apart. `classifyGa4AiReferralTrafficClass`
+    // there is no way to tell the two apart. `classifyAiReferralTrafficClass`
     // is pure and deterministic, so re-running it over already-correct rows
     // writes nothing, which is what makes this version safe to replay.
     version: 96,
@@ -3521,6 +3537,27 @@ var MIGRATION_VERSIONS = [
     run: (tx) => {
       backfillGaAiReferralTrafficClass(tx);
     }
+  },
+  {
+    // Splits the server-side AI-referral MEASURE by traffic class rather than
+    // adding a class column. Paid-ness lives in the request's UTM tags, which
+    // `landing_path_normalized` strips, so one hourly bucket can legitimately
+    // hold both paid and organic arrivals: a class column outside the 8-column
+    // primary key would silently stamp a mixed bucket with one label, and
+    // SQLite cannot extend a composite key with ADD COLUMN anyway.
+    //
+    // Deliberately NO backfill. The discriminator was never persisted — the
+    // request's query string is dropped before the hourly bucket and before
+    // `raw_event_samples` — so no honest class exists for historical rows.
+    // Leaving both counters at 0 surfaces their whole `sessions_or_hits` as the
+    // unknown residual. An older binary writing rows after a downgrade lands in
+    // that residual too, which is the truth about those rows.
+    version: 97,
+    name: "server-side-ai-referral-traffic-class",
+    statements: [
+      `ALTER TABLE ai_referral_events_hourly ADD COLUMN paid_sessions_or_hits INTEGER NOT NULL DEFAULT 0`,
+      `ALTER TABLE ai_referral_events_hourly ADD COLUMN organic_sessions_or_hits INTEGER NOT NULL DEFAULT 0`
+    ]
   }
 ];
 function rebuildBacklinkTableWithSource(tx, table) {
@@ -3615,7 +3652,7 @@ function backfillGaAiReferralTrafficClass(tx) {
   ));
   let updated = 0;
   for (const row of rows) {
-    const next = classifyGa4AiReferralTrafficClass({
+    const next = classifyAiReferralTrafficClass({
       source: row.source,
       medium: row.medium,
       channelGroup: row.channel_group,
@@ -5613,8 +5650,8 @@ var METRIC_LABELS = {
   WEBSITE_CLICKS: "Website clicks",
   CALL_CLICKS: "Call clicks"
 };
-function metricLabel(metric) {
-  return METRIC_LABELS[metric] ?? metric;
+function metricLabel(metric2) {
+  return METRIC_LABELS[metric2] ?? metric2;
 }
 function formatAmenityList(amenities) {
   if (amenities.length === 1) return amenities[0];
@@ -5708,12 +5745,12 @@ function analyzeGbp(signals) {
 }
 function pickWorstMetricDrop(loc) {
   let worst = null;
-  for (const metric of GBP_HEADLINE_METRICS) {
-    const delta = loc.metricDeltaPct[metric];
-    const prior = loc.metricPrior7d[metric] ?? 0;
+  for (const metric2 of GBP_HEADLINE_METRICS) {
+    const delta = loc.metricDeltaPct[metric2];
+    const prior = loc.metricPrior7d[metric2] ?? 0;
     if (delta == null || delta > -GBP_METRIC_DROP_PCT || prior < GBP_METRIC_MIN_BASELINE) continue;
     if (!worst || delta < worst.deltaPct) {
-      worst = { metric, deltaPct: delta, recent: loc.metricRecent7d[metric] ?? 0, prior };
+      worst = { metric: metric2, deltaPct: delta, recent: loc.metricRecent7d[metric2] ?? 0, prior };
     }
   }
   return worst;
@@ -8507,7 +8544,7 @@ function computeBuckets(snapshots, projectRuns, bucketDays, queryCreatedAt, ment
         });
         if (eligible.length > 0) usable = eligible;
       }
-      const metric = computeProviderMetric(usable);
+      const metric2 = computeProviderMetric(usable);
       const queryCount = new Set(usable.map((s) => s.queryId)).size;
       const byProvider = {};
       for (const provider of new Set(usable.map((s) => s.provider))) {
@@ -8516,12 +8553,12 @@ function computeBuckets(snapshots, projectRuns, bucketDays, queryCreatedAt, ment
       buckets.push({
         startDate: startISO,
         endDate: endISO,
-        citationRate: metric.citationRate,
-        cited: metric.cited,
-        total: metric.total,
+        citationRate: metric2.citationRate,
+        cited: metric2.cited,
+        total: metric2.total,
         queryCount,
-        mentionRate: metric.mentionRate,
-        mentionedCount: metric.mentionedCount,
+        mentionRate: metric2.mentionRate,
+        mentionedCount: metric2.mentionedCount,
         mentionShare: computeMentionShareBucketMetric(usable, mentionShareCompetitors),
         byProvider
       });
@@ -11272,6 +11309,7 @@ function renderServerActivity(report, audience) {
     if (!copy) return "";
     return `<span class="tone-${deltaTone(d.deltaPct)}">${escapeHtml(copy)}</span>`;
   };
+  const referralSubtitle = [formatDelta(sa.referralArrivals, "sessions"), escapeHtml(sa.referralArrivalsClassSummary)].filter(Boolean).join(" \xB7 ");
   if (isClient) {
     const crawlerRequests = {
       current: sa.verifiedCrawlerHits.current + sa.unverifiedCrawlerHits.current,
@@ -11310,7 +11348,7 @@ function renderServerActivity(report, audience) {
         <div class="metric">
           <div class="label">AI referral sessions</div>
           <div class="value">${formatNumber(sa.referralArrivals.current)}</div>
-          <div class="subtitle">${formatDelta(sa.referralArrivals, "sessions")}</div>
+          <div class="subtitle">${referralSubtitle}</div>
         </div>
       </div>
       ${clientOperatorRows ? `<div class="chart-card"><h3>By AI tool</h3>
@@ -11379,7 +11417,7 @@ function renderServerActivity(report, audience) {
       <div class="metric">
         <div class="label">AI-referral sessions (${windowLabel})</div>
         <div class="value">${formatNumber(sa.referralArrivals.current)}</div>
-        <div class="subtitle">${formatDelta(sa.referralArrivals, "sessions")}</div>
+        <div class="subtitle">${referralSubtitle}</div>
       </div>
     </div>
     ${trendChart}
@@ -11905,7 +11943,7 @@ function safeNum(value) {
   return 0;
 }
 function isPaidAiTrafficClass(value) {
-  return value === GA4AiReferralTrafficClasses.paid;
+  return value === AiReferralTrafficClasses.paid;
 }
 function categorizeQuery(query, projectBrandNames, canonicalDomain) {
   return categorizeQueryByIntent(query, buildBrandTokens(canonicalDomain, projectBrandNames));
@@ -12298,16 +12336,21 @@ function buildServerActivity(db, projectId, windowDays) {
       )
     ).get()?.total ?? 0
   );
-  const sumReferrals = (windowStartIso, windowEndIso, exclusiveEnd = false) => Number(
-    db.select({ total: sql7`COALESCE(SUM(${aiReferralEventsHourly.sessionsOrHits}), 0)` }).from(aiReferralEventsHourly).where(
+  const sumReferrals = (windowStartIso, windowEndIso, exclusiveEnd = false) => {
+    const row = db.select({
+      total: sql7`COALESCE(SUM(${aiReferralEventsHourly.sessionsOrHits}), 0)`,
+      paid: sql7`COALESCE(SUM(${aiReferralEventsHourly.paidSessionsOrHits}), 0)`,
+      organic: sql7`COALESCE(SUM(${aiReferralEventsHourly.organicSessionsOrHits}), 0)`
+    }).from(aiReferralEventsHourly).where(
       and12(
         eq15(aiReferralEventsHourly.projectId, projectId),
         nonSubresourceReferralPathCondition(),
         gte2(aiReferralEventsHourly.tsHour, windowStartIso),
         exclusiveEnd ? lt(aiReferralEventsHourly.tsHour, windowEndIso) : lte(aiReferralEventsHourly.tsHour, windowEndIso)
       )
-    ).get()?.total ?? 0
-  );
+    ).get();
+    return aiReferralClassCounts(Number(row?.total ?? 0), Number(row?.paid ?? 0), Number(row?.organic ?? 0));
+  };
   const sumUserFetches = (windowStartIso, windowEndIso, exclusiveEnd = false) => Number(
     db.select({ total: sql7`COALESCE(SUM(${aiUserFetchEventsHourly.hits}), 0)` }).from(aiUserFetchEventsHourly).where(
       and12(
@@ -12505,7 +12548,7 @@ function buildServerActivity(db, projectId, windowDays) {
   return {
     windowStart: headlineStart,
     windowEnd: headlineEnd,
-    hasData: verifiedCurrent + unverifiedCurrent + userFetchCurrent + referralCurrent + verifiedPrior + unverifiedPrior + userFetchPrior + referralPrior > 0 || byOperator.length > 0 || topCrawledPaths.length > 0 || referralProducts.length > 0,
+    hasData: verifiedCurrent + unverifiedCurrent + userFetchCurrent + referralCurrent.total + verifiedPrior + unverifiedPrior + userFetchPrior + referralPrior.total > 0 || byOperator.length > 0 || topCrawledPaths.length > 0 || referralProducts.length > 0,
     verifiedCrawlerHits: {
       current: verifiedCurrent,
       prior: verifiedPrior,
@@ -12522,10 +12565,28 @@ function buildServerActivity(db, projectId, windowDays) {
       deltaPct: deltaPercent(userFetchCurrent, userFetchPrior)
     },
     referralArrivals: {
-      current: referralCurrent,
-      prior: referralPrior,
-      deltaPct: deltaPercent(referralCurrent, referralPrior)
+      current: referralCurrent.total,
+      prior: referralPrior.total,
+      deltaPct: deltaPercent(referralCurrent.total, referralPrior.total)
+    },
+    referralArrivalsByClass: {
+      paid: {
+        current: referralCurrent.paid,
+        prior: referralPrior.paid,
+        deltaPct: deltaPercent(referralCurrent.paid, referralPrior.paid)
+      },
+      organic: {
+        current: referralCurrent.organic,
+        prior: referralPrior.organic,
+        deltaPct: deltaPercent(referralCurrent.organic, referralPrior.organic)
+      },
+      unclassified: {
+        current: referralCurrent.unknown,
+        prior: referralPrior.unknown,
+        deltaPct: deltaPercent(referralCurrent.unknown, referralPrior.unknown)
+      }
     },
+    referralArrivalsClassSummary: formatAiReferralClassSummary(referralCurrent),
     byOperator,
     topCrawledPaths,
     referralProducts,
@@ -13573,6 +13634,253 @@ function normalizeDomain2(domain) {
 
 // ../api-routes/src/visibility-stats.ts
 import { and as and14, desc as desc8, eq as eq17, inArray as inArray8 } from "drizzle-orm";
+
+// ../api-routes/src/visibility-compare.ts
+var VISIBILITY_COMPARE_MIN_RUNS = 5;
+function basketPairKey(queryId, provider) {
+  return JSON.stringify([queryId, provider]);
+}
+function citedHostMatches(citedHost, competitorHost) {
+  return citedHost === competitorHost || citedHost.endsWith(`.${competitorHost}`);
+}
+function restrict(snapshots, attribution, pairs) {
+  const out = [];
+  for (const snap of snapshots) {
+    const resolved = resolveCurrentQuery(attribution, snap);
+    if (!resolved) continue;
+    if (!pairs.has(basketPairKey(resolved.id, snap.provider))) continue;
+    out.push({ ...snap, queryId: resolved.id });
+  }
+  return out;
+}
+function observed(snapshots, attribution) {
+  const queryIds = /* @__PURE__ */ new Set();
+  const providers = /* @__PURE__ */ new Set();
+  for (const snap of snapshots) {
+    const resolved = resolveCurrentQuery(attribution, snap);
+    if (!resolved) continue;
+    queryIds.add(resolved.id);
+    providers.add(snap.provider);
+  }
+  return { queryIds, providers };
+}
+function observedPairs(snapshots, attribution, queryIds) {
+  const pairs = /* @__PURE__ */ new Map();
+  for (const snap of snapshots) {
+    const resolved = resolveCurrentQuery(attribution, snap);
+    if (!resolved || !queryIds.has(resolved.id)) continue;
+    const pair = { queryId: resolved.id, provider: snap.provider };
+    pairs.set(basketPairKey(pair.queryId, pair.provider), pair);
+  }
+  return pairs;
+}
+function period(numerator, denominator) {
+  const ci = wilsonInterval(numerator, denominator);
+  return {
+    point: denominator > 0 ? Math.round(numerator / denominator * 1e4) / 1e4 : null,
+    ciLow: ci ? ci.low : null,
+    ciHigh: ci ? ci.high : null,
+    numerator,
+    denominator
+  };
+}
+function ciOverlap(a, b) {
+  if (a.ciLow === null || a.ciHigh === null || b.ciLow === null || b.ciHigh === null) return true;
+  return a.ciLow <= b.ciHigh && b.ciLow <= a.ciHigh;
+}
+function metric(key, label, driftRobust, from, to, continuityBlock) {
+  const verdict = continuityBlock ?? (from.denominator === 0 || to.denominator === 0 ? "insufficient-data" : ciOverlap(from, to) ? "within-noise" : "moved");
+  const direction = from.point === null || to.point === null ? null : to.point > from.point ? "up" : to.point < from.point ? "down" : "flat";
+  const rateRatio = from.point === null || from.point === 0 || to.point === null ? null : Math.round(to.point / from.point * 100) / 100;
+  return { key, label, driftRobust, from, to, rateRatio, direction, verdict };
+}
+function countPeriod(snaps, competitors2) {
+  let checked = 0;
+  let mentioned = 0;
+  let cited = 0;
+  let competitorCited = 0;
+  const perProvider = /* @__PURE__ */ new Map();
+  const models = /* @__PURE__ */ new Map();
+  const modelUnknownProviders = /* @__PURE__ */ new Set();
+  const mentionedQueries = /* @__PURE__ */ new Set();
+  const competitorHosts = competitors2.map((c) => hostOf(c.domain)).filter((h) => h !== null && h.length > 0);
+  for (const snap of snaps) {
+    const isMentioned = snap.answerMentioned === true;
+    if (snap.answerMentioned === true || snap.answerMentioned === false) checked += 1;
+    if (isMentioned) {
+      mentioned += 1;
+      mentionedQueries.add(snap.queryId);
+    }
+    const isCited = snap.citationState === CitationStates.cited;
+    if (isCited) cited += 1;
+    const pp = perProvider.get(snap.provider) ?? { checked: 0, mentioned: 0, cited: 0 };
+    if (snap.answerMentioned === true || snap.answerMentioned === false) pp.checked += 1;
+    if (isMentioned) pp.mentioned += 1;
+    if (isCited) pp.cited += 1;
+    perProvider.set(snap.provider, pp);
+    if (snap.model) {
+      const set = models.get(snap.provider) ?? /* @__PURE__ */ new Set();
+      set.add(snap.model);
+      models.set(snap.provider, set);
+    } else {
+      modelUnknownProviders.add(snap.provider);
+    }
+    if (competitorHosts.length > 0 && snap.citedDomains.length > 0) {
+      const citedHosts = snap.citedDomains.map((d) => hostOf(d)).filter((h) => h !== null && h.length > 0);
+      for (const compHost of competitorHosts) {
+        if (citedHosts.some((ch) => citedHostMatches(ch, compHost))) competitorCited += 1;
+      }
+    }
+  }
+  const mentionShare = buildMentionShare(
+    snaps.map((s) => ({ projectMentioned: s.answerMentioned === true, answerText: s.answerText })),
+    { competitors: competitors2 }
+  );
+  return {
+    checked,
+    mentioned,
+    total: snaps.length,
+    cited,
+    projectCited: cited,
+    competitorCited,
+    queriesMentioned: mentionedQueries.size,
+    perProvider,
+    models,
+    modelUnknownProviders,
+    mentionShare,
+    competitors: mentionShare.breakdown.perCompetitor.map((c) => ({ domain: c.domain, mentions: c.mentionSnapshots }))
+  };
+}
+function computeVisibilityCompare(input) {
+  const attribution = buildQueryAttribution(input.queries);
+  const fromObs = observed(input.from.snapshots, attribution);
+  const toObs = observed(input.to.snapshots, attribution);
+  const queriesObservedBoth = new Set([...fromObs.queryIds].filter((q) => toObs.queryIds.has(q)));
+  const fromPairs = observedPairs(input.from.snapshots, attribution, queriesObservedBoth);
+  const toPairs = observedPairs(input.to.snapshots, attribution, queriesObservedBoth);
+  const pairsBoth = new Map([...fromPairs].filter(([key]) => toPairs.has(key)));
+  const candidateProviders = new Set([...pairsBoth.values()].map((pair) => pair.provider));
+  const fromCandidateSnaps = restrict(input.from.snapshots, attribution, pairsBoth);
+  const toCandidateSnaps = restrict(input.to.snapshots, attribution, pairsBoth);
+  const fromCandidateCounts = countPeriod(fromCandidateSnaps, input.competitors);
+  const toCandidateCounts = countPeriod(toCandidateSnaps, input.competitors);
+  const continuityProviders = [...candidateProviders].sort((a, b) => a.localeCompare(b)).map((provider) => {
+    const fromModels = [...fromCandidateCounts.models.get(provider) ?? /* @__PURE__ */ new Set()].sort((a, b) => a.localeCompare(b));
+    const toModels = [...toCandidateCounts.models.get(provider) ?? /* @__PURE__ */ new Set()].sort((a, b) => a.localeCompare(b));
+    const fromModelUnknown = fromCandidateCounts.modelUnknownProviders.has(provider) || fromModels.length === 0;
+    const toModelUnknown = toCandidateCounts.modelUnknownProviders.has(provider) || toModels.length === 0;
+    const status = fromModelUnknown || toModelUnknown ? "model-unknown" : fromModels.length === 1 && toModels.length === 1 && fromModels[0] === toModels[0] ? "included" : "model-discontinuous";
+    return { provider, status, fromModels, toModels };
+  });
+  const providersBoth = new Set(
+    continuityProviders.filter((provider) => provider.status === "included").map((provider) => provider.provider)
+  );
+  const continuityStatus = candidateProviders.size === 0 ? "insufficient-data" : providersBoth.size > 0 ? "comparable" : continuityProviders.every((provider) => provider.status === "model-unknown") ? "model-unknown" : "model-discontinuous";
+  const continuityBlock = continuityStatus === "model-discontinuous" || continuityStatus === "model-unknown" ? continuityStatus : null;
+  const comparedPairs = new Map([...pairsBoth].filter(([, pair]) => providersBoth.has(pair.provider)));
+  const queriesBoth = new Set([...comparedPairs.values()].map((pair) => pair.queryId));
+  const excludedProviders = [.../* @__PURE__ */ new Set([...fromObs.providers, ...toObs.providers])].filter((p) => !providersBoth.has(p)).sort((a, b) => a.localeCompare(b));
+  const fromSnaps = restrict(input.from.snapshots, attribution, comparedPairs);
+  const toSnaps = restrict(input.to.snapshots, attribution, comparedPairs);
+  const fromCounts = countPeriod(fromSnaps, input.competitors);
+  const toCounts = countPeriod(toSnaps, input.competitors);
+  const shareCounts = (c) => ({
+    proj: c.mentionShare.breakdown.projectMentionSnapshots,
+    comp: c.mentionShare.breakdown.competitorMentionSnapshots
+  });
+  const fromShare = shareCounts(fromCounts);
+  const toShare = shareCounts(toCounts);
+  const metrics = [
+    metric(
+      "mention-share-of-voice",
+      "Named share of voice",
+      true,
+      period(fromShare.proj, fromShare.proj + fromShare.comp),
+      period(toShare.proj, toShare.proj + toShare.comp),
+      continuityBlock
+    ),
+    // Share of voice is undefined without a competitive frame: with zero
+    // configured competitors the denominator degenerates to the project's own
+    // count and the metric would fabricate a 100%. buildMentionShare already
+    // refuses that on the mention side ("reporting 100% would mislead");
+    // degrade the cited side identically to a 0/0 period -> insufficient-data.
+    metric(
+      "cited-share-of-voice",
+      "Cited share of voice",
+      true,
+      input.competitors.length > 0 ? period(fromCounts.projectCited, fromCounts.projectCited + fromCounts.competitorCited) : period(0, 0),
+      input.competitors.length > 0 ? period(toCounts.projectCited, toCounts.projectCited + toCounts.competitorCited) : period(0, 0),
+      continuityBlock
+    ),
+    metric(
+      "mention-rate",
+      "Named rate",
+      false,
+      period(fromCounts.mentioned, fromCounts.checked),
+      period(toCounts.mentioned, toCounts.checked),
+      continuityBlock
+    ),
+    metric(
+      "cited-rate",
+      "Cited rate",
+      false,
+      period(fromCounts.cited, fromCounts.total),
+      period(toCounts.cited, toCounts.total),
+      continuityBlock
+    )
+  ];
+  const modelChanges = [...candidateProviders].sort((a, b) => a.localeCompare(b)).map((provider) => {
+    const fromModels = [...fromCandidateCounts.models.get(provider) ?? /* @__PURE__ */ new Set()].sort((a, b) => a.localeCompare(b));
+    const toModels = [...toCandidateCounts.models.get(provider) ?? /* @__PURE__ */ new Set()].sort((a, b) => a.localeCompare(b));
+    return { provider, fromModels, toModels };
+  }).filter(
+    (c) => c.fromModels.length > 0 && c.toModels.length > 0 && JSON.stringify(c.fromModels) !== JSON.stringify(c.toModels)
+  );
+  const byProvider = [...providersBoth].sort((a, b) => a.localeCompare(b)).map((provider) => ({
+    provider,
+    from: fromCounts.perProvider.get(provider) ?? { checked: 0, mentioned: 0, cited: 0 },
+    to: toCounts.perProvider.get(provider) ?? { checked: 0, mentioned: 0, cited: 0 }
+  }));
+  return {
+    project: input.project,
+    from: {
+      month: input.from.month,
+      since: input.from.since,
+      until: input.from.until,
+      runCount: input.from.runCount,
+      lowRunCount: input.from.runCount < VISIBILITY_COMPARE_MIN_RUNS
+    },
+    to: {
+      month: input.to.month,
+      since: input.to.since,
+      until: input.to.until,
+      runCount: input.to.runCount,
+      lowRunCount: input.to.runCount < VISIBILITY_COMPARE_MIN_RUNS
+    },
+    basket: {
+      queryCount: queriesBoth.size,
+      excludedFromOnly: [...fromObs.queryIds].filter((q) => !queriesBoth.has(q)).length,
+      excludedToOnly: [...toObs.queryIds].filter((q) => !queriesBoth.has(q)).length,
+      providers: [...providersBoth].sort((a, b) => a.localeCompare(b)),
+      excludedProviders
+    },
+    metrics,
+    queriesMentioned: {
+      from: { count: fromCounts.queriesMentioned, of: queriesBoth.size },
+      to: { count: toCounts.queriesMentioned, of: queriesBoth.size }
+    },
+    byProvider,
+    modelChanges,
+    continuity: {
+      status: continuityStatus,
+      comparedProviders: [...providersBoth].sort((a, b) => a.localeCompare(b)),
+      providers: continuityProviders
+    },
+    competitors: { from: fromCounts.competitors, to: toCounts.competitors }
+  };
+}
+
+// ../api-routes/src/visibility-stats.ts
 function round42(value) {
   return Math.round(value * 1e4) / 1e4;
 }
@@ -13791,6 +14099,62 @@ async function visibilityStatsRoutes(app) {
     };
     return reply.send(response);
   });
+  app.get("/projects/:name/visibility-compare", async (request, reply) => {
+    const project = resolveProject(app.db, request.params.name);
+    const { from: fromRaw, to: toRaw } = request.query;
+    if (fromRaw === void 0 || fromRaw === "") throw validationError('"from" (YYYY-MM) is required');
+    if (toRaw === void 0 || toRaw === "") throw validationError('"to" (YYYY-MM) is required');
+    let fromBounds;
+    let toBounds;
+    try {
+      fromBounds = calendarMonthBounds(fromRaw);
+    } catch (err) {
+      throw validationError(err instanceof RangeError ? `"from": ${err.message}` : '"from" must be in YYYY-MM format');
+    }
+    try {
+      toBounds = calendarMonthBounds(toRaw);
+    } catch (err) {
+      throw validationError(err instanceof RangeError ? `"to": ${err.message}` : '"to" must be in YYYY-MM format');
+    }
+    if (Date.parse(fromBounds.since) >= Date.parse(toBounds.since)) {
+      throw validationError('"from" must be a month strictly before "to"');
+    }
+    const projectQueries = app.db.select({ id: queries.id, query: queries.query }).from(queries).where(eq17(queries.projectId, project.id)).all();
+    const competitorRows = app.db.select({ domain: competitors.domain }).from(competitors).where(eq17(competitors.projectId, project.id)).all();
+    const competitorInputs = competitorRows.map((c) => ({
+      domain: c.domain,
+      brandTokens: [brandLabelFromDomain(c.domain)].filter((t) => t.length >= 3)
+    }));
+    const loadMonth = (bounds) => {
+      const sinceMs = Date.parse(bounds.since);
+      const untilMs = Date.parse(bounds.until);
+      const monthRuns = app.db.select({ id: runs.id, createdAt: runs.createdAt, status: runs.status }).from(runs).where(and14(eq17(runs.projectId, project.id), eq17(runs.kind, RunKinds["answer-visibility"]), notProbeRun())).all().filter(
+        (r) => (r.status === RunStatuses.completed || r.status === RunStatuses.partial) && Date.parse(r.createdAt) >= sinceMs && Date.parse(r.createdAt) <= untilMs
+      );
+      const runIds = monthRuns.map((r) => r.id);
+      const snapshots = runIds.length > 0 && projectQueries.length > 0 ? app.db.select({
+        queryId: querySnapshots.queryId,
+        queryText: querySnapshots.queryText,
+        provider: querySnapshots.provider,
+        model: querySnapshots.model,
+        citationState: querySnapshots.citationState,
+        answerMentioned: querySnapshots.answerMentioned,
+        answerText: querySnapshots.answerText,
+        citedDomains: querySnapshots.citedDomains
+      }).from(querySnapshots).where(inArray8(querySnapshots.runId, runIds)).all() : [];
+      return { runCount: monthRuns.length, snapshots };
+    };
+    const fromMonth = loadMonth(fromBounds);
+    const toMonth = loadMonth(toBounds);
+    const dto = computeVisibilityCompare({
+      project: project.name,
+      queries: projectQueries,
+      competitors: competitorInputs,
+      from: { month: fromRaw, since: fromBounds.since, until: fromBounds.until, runCount: fromMonth.runCount, snapshots: fromMonth.snapshots },
+      to: { month: toRaw, since: toBounds.since, until: toBounds.until, runCount: toMonth.runCount, snapshots: toMonth.snapshots }
+    });
+    return reply.send(dto);
+  });
 }
 
 // ../api-routes/src/composites.ts
@@ -14596,6 +14960,7 @@ var SCHEMA_TABLE = {
   TrafficSourceListResponse: trafficSourceListResponseSchema,
   TrafficStatusResponse: trafficStatusResponseSchema,
   TrafficSyncResponse: trafficSyncResponseSchema,
+  VisibilityCompareDto: visibilityCompareDtoSchema,
   VisibilityStatsDto: visibilityStatsDtoSchema,
   WordpressAuditPageDto: wordpressAuditPageDtoSchema,
   WordpressBulkMetaResultDto: wordpressBulkMetaResultDtoSchema,
@@ -14872,6 +15237,20 @@ var monthQueryParameter = {
   description: `Aggregate a single calendar month (YYYY-MM), expanded to that month's inclusive UTC bounds. Mutually exclusive with "since"/"until"/"lastRuns".`,
   schema: stringSchema
 };
+var compareFromQueryParameter = {
+  name: "from",
+  in: "query",
+  required: true,
+  description: 'Earlier calendar month (YYYY-MM) \u2014 the baseline period. Must be strictly before "to".',
+  schema: stringSchema
+};
+var compareToQueryParameter = {
+  name: "to",
+  in: "query",
+  required: true,
+  description: 'Later calendar month (YYYY-MM) \u2014 the reporting period compared against "from".',
+  schema: stringSchema
+};
 var shareOfVoiceQueryParameter = {
   name: "shareOfVoice",
   in: "query",
@@ -15647,6 +16026,19 @@ var routeCatalog = [
       404: errorResponse("Project not found.")
     }
   },
+  {
+    method: "get",
+    path: "/api/v1/projects/{name}/visibility-compare",
+    summary: "Compare AEO visibility month over month",
+    description: "Statistically honest month-over-month AEO comparison in one call. PRIMARY metric is share of voice (brand vs competitor mentions in the same answers), which is less exposed to broad model-wide naming propensity than an absolute rate but never bypasses model continuity. Rates are pooled per-snapshot over each month (invariant to sweep count), restricted to query/provider pairs present in BOTH months, and then restricted again to providers with exactly one known, identical configured model id in both months. `continuity` reports every provider and its model evidence; changed, mixed mid-month, or legacy-unknown models are excluded. When no provider remains, metrics return a continuity-blocked verdict rather than a directional call. `from` must be a month strictly before `to`. A silent upstream version bump under an unchanged configured id remains undetectable.",
+    tags: ["analytics"],
+    parameters: [nameParameter, compareFromQueryParameter, compareToQueryParameter],
+    responses: {
+      200: jsonResponse("Month-over-month visibility comparison returned.", "VisibilityCompareDto"),
+      400: errorResponse("Invalid or missing from/to months."),
+      404: errorResponse("Project not found.")
+    }
+  },
   {
     method: "get",
     path: "/api/v1/projects/{name}/snapshots/diff",
@@ -19458,12 +19850,12 @@ function computeWindowDelta(rows, referenceDate) {
   }
   const deltaPct = {};
   const metrics = /* @__PURE__ */ new Set([...Object.keys(recent7d), ...Object.keys(prior7d)]);
-  for (const metric of metrics) {
-    const recent = recent7d[metric] ?? 0;
-    const prior = prior7d[metric] ?? 0;
-    recent7d[metric] = recent;
-    prior7d[metric] = prior;
-    deltaPct[metric] = prior === 0 ? null : Math.round((recent - prior) / prior * 100);
+  for (const metric2 of metrics) {
+    const recent = recent7d[metric2] ?? 0;
+    const prior = prior7d[metric2] ?? 0;
+    recent7d[metric2] = recent;
+    prior7d[metric2] = prior;
+    deltaPct[metric2] = prior === 0 ? null : Math.round((recent - prior) / prior * 100);
   }
   return { recent7d, prior7d, deltaPct };
 }
@@ -20551,7 +20943,7 @@ async function fetchAiReferrals(accessToken, propertyId, days) {
           date: row.dimensionValues[0].value,
           source,
           medium,
-          trafficClass: classifyGa4AiReferralTrafficClass({ source, medium, channelGroup, landingPage }),
+          trafficClass: classifyAiReferralTrafficClass({ source, medium, channelGroup, landingPage }),
           channelGroup,
           landingPage,
           sessions: parseInt(row.metricValues[0].value, 10) || 0,
@@ -23527,7 +23919,7 @@ function pickWinningDimension(rows, tupleKey) {
   return [...winners.values()].sort((a, b) => (b.sessions ?? 0) - (a.sessions ?? 0));
 }
 function normalizeAiTrafficClass(value) {
-  return value === GA4AiReferralTrafficClasses.paid ? GA4AiReferralTrafficClasses.paid : GA4AiReferralTrafficClasses.organic;
+  return value === AiReferralTrafficClasses.paid ? AiReferralTrafficClasses.paid : AiReferralTrafficClasses.organic;
 }
 function emptyAiCounts() {
   return { sessions: 0, users: 0 };
@@ -23540,7 +23932,7 @@ function summarizeAiReferralCounts(rows) {
   const paidBySession = emptyAiCounts();
   const organicBySession = emptyAiCounts();
   for (const row of rows) {
-    const isPaid = normalizeAiTrafficClass(row.trafficClass) === GA4AiReferralTrafficClasses.paid;
+    const isPaid = normalizeAiTrafficClass(row.trafficClass) === AiReferralTrafficClasses.paid;
     const sessions = row.sessions ?? 0;
     const users = row.users ?? 0;
     const key = `${row.date}\0${row.source}\0${row.medium}`;
@@ -23872,7 +24264,7 @@ async function ga4Routes(app, opts) {
               date: row.date,
               source: row.source,
               medium: row.medium,
-              trafficClass: row.trafficClass ?? classifyGa4AiReferralTrafficClass({
+              trafficClass: row.trafficClass ?? classifyAiReferralTrafficClass({
                 source: row.source,
                 medium: row.medium,
                 channelGroup: row.channelGroup,
@@ -29650,6 +30042,33 @@ function utmSourceFromUrl(value) {
     return null;
   }
 }
+function paramsFromQuery(queryString) {
+  if (!queryString) return null;
+  const params = new URLSearchParams(queryString);
+  return [...params.keys()].length > 0 ? params : null;
+}
+function paramsFromUrl(value) {
+  if (!value) return null;
+  try {
+    return paramsFromQuery(new URL(value).search.replace(/^\?/, ""));
+  } catch {
+    return null;
+  }
+}
+function classifyAiReferralTrafficClassFromEvent(event) {
+  for (const params of [paramsFromQuery(event.queryString), paramsFromUrl(event.referer)]) {
+    if (!params) continue;
+    const trafficClass = classifyAiReferralTrafficClass({
+      source: params.get("utm_source"),
+      medium: params.get("utm_medium"),
+      channelGroup: null,
+      // Carries utm_campaign / utm_content / utm_term to the shared rules.
+      landingPage: `/?${params.toString()}`
+    });
+    if (trafficClass === AiReferralTrafficClasses.paid) return AiReferralTrafficClasses.paid;
+  }
+  return AiReferralTrafficClasses.organic;
+}
 function isSelfTraffic(event) {
   const userAgent = event.userAgent?.trim();
   if (!userAgent) return false;
@@ -29693,6 +30112,7 @@ function classifyAiUserFetch(event) {
   return null;
 }
 function classifyAiReferral(event) {
+  const trafficClass = classifyAiReferralTrafficClassFromEvent(event);
   const refererHost = hostFromUrl(event.referer);
   if (refererHost) {
     const rule = DEFAULT_AI_REFERRER_RULES.find((candidate) => hostMatches(refererHost, candidate.domain));
@@ -29701,7 +30121,8 @@ function classifyAiReferral(event) {
         operator: rule.operator,
         product: rule.product,
         sourceDomain: refererHost,
-        evidenceType: "referer"
+        evidenceType: "referer",
+        trafficClass
       };
     }
   }
@@ -29713,7 +30134,8 @@ function classifyAiReferral(event) {
         operator: rule.operator,
         product: rule.product,
         sourceDomain: utmSource,
-        evidenceType: "utm"
+        evidenceType: "utm",
+        trafficClass
       };
     }
   }
@@ -29725,7 +30147,8 @@ function classifyAiReferral(event) {
         operator: rule.operator,
         product: rule.product,
         sourceDomain: refererUtmSource,
-        evidenceType: "referer-utm"
+        evidenceType: "referer-utm",
+        trafficClass
       };
     }
   }
@@ -29828,8 +30251,10 @@ function evidenceRank(evidenceType) {
       return 1;
   }
 }
-function strongerReferralEvidence(current, next) {
-  return evidenceRank(next.evidenceType) > evidenceRank(current.evidenceType) ? next : current;
+function mergeReferralSession(current, next) {
+  const winner = evidenceRank(next.evidenceType) > evidenceRank(current.evidenceType) ? next : current;
+  const paid = current.trafficClass === AiReferralTrafficClasses.paid || next.trafficClass === AiReferralTrafficClasses.paid;
+  return { ...winner, trafficClass: paid ? AiReferralTrafficClasses.paid : winner.trafficClass };
 }
 function sortCrawlerBuckets(a, b) {
   return a.tsHour.localeCompare(b.tsHour) || a.botId.localeCompare(b.botId) || a.pathNormalized.localeCompare(b.pathNormalized) || String(a.status).localeCompare(String(b.status));
@@ -29862,6 +30287,8 @@ function buildTrafficProbeReport(events, options = {}) {
   let crawlerHits = 0;
   let aiUserFetchHits = 0;
   let aiReferralHits = 0;
+  let aiReferralPaidSessions = 0;
+  let aiReferralOrganicSessions = 0;
   let unknownHits = 0;
   const samples = [];
   for (const event of includedEvents) {
@@ -29943,11 +30370,12 @@ function buildTrafficProbeReport(events, options = {}) {
           sourceDomain: aiReferral.sourceDomain,
           evidenceType: aiReferral.evidenceType,
           landingPathNormalized,
-          status: event.status
+          status: event.status,
+          trafficClass: aiReferral.trafficClass
         };
         const key = aiReferralSessionKey(event, aiReferral, landingPathNormalized, aiReferralSessionWindowMs);
         const existing = aiReferralSessions.get(key);
-        aiReferralSessions.set(key, existing ? strongerReferralEvidence(existing, session) : session);
+        aiReferralSessions.set(key, existing ? mergeReferralSession(existing, session) : session);
       }
     }
     if (!crawler && !aiUserFetch && !aiReferral) unknownHits += 1;
@@ -29975,13 +30403,21 @@ function buildTrafficProbeReport(events, options = {}) {
       session.landingPathNormalized,
       session.status ?? "null"
     ].join("	");
+    const { trafficClass, ...bucketFields } = session;
+    const paid = trafficClass === AiReferralTrafficClasses.paid;
+    if (paid) aiReferralPaidSessions += 1;
+    else aiReferralOrganicSessions += 1;
     const existing = aiReferralBuckets.get(key);
     if (existing) {
       existing.hits += 1;
+      if (paid) existing.paidHits += 1;
+      else existing.organicHits += 1;
     } else {
       aiReferralBuckets.set(key, {
-        ...session,
-        hits: 1
+        ...bucketFields,
+        hits: 1,
+        paidHits: paid ? 1 : 0,
+        organicHits: paid ? 0 : 1
       });
     }
     incrementBucket(topAiReferrers, session.sourceDomain, {
@@ -30000,6 +30436,8 @@ function buildTrafficProbeReport(events, options = {}) {
       crawlerHits,
       aiUserFetchHits,
       aiReferralSessions: aiReferralSessions.size,
+      aiReferralPaidSessions,
+      aiReferralOrganicSessions,
       aiReferralHits,
       unknownHits
     },
@@ -30761,6 +31199,8 @@ async function runBackfillTask(options) {
           landingPathNormalized: bucket.landingPathNormalized,
           status: bucket.status ?? 0,
           sessionsOrHits: bucket.hits,
+          paidSessionsOrHits: bucket.paidHits,
+          organicSessionsOrHits: bucket.organicHits,
           usersEstimated: null,
           createdAt: finishedAt,
           updatedAt: finishedAt
@@ -31508,6 +31948,8 @@ async function trafficRoutes(app, opts) {
           landingPathNormalized: bucket.landingPathNormalized,
           status,
           sessionsOrHits: bucket.hits,
+          paidSessionsOrHits: bucket.paidHits,
+          organicSessionsOrHits: bucket.organicHits,
           usersEstimated: null,
           createdAt: finishedAt,
           updatedAt: finishedAt
@@ -31522,8 +31964,13 @@ async function trafficRoutes(app, opts) {
             aiReferralEventsHourly.landingPathNormalized,
             aiReferralEventsHourly.status
           ],
+          // All three counters accumulate. The class splits the measure, so a
+          // colliding bucket adds its paid and organic arrivals to the ones
+          // already there rather than overwriting a single label.
           set: {
             sessionsOrHits: sql12`${aiReferralEventsHourly.sessionsOrHits} + ${bucket.hits}`,
+            paidSessionsOrHits: sql12`${aiReferralEventsHourly.paidSessionsOrHits} + ${bucket.paidHits}`,
+            organicSessionsOrHits: sql12`${aiReferralEventsHourly.organicSessionsOrHits} + ${bucket.organicHits}`,
             updatedAt: finishedAt
           }
         }).run();
@@ -31975,7 +32422,7 @@ async function trafficRoutes(app, opts) {
     let crawlerTotal = 0;
     let crawlerSegments = { content: 0, sitemap: 0, robots: 0, asset: 0, other: 0 };
     let aiUserFetchTotal = 0;
-    let aiReferralTotal = 0;
+    let aiReferralCounts = aiReferralClassCounts(0, 0, 0);
     if (kind === "all" || kind === TrafficEventKinds.crawler) {
       const crawlerFilters = [
         eq28(crawlerEventsHourly.projectId, project.id),
@@ -32041,10 +32488,19 @@ async function trafficRoutes(app, opts) {
       ];
       if (sourceIdParam) aiFilters.push(eq28(aiReferralEventsHourly.sourceId, sourceIdParam));
       const aiWhere = and24(...aiFilters);
-      const total = app.db.select({ total: sql12`COALESCE(SUM(${aiReferralEventsHourly.sessionsOrHits}), 0)` }).from(aiReferralEventsHourly).where(aiWhere).get();
-      aiReferralTotal = Number(total?.total ?? 0);
+      const total = app.db.select({
+        total: sql12`COALESCE(SUM(${aiReferralEventsHourly.sessionsOrHits}), 0)`,
+        paid: sql12`COALESCE(SUM(${aiReferralEventsHourly.paidSessionsOrHits}), 0)`,
+        organic: sql12`COALESCE(SUM(${aiReferralEventsHourly.organicSessionsOrHits}), 0)`
+      }).from(aiReferralEventsHourly).where(aiWhere).get();
+      aiReferralCounts = aiReferralClassCounts(
+        Number(total?.total ?? 0),
+        Number(total?.paid ?? 0),
+        Number(total?.organic ?? 0)
+      );
       const rows = app.db.select().from(aiReferralEventsHourly).where(aiWhere).orderBy(desc15(aiReferralEventsHourly.tsHour)).limit(limit).all();
       for (const r of rows) {
+        const counts2 = aiReferralClassCounts(r.sessionsOrHits, r.paidSessionsOrHits, r.organicSessionsOrHits);
         events.push({
           kind: TrafficEventKinds["ai-referral"],
           sourceId: r.sourceId,
@@ -32055,7 +32511,10 @@ async function trafficRoutes(app, opts) {
           evidenceType: r.evidenceType,
           landingPathNormalized: r.landingPathNormalized,
           status: r.status,
-          hits: r.sessionsOrHits
+          hits: counts2.total,
+          paidHits: counts2.paid,
+          organicHits: counts2.organic,
+          unknownHits: counts2.unknown
         });
       }
     }
@@ -32070,7 +32529,10 @@ async function trafficRoutes(app, opts) {
         crawlerInfraHits: sumInfraHits(crawlerSegments),
         crawlerSegments,
         aiUserFetchHits: aiUserFetchTotal,
-        aiReferralHits: aiReferralTotal
+        aiReferralHits: aiReferralCounts.total,
+        aiReferralPaidHits: aiReferralCounts.paid,
+        aiReferralOrganicHits: aiReferralCounts.organic,
+        aiReferralUnknownHits: aiReferralCounts.unknown
       },
       events: trimmed
     };