@canonry/canonry 5.20.4 → 5.21.0

package/dist/{chunk-NSKFW3NF.js → chunk-FAVYLZQV.js}

@@ -417,6 +417,7 @@ import {
   isTemplateLinkRatio,
   isTrendBaseline,
   isVertexGroundingRedirect,
+  isVisibilityCompareClassMetric,
   isoDateDaysBeforeInTimeZone,
   keywordDtoSchema,
   keywordGenerateRequestSchema,
@@ -771,6 +772,7 @@ import {
   userListDtoSchema,
   validationError,
   visibilityCompareDtoSchema,
+  visibilityCompareSelectionSchema,
   visibilityReportQuerySchema,
   visibilityReportResponseSchema,
   visibilityStateFromAnswerMentioned,
@@ -792,7 +794,7 @@ import {
   wordpressSchemaDeployResultDtoSchema,
   wordpressSchemaStatusResultDtoSchema,
   wordpressStatusDtoSchema
-} from "./chunk-TOSPZ7I5.js";
+} from "./chunk-2LO7FLVD.js";
 
 // src/intelligence-service.ts
 import { eq as eq71, desc as desc32, asc as asc12, and as and60, ne as ne11, or as or18, inArray as inArray27, gte as gte18, lte as lte15, isNull as isNull13, sql as sql28, exists } from "drizzle-orm";
@@ -16046,6 +16048,17 @@ function modelEvidenceStatesEqual(a, b) {
   if (a.status !== "mixed" || b.status !== "mixed") return false;
   return a.includesUnknown === b.includesUnknown && a.models.length === b.models.length && a.models.every((model, index2) => model === b.models[index2]);
 }
+function compareModelContinuity(from, to) {
+  const fromEvidence = classifyModelEvidence(from);
+  const toEvidence = classifyModelEvidence(to);
+  const ids = (evidence) => evidence.status === "known" ? [evidence.model] : evidence.status === "mixed" ? evidence.models : [];
+  const unknown = (evidence) => evidence.status === "unknown" || evidence.status === "mixed" && evidence.includesUnknown;
+  return {
+    status: unknown(fromEvidence) || unknown(toEvidence) ? "model-unknown" : fromEvidence.status === "known" && toEvidence.status === "known" && fromEvidence.model === toEvidence.model ? "included" : "model-discontinuous",
+    fromModels: ids(fromEvidence),
+    toModels: ids(toEvidence)
+  };
+}
 
 // ../api-routes/src/competitor-landscape.ts
 var COMPETITOR_LANDSCAPE_RANKED_ROW_LIMIT = 100;
@@ -24412,6 +24425,50 @@ function buildVisibilityReport(input) {
     populations
   });
 }
+function visibilityComparisonPopulation(run, selection) {
+  const targets = targetMap(run.definition);
+  const byClass = ALL_CLASSES.map((queryClass) => ({ queryClass, candidates: candidatesFor(run, selection, queryClass).candidates }));
+  const pooled = /* @__PURE__ */ new Map();
+  for (const { candidates } of byClass) {
+    for (const candidate of candidates) {
+      const existing = pooled.get(candidate.slot.id);
+      if (existing) existing.edges.push(...candidate.edges);
+      else pooled.set(candidate.slot.id, { ...candidate, edges: [...candidate.edges] });
+    }
+  }
+  const cohortKeys = new Map([...pooled.values()].map((candidate) => [candidate.slot.id, JSON.stringify({
+    definition: run.comparableDefinitionIds.at(-1) ?? run.definitionId,
+    query: candidate.slot.query,
+    execution: candidate.slot.executionId,
+    location: candidate.slot.location,
+    edges: candidate.edges.map((edge) => [edge.targetKey, edge.queryClass, [...edge.marketKeys].sort()]).sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)))
+  })]));
+  const row = (candidate, queryClass) => {
+    const signals = targetValues(candidate, targets);
+    return {
+      queryId: candidate.slot.queryId ?? candidate.slot.queryKey,
+      queryText: candidate.slot.query,
+      provider: candidate.slot.provider,
+      model: candidate.observation.model,
+      answerMentioned: signals.mention,
+      mentionApplicable: candidate.edges.some((edge) => targets.get(edge.targetKey)?.mentionEligible === true),
+      citation: citationForCoverage(candidate, targets),
+      answerText: candidate.observation.answerText,
+      competitorDomains: [...new Set(candidate.edges.flatMap((edge) => edge.competitorDomains))],
+      competitorMentions: candidate.observation.competitorMentionDomains.filter((domain) => candidate.edges.some((edge) => edge.competitorDomains.includes(domain))),
+      competitorCitations: candidate.observation.competitorCitationDomains.filter((domain) => candidate.edges.some((edge) => edge.competitorDomains.includes(domain))),
+      cohortKey: cohortKeys.get(candidate.slot.id),
+      queryClass: queryClass === "unknown" ? null : queryClass
+    };
+  };
+  return {
+    snapshots: [...pooled.values()].filter((candidate) => candidate.observation !== null).map((candidate) => {
+      const classes = new Set(candidate.edges.map((edge) => edge.queryClass));
+      return row(candidate, classes.size === 1 ? candidate.edges[0].queryClass : null);
+    }),
+    classSnapshots: byClass.flatMap(({ queryClass, candidates }) => candidates.filter((candidate) => candidate.observation !== null).map((candidate) => row(candidate, queryClass)))
+  };
+}
 
 // ../api-routes/src/visibility-report.ts
 function normalizedText3(value) {
@@ -24928,6 +24985,13 @@ function comparableVersionIds(rows, versionId) {
   }
   return ids;
 }
+function comparableChainHeads(rows, rowsById) {
+  const heads = /* @__PURE__ */ new Map();
+  for (const row of [...rows].sort((left, right) => left.revision - right.revision)) {
+    for (const id of comparableVersionIds(rowsById, row.id)) heads.set(id, row.id);
+  }
+  return heads;
+}
 function assignmentSignature(plan, assignment) {
   const node = plan.executionNodes.find((candidate) => candidate.stableKey === assignment.executionNodeKey);
   if (!node) throw new Error(`Frozen assignment references missing execution node ${assignment.executionNodeKey}`);
@@ -25082,6 +25146,37 @@ async function visibilityReportRoutes(app) {
     async (request) => readVisibilityReport(app.db, resolveProject(app.db, request.params.name), request.query)
   );
 }
+function readVisibilityComparisonRuns(db, projectId, since, until) {
+  const sourceRuns = db.select().from(runs).where(and21(
+    eq26(runs.projectId, projectId),
+    eq26(runs.kind, RunKinds["answer-visibility"]),
+    inArray10(runs.status, [RunStatuses.completed, RunStatuses.partial]),
+    notProbeRun(),
+    isNotNull(runs.measurementPlanVersionId),
+    isNull5(runs.measurementScope),
+    gte4(runs.createdAt, since),
+    lte4(runs.createdAt, until)
+  )).all();
+  const versionRows = db.select().from(measurementPlanVersions).where(eq26(measurementPlanVersions.projectId, projectId)).all();
+  const rowsById = new Map(versionRows.map((version) => [version.id, version]));
+  const versions = parseV2Versions(versionRows);
+  const heads = comparableChainHeads(versionRows, rowsById);
+  const byRun = loadVisibilitySnapshots(db, sourceRuns.map((run) => run.id));
+  let unavailable5 = false;
+  const selected = sourceRuns.flatMap((run) => {
+    const source = versions.get(run.measurementPlanVersionId);
+    if (!source) {
+      unavailable5 = true;
+      return [];
+    }
+    const presentation = versions.get(heads.get(source.row.id) ?? source.row.id) ?? source;
+    const snapshots = byRun.get(run.id) ?? [];
+    const models = new Map(snapshots.map((snapshot) => [snapshot.id, snapshot.model]));
+    const materialized = advancedRun(run, presentation.row, presentation.plan, snapshots, comparableVersionIds(rowsById, presentation.row.id));
+    return [{ ...materialized, observations: materialized.observations.map((observation) => ({ ...observation, model: models.get(observation.answerId) ?? null })) }];
+  });
+  return { runs: selected, unavailable: unavailable5 };
+}
 
 // ../api-routes/src/query-tracking.ts
 import crypto21 from "crypto";
@@ -34822,15 +34917,15 @@ import { and as and35, desc as desc18, eq as eq39, inArray as inArray18 } from "
 
 // ../api-routes/src/visibility-compare.ts
 var VISIBILITY_COMPARE_MIN_RUNS = 5;
-function basketPairKey(queryId, provider) {
-  return JSON.stringify([queryId, provider]);
+function basketPairKey(queryId, provider, cohortKey) {
+  return JSON.stringify([queryId, provider, cohortKey ?? null]);
 }
 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;
+    if (!pairs.has(basketPairKey(resolved.id, snap.provider, snap.cohortKey))) continue;
     out.push({ ...snap, queryId: resolved.id });
   }
   return out;
@@ -34851,8 +34946,8 @@ function observedPairs(snapshots, attribution, queryIds) {
   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);
+    const pair = { queryId: resolved.id, provider: snap.provider, cohortKey: snap.cohortKey };
+    pairs.set(basketPairKey(pair.queryId, pair.provider, pair.cohortKey), pair);
   }
   return pairs;
 }
@@ -34899,7 +34994,9 @@ function modelEvidenceOf(snaps) {
 function countPeriod(snaps, competitors2, queryClassOf, classificationAvailable, projectMatcher) {
   let checked = 0;
   let mentioned = 0;
+  let total = 0;
   let cited = 0;
+  let citationUnknown = 0;
   let competitorCited = 0;
   const perProvider = /* @__PURE__ */ new Map();
   const mentionedQueries = /* @__PURE__ */ new Set();
@@ -34911,21 +35008,26 @@ function countPeriod(snaps, competitors2, queryClassOf, classificationAvailable,
       mentioned += 1;
       mentionedQueries.add(snap.queryId);
     }
-    const isCited = snap.citationState === CitationStates.cited;
+    const citationKnown = snap.citationChecked !== false;
+    if (citationKnown) total += 1;
+    else citationUnknown += 1;
+    const isCited = citationKnown && 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 (competitorHosts.length > 0 && snap.citedDomains.length > 0) {
+    if (!citationKnown) continue;
+    if (snap.competitorCitations !== void 0) competitorCited += snap.competitorCitations.length;
+    else 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) => hostMatchesDomain(ch, compHost))) competitorCited += 1;
       }
     }
   }
-  const mentionShare = buildMentionShare(
+  let mentionShare = buildMentionShare(
     snaps.map((s) => ({
       // Share uses current identity; named-rate counts above deliberately keep
       // their historical persisted-boolean semantics.
@@ -34935,11 +35037,26 @@ function countPeriod(snaps, competitors2, queryClassOf, classificationAvailable,
     })),
     { competitors: competitors2, classificationAvailable }
   );
+  if (snaps.some((snapshot) => snapshot.competitorMentions !== void 0)) {
+    const selected = snaps.filter((snapshot) => (!classificationAvailable || queryClassOf(snapshot) === "non-brand") && snapshot.answerMentioned !== null);
+    const perCompetitor = competitors2.map((competitor) => ({
+      domain: competitor.domain,
+      mentionSnapshots: selected.filter((snapshot) => snapshot.competitorMentions?.includes(competitor.domain)).length
+    })).filter((row) => row.mentionSnapshots > 0).sort((a, b) => b.mentionSnapshots - a.mentionSnapshots || (a.domain < b.domain ? -1 : 1));
+    mentionShare = { ...mentionShare, breakdown: {
+      ...mentionShare.breakdown,
+      projectMentionSnapshots: selected.filter((snapshot) => snapshot.answerMentioned === true).length,
+      competitorMentionSnapshots: perCompetitor.reduce((total2, competitor) => total2 + competitor.mentionSnapshots, 0),
+      perCompetitor
+    } };
+  }
   return {
     checked,
     mentioned,
-    total: snaps.length,
+    total,
     cited,
+    citationUnknown,
+    citationEvidence: snaps.some((snapshot) => snapshot.citationChecked !== void 0),
     projectCited: cited,
     competitorCited,
     queriesMentioned: mentionedQueries.size,
@@ -34953,15 +35070,12 @@ function modelIds(evidence) {
   if (evidence.status === "mixed") return evidence.models;
   return [];
 }
-function isUnknownModelEvidence(evidence) {
-  return evidence.status === "unknown" || evidence.status === "mixed" && evidence.includesUnknown;
-}
 function computeVisibilityCompare(input) {
   const attribution = buildQueryAttribution(input.queries);
   const classifier = compileQueryClassifier(input.brandNames ?? []);
-  const classificationAvailable = classifier !== null;
+  const classificationAvailable = input.frozenClassification === true || classifier !== null;
   const queryTextById = new Map(input.queries.map((q) => [q.id, q.query]));
-  const queryClassOf = (snap) => classifier ? classifier.classify(queryTextById.get(snap.queryId) ?? snap.queryText) : null;
+  const queryClassOf = (snap) => input.frozenClassification ? snap.queryClass ?? null : classifier ? classifier.classify(queryTextById.get(snap.queryId) ?? snap.queryText) : null;
   const projectMatcher = compileBrandAliases(input.brandNames ?? []);
   const fromObs = observed(input.from.snapshots, attribution);
   const toObs = observed(input.to.snapshots, attribution);
@@ -34973,12 +35087,10 @@ function computeVisibilityCompare(input) {
   const fromCandidateModels = modelEvidenceOf(restrict(input.from.snapshots, attribution, pairsBoth));
   const toCandidateModels = modelEvidenceOf(restrict(input.to.snapshots, attribution, pairsBoth));
   const continuityProviders = [...candidateProviders].sort((a, b) => a.localeCompare(b)).map((provider) => {
-    const fromEvidence = classifyModelEvidence(fromCandidateModels.get(provider) ?? []);
-    const toEvidence = classifyModelEvidence(toCandidateModels.get(provider) ?? []);
-    const fromModels = modelIds(fromEvidence);
-    const toModels = modelIds(toEvidence);
-    const status = isUnknownModelEvidence(fromEvidence) || isUnknownModelEvidence(toEvidence) ? "model-unknown" : fromEvidence.status === "known" && toEvidence.status === "known" && fromEvidence.model === toEvidence.model ? "included" : "model-discontinuous";
-    return { provider, status, fromModels, toModels };
+    return { provider, ...compareModelContinuity(
+      fromCandidateModels.get(provider) ?? [],
+      toCandidateModels.get(provider) ?? []
+    ) };
   });
   const providersBoth = new Set(
     continuityProviders.filter((provider) => provider.status === "included").map((provider) => provider.provider)
@@ -34992,12 +35104,18 @@ function computeVisibilityCompare(input) {
   const toSnaps = restrict(input.to.snapshots, attribution, comparedPairs);
   const fromCounts = countPeriod(fromSnaps, input.competitors, queryClassOf, classificationAvailable, projectMatcher);
   const toCounts = countPeriod(toSnaps, input.competitors, queryClassOf, classificationAvailable, projectMatcher);
+  const fromClassSnaps = input.from.classSnapshots === void 0 ? fromSnaps : restrict(input.from.classSnapshots, attribution, comparedPairs);
+  const toClassSnaps = input.to.classSnapshots === void 0 ? toSnaps : restrict(input.to.classSnapshots, attribution, comparedPairs);
+  const noProjectMatcher = compileBrandAliases([]);
+  const fromShareCounts = input.frozenClassification ? countPeriod(fromClassSnaps, input.competitors, queryClassOf, true, noProjectMatcher) : fromCounts;
+  const toShareCounts = input.frozenClassification ? countPeriod(toClassSnaps, input.competitors, queryClassOf, true, noProjectMatcher) : toCounts;
   const shareCounts = (c) => ({
     proj: c.mentionShare.breakdown.projectMentionSnapshots,
     comp: c.mentionShare.breakdown.competitorMentionSnapshots
   });
-  const fromShare = shareCounts(fromCounts);
-  const toShare = shareCounts(toCounts);
+  const fromShare = shareCounts(fromShareCounts);
+  const toShare = shareCounts(toShareCounts);
+  const citationPeriod = (c, value) => c.citationEvidence ? { ...value, excludedUnknown: c.citationUnknown } : value;
   const metrics = [
     metric(
       "mention-share-of-voice",
@@ -35018,8 +35136,8 @@ function computeVisibilityCompare(input) {
       "Cited share of voice",
       "all",
       true,
-      input.competitors.length > 0 ? period(fromCounts.projectCited, fromCounts.projectCited + fromCounts.competitorCited) : unavailableCompetitivePeriod(fromCounts.projectCited),
-      input.competitors.length > 0 ? period(toCounts.projectCited, toCounts.projectCited + toCounts.competitorCited) : unavailableCompetitivePeriod(toCounts.projectCited),
+      citationPeriod(fromCounts, input.competitors.length > 0 ? period(fromCounts.projectCited, fromCounts.projectCited + fromCounts.competitorCited) : unavailableCompetitivePeriod(fromCounts.projectCited)),
+      citationPeriod(toCounts, input.competitors.length > 0 ? period(toCounts.projectCited, toCounts.projectCited + toCounts.competitorCited) : unavailableCompetitivePeriod(toCounts.projectCited)),
       continuityBlock
     ),
     metric(
@@ -35036,11 +35154,31 @@ function computeVisibilityCompare(input) {
       "Cited rate",
       "all",
       false,
-      period(fromCounts.cited, fromCounts.total),
-      period(toCounts.cited, toCounts.total),
+      citationPeriod(fromCounts, period(fromCounts.cited, fromCounts.total)),
+      citationPeriod(toCounts, period(toCounts.cited, toCounts.total)),
       continuityBlock
     )
   ];
+  const classPeriod = (snapshots, queryClass, signal) => {
+    if (!classificationAvailable) return { ...period(0, 0), availability: "classification-unavailable" };
+    const selected = snapshots.filter((snapshot) => queryClassOf(snapshot) === queryClass && (signal === "cited" || snapshot.mentionApplicable !== false));
+    const checked = selected.filter((snapshot) => signal === "mention" ? typeof snapshot.answerMentioned === "boolean" : snapshot.citationChecked !== false);
+    const numerator = checked.filter((snapshot) => signal === "mention" ? snapshot.answerMentioned === true : snapshot.citationState === CitationStates.cited).length;
+    return { ...period(numerator, checked.length), excludedUnknown: selected.length - checked.length };
+  };
+  for (const queryClass of ["branded", "non-brand"]) {
+    for (const signal of ["mention", "cited"]) {
+      metrics.push(metric(
+        `${signal}-rate-${queryClass}`,
+        signal === "mention" ? "Mention rate" : "Cited rate",
+        queryClass,
+        false,
+        classPeriod(fromClassSnaps, queryClass, signal),
+        classPeriod(toClassSnaps, queryClass, signal),
+        continuityBlock
+      ));
+    }
+  }
   const modelChanges = [...candidateProviders].sort((a, b) => a.localeCompare(b)).map((provider) => {
     const fromModels = modelIds(classifyModelEvidence(fromCandidateModels.get(provider) ?? []));
     const toModels = modelIds(classifyModelEvidence(toCandidateModels.get(provider) ?? []));
@@ -35088,7 +35226,7 @@ function computeVisibilityCompare(input) {
       comparedProviders: [...providersBoth].sort((a, b) => a.localeCompare(b)),
       providers: continuityProviders
     },
-    competitors: { from: fromCounts.competitors, to: toCounts.competitors }
+    competitors: { from: fromShareCounts.competitors, to: toShareCounts.competitors }
   };
 }
 
@@ -35306,59 +35444,150 @@ 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(eq39(queries.projectId, project.id)).all();
-    const competitorRows2 = app.db.select({ domain: competitors.domain }).from(competitors).where(eq39(competitors.projectId, project.id)).all();
-    const competitorInputs = mentionShareCompetitorsFromDomains(competitorRows2.map((c) => c.domain));
-    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(and35(eq39(runs.projectId, project.id), eq39(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(inArray18(querySnapshots.runId, runIds)).all() : [];
-      return { runCount: monthRuns.length, snapshots };
+    const dto = readVisibilityCompare(app.db, request.params.name, request.query);
+    return reply.send(dto);
+  });
+}
+function readVisibilityCompare(db, projectName, query) {
+  const project = resolveProject(db, projectName);
+  const selection = visibilityCompareSelectionSchema.safeParse(query);
+  if (!selection.success) throw validationError("Invalid comparison selection", { issues: selection.error.issues });
+  const filters = selection.data;
+  const scope = filters.scope ?? "project";
+  if (scope !== "project" && filters.scopeKey === void 0) throw validationError("A non-project comparison scope requires scopeKey.");
+  if (scope === "project" && filters.scopeKey !== void 0) throw validationError("scopeKey is not valid for project scope.");
+  if (scope === "market" && filters.marketKey !== void 0) throw validationError("marketKey is not valid for market scope.");
+  const { from: fromRaw, to: toRaw } = 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 providerKey2 = filters.provider === void 0 ? void 0 : normalizeText3(filters.provider);
+  const locationKey2 = filters.location === void 0 ? void 0 : normalizeText3(filters.location);
+  const scoped = scope !== "project" || filters.marketKey !== void 0;
+  let advancedComparison;
+  if (activeMeasurementPlan(db, project.id) !== null) {
+    let missingScope;
+    let measuredScope = 0;
+    const loadAdvancedMonth = (bounds) => {
+      const selected = readVisibilityComparisonRuns(db, project.id, bounds.since, bounds.until);
+      const snapshots = [];
+      const classSnapshots = [];
+      let runCount = 0;
+      for (const run of selected.runs) {
+        let population;
+        try {
+          population = visibilityComparisonPopulation(run, {
+            ...filters,
+            scope,
+            queryClass: "all",
+            location: locationKey2 === void 0 ? { kind: "all" } : locationKey2 === "none" ? { kind: "none" } : { kind: "exact", value: filters.location },
+            limit: 100
+          });
+        } catch (error) {
+          if (error instanceof VisibilityReportScopeError && error.details !== void 0) {
+            missingScope ??= error;
+            continue;
+          }
+          if (error instanceof VisibilityReportScopeError) throw validationError(error.message, error.details);
+          throw error;
+        }
+        runCount += 1;
+        const adapt = (snapshot) => ({
+          ...snapshot,
+          citationState: snapshot.citation === true ? CitationStates.cited : CitationStates["not-cited"],
+          citationChecked: snapshot.citation !== null,
+          citedDomains: []
+        });
+        snapshots.push(...population.snapshots.map(adapt));
+        classSnapshots.push(...population.classSnapshots.map(adapt));
+      }
+      measuredScope += runCount;
+      return { runCount, snapshots, classSnapshots, classificationAvailable: !selected.unavailable };
     };
-    const fromMonth = loadMonth(fromBounds);
-    const toMonth = loadMonth(toBounds);
-    const dto = computeVisibilityCompare({
+    const fromMonth2 = loadAdvancedMonth(fromBounds);
+    const toMonth2 = loadAdvancedMonth(toBounds);
+    if (missingScope !== void 0 && measuredScope === 0) throw validationError(missingScope.message, missingScope.details);
+    const queries2 = [...new Map([...fromMonth2.snapshots, ...toMonth2.snapshots].map((snapshot) => [snapshot.queryId, { id: snapshot.queryId, query: snapshot.queryText }])).values()];
+    advancedComparison = { ...computeVisibilityCompare({
       project: project.name,
-      queries: projectQueries,
-      competitors: competitorInputs,
-      brandNames: effectiveBrandNames(project),
-      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);
+      queries: queries2,
+      competitors: [...new Set([...fromMonth2.snapshots, ...toMonth2.snapshots].flatMap((snapshot) => snapshot.competitorDomains ?? []))].map((domain) => ({ domain, brandTokens: [] })),
+      frozenClassification: fromMonth2.classificationAvailable && toMonth2.classificationAvailable,
+      from: { ...fromMonth2, month: fromRaw, ...fromBounds },
+      to: { ...toMonth2, month: toRaw, ...toBounds }
+    }), selection: filters };
+    if (scoped) {
+      const unreadable = [fromMonth2.classificationAvailable ? null : fromRaw, toMonth2.classificationAvailable ? null : toRaw].filter((month) => month !== null);
+      if (unreadable.length > 0) {
+        throw validationError(`Property, group and market comparisons need frozen schema-v2 plan history; ${unreadable.join(" and ")} include runs whose plan cannot be reconstructed.`, { months: unreadable });
+      }
+      return advancedComparison;
+    }
+  }
+  if (advancedComparison === void 0 && scoped) throw validationError("Property, group and market comparison scopes require an Advanced portfolio.");
+  const projectQueries = db.select({ id: queries.id, query: queries.query }).from(queries).where(eq39(queries.projectId, project.id)).all();
+  const competitorRows2 = db.select({ domain: competitors.domain }).from(competitors).where(eq39(competitors.projectId, project.id)).all();
+  const competitorInputs = mentionShareCompetitorsFromDomains(competitorRows2.map((c) => c.domain));
+  const loadMonth = (bounds) => {
+    const sinceMs = Date.parse(bounds.since);
+    const untilMs = Date.parse(bounds.until);
+    const monthRuns = db.select({ id: runs.id, createdAt: runs.createdAt, status: runs.status }).from(runs).where(and35(eq39(runs.projectId, project.id), eq39(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 ? 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,
+      location: querySnapshots.location
+    }).from(querySnapshots).where(inArray18(querySnapshots.runId, runIds)).all() : [];
+    return {
+      runCount: monthRuns.length,
+      snapshots: snapshots.filter((snapshot) => (providerKey2 === void 0 || normalizeText3(snapshot.provider) === providerKey2) && (locationKey2 === void 0 || (locationKey2 === "none" ? snapshot.location === null : snapshot.location !== null && normalizeText3(snapshot.location) === locationKey2)))
+    };
+  };
+  const fromMonth = loadMonth(fromBounds);
+  const toMonth = loadMonth(toBounds);
+  const dto = computeVisibilityCompare({
+    project: project.name,
+    queries: projectQueries,
+    competitors: competitorInputs,
+    brandNames: effectiveBrandNames(project),
+    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 }
   });
+  if (advancedComparison !== void 0) {
+    const { from, to, basket, continuity: continuity2, modelChanges } = advancedComparison;
+    return {
+      ...dto,
+      selection: filters,
+      metrics: [
+        ...dto.metrics.filter((metric2) => !isVisibilityCompareClassMetric(metric2.key)),
+        ...advancedComparison.metrics.filter((metric2) => isVisibilityCompareClassMetric(metric2.key))
+      ],
+      classComparison: { from, to, basket, continuity: continuity2, modelChanges }
+    };
+  }
+  return { ...dto, selection: filters };
 }
 
 // ../api-routes/src/results-export.ts
@@ -39055,9 +39284,18 @@ var routeCatalog = [
     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.",
+    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`. Adds separate branded/non-brand mention and cited rates with classification-unavailable rather than pooled fallback. Advanced class metrics read frozen Property/market/execution assignments and reuse each answer once per class. Without a scope or marketKey the four original metrics keep the project frame (provider/location narrow it the same way for Simple and Advanced) and Advanced class metrics carry their own `classComparison` cohort. A scope or marketKey answers entirely from the frozen frame and is refused when either month holds runs whose plan cannot be reconstructed (schema v1). On frozen frames, answers with incomplete source capture leave every citation figure and are counted in `excludedUnknown`. A silent upstream version bump under an unchanged configured id remains undetectable.",
     tags: ["analytics"],
-    parameters: [nameParameter, compareFromQueryParameter, compareToQueryParameter],
+    parameters: [
+      nameParameter,
+      compareFromQueryParameter,
+      compareToQueryParameter,
+      { name: "scope", in: "query", description: "Advanced frozen population scope; default project.", schema: { type: "string", enum: ["project", "group", "market", "property"] } },
+      { name: "scopeKey", in: "query", description: "Stable Property Target, group, or market key; required for non-project scope.", schema: stringSchema },
+      { name: "marketKey", in: "query", description: "Intersect project/group/property selection with exact frozen market edges.", schema: stringSchema },
+      { name: "provider", in: "query", description: "Restrict both frames to one provider (case-insensitive).", schema: stringSchema },
+      { name: "location", in: "query", description: "Execution location label (case-insensitive), or none for no location.", schema: stringSchema }
+    ],
     responses: {
       200: jsonResponse("Month-over-month visibility comparison returned.", "VisibilityCompareDto"),
       400: errorResponse("Invalid or missing from/to months."),

package/dist/{chunk-PXVJ3P5G.js → chunk-FRWZWJB3.js}

@@ -5,7 +5,7 @@ import {
   PACKAGE_VERSION,
   canonryMcpTools,
   isMachineFormat
-} from "./chunk-JJPZ4OQ2.js";
+} from "./chunk-WUT3G2GM.js";
 import {
   AGENT_PROVIDER_IDS,
   CANONRY_NPM_PACKAGE_URL,
@@ -37,7 +37,7 @@ import {
   skillsClientSchema,
   upgradeCaveatFor,
   upgradeCommandFor
-} from "./chunk-TOSPZ7I5.js";
+} from "./chunk-2LO7FLVD.js";
 
 // src/config.ts
 import fs from "fs";
@@ -8891,12 +8891,12 @@ var ApiClient = class {
       })
     );
   }
-  async getVisibilityCompare(project, from, to) {
+  async getVisibilityCompare(project, from, to, selection = {}) {
     return this.invoke(
       () => getApiV1ProjectsByNameVisibilityCompare({
         client: this.heyClient,
         path: { name: project },
-        query: { from, to }
+        query: { from, to, ...selection }
       })
     );
   }

package/dist/{chunk-TWLJRAWA.js → chunk-HDJHQPW3.js}

@@ -5,12 +5,12 @@ import {
   siteCrawlGraphNodes,
   siteCrawlPages,
   siteCrawlSnapshots
-} from "./chunk-NSKFW3NF.js";
+} from "./chunk-FAVYLZQV.js";
 import {
   SITE_CRAWL_GRAPH_MAX_EDGES,
   SITE_CRAWL_GRAPH_MAX_NODES,
   TEMPLATE_LINK_RATIO_THRESHOLD
-} from "./chunk-TOSPZ7I5.js";
+} from "./chunk-2LO7FLVD.js";
 
 // src/site-crawl-graph-layout.ts
 import crypto from "crypto";

package/dist/{chunk-CVUR3O5G.js → chunk-MEAKE5W7.js}

@@ -4,14 +4,14 @@ import {
   installSkills,
   loadConfigRaw,
   saveConfigPatch
-} from "./chunk-PXVJ3P5G.js";
+} from "./chunk-FRWZWJB3.js";
 import {
   PACKAGE_VERSION
-} from "./chunk-JJPZ4OQ2.js";
+} from "./chunk-WUT3G2GM.js";
 import {
   SKILL_MANIFEST_FILENAME,
   SkillsClients
-} from "./chunk-TOSPZ7I5.js";
+} from "./chunk-2LO7FLVD.js";
 
 // src/skills-autosync.ts
 import fs from "fs";