@ainyc/canonry 4.190.1 → 4.192.0

package/dist/{chunk-ECPN4OUR.js → chunk-FTKZAOFD.js}

@@ -88,6 +88,8 @@ import {
   MeasurementRunScopeError,
   PROJECTS_WRITE_SCOPE,
   READ_ONLY_SCOPE,
+  REPORT_VISIBILITY_COPY,
+  RESEARCH_RUN_SCOPE,
   ResearchQueryStatuses,
   ResearchRunStatuses,
   RunKinds,
@@ -381,6 +383,7 @@ import {
   inclusiveDayCount,
   indexingRequestResponseDtoSchema,
   internalError,
+  intersectScopes,
   isBrowserProvider,
   isLocationRedirectStatus,
   isReadOnlyKey,
@@ -559,7 +562,16 @@ import {
   reportComparisonWindowDays,
   reportConfidenceLabel,
   reportHorizonLabel,
+  reportQueryClassLabel,
   reportSeverityLabel,
+  reportVisibilityComparison,
+  reportVisibilityEvidence,
+  reportVisibilityHistoryLabel,
+  reportVisibilityLocationLabel,
+  reportVisibilityMeasurementLabel,
+  reportVisibilityRate,
+  researchBatchCreateSchema,
+  researchBatchSchema,
   researchDailyLimitExceeded,
   researchRunCreateSchema,
   researchRunDetailSchema,
@@ -570,6 +582,7 @@ import {
   resolveMeasurementRunQueryScope,
   resolveMeasurementRunScope,
   resolveSnapshotRequestQueries,
+  restrictedWriteScopes,
   resultsClearRequestSchema,
   resultsClearResponseSchema,
   resultsExportDtoSchema,
@@ -676,10 +689,10 @@ import {
   wordpressSchemaDeployResultDtoSchema,
   wordpressSchemaStatusResultDtoSchema,
   wordpressStatusDtoSchema
-} from "./chunk-ROPJUNQN.js";
+} from "./chunk-BULKBROE.js";
 
 // src/intelligence-service.ts
-import { eq as eq67, desc as desc29, asc as asc12, and as and57, ne as ne10, or as or14, inArray as inArray25, gte as gte18, lte as lte15, isNull as isNull12, sql as sql26, exists } from "drizzle-orm";
+import { eq as eq67, desc as desc29, asc as asc12, and as and57, ne as ne10, or as or15, inArray as inArray25, gte as gte18, lte as lte15, isNull as isNull12, sql as sql26, exists } from "drizzle-orm";
 
 // ../db/src/client.ts
 import { mkdirSync } from "fs";
@@ -1181,6 +1194,8 @@ var apiKeys = sqliteTable("api_keys", {
    * project so a stale scoped key never outlives its project.
    */
   projectId: text("project_id").references(() => projects.id, { onDelete: "cascade" }),
+  /** Internal delegated session identity, never accepted by the key-create API. */
+  delegatedUserId: text("delegated_user_id").references(() => users.id, { onDelete: "cascade" }),
   createdAt: text("created_at").notNull(),
   lastUsedAt: text("last_used_at"),
   revokedAt: text("revoked_at")
@@ -7177,6 +7192,13 @@ var MIGRATION_VERSIONS = [
       `ALTER TABLE research_runs ADD COLUMN template TEXT`,
       `ALTER TABLE research_run_queries ADD COLUMN query_class TEXT`
     ]
+  },
+  {
+    version: 154,
+    name: "delegated-api-key-user",
+    statements: [
+      `ALTER TABLE api_keys ADD COLUMN delegated_user_id TEXT REFERENCES users(id) ON DELETE CASCADE`
+    ]
   }
 ];
 function addRunsMeasurementPlanVersionForeignKey(tx) {
@@ -8471,14 +8493,14 @@ function buildCitationScorecard(snapshots, queryLookup) {
   const providerRates = providerList.map((provider) => {
     const counts2 = providerCounts.get(provider) ?? { cited: 0, mentioned: 0, total: 0 };
     const citationRate = counts2.total > 0 ? Math.round(counts2.cited / counts2.total * 100) : 0;
-    const mentionRate2 = counts2.total > 0 ? Math.round(counts2.mentioned / counts2.total * 100) : 0;
+    const mentionRate3 = counts2.total > 0 ? Math.round(counts2.mentioned / counts2.total * 100) : 0;
     return {
       provider,
       citedCount: counts2.cited,
       mentionedCount: counts2.mentioned,
       totalCount: counts2.total,
       citationRate,
-      mentionRate: mentionRate2
+      mentionRate: mentionRate3
     };
   });
   return { queries: queryList, providers: providerList, matrix, providerRates };
@@ -9635,7 +9657,7 @@ function buildRunHistory(runs2, snapshotsByRunId, limit = DEFAULT_RUN_HISTORY_LI
     const citedCount = [...queryCited.values()].filter(Boolean).length;
     const citationRate = totalCount > 0 ? Math.round(citedCount / totalCount * 100) : 0;
     const mentionedCount = [...queryMentioned.values()].filter(Boolean).length;
-    const mentionRate2 = totalCount > 0 ? Math.round(mentionedCount / totalCount * 100) : 0;
+    const mentionRate3 = totalCount > 0 ? Math.round(mentionedCount / totalCount * 100) : 0;
     return {
       runId: run.id,
       createdAt: run.createdAt,
@@ -9643,7 +9665,7 @@ function buildRunHistory(runs2, snapshotsByRunId, limit = DEFAULT_RUN_HISTORY_LI
       totalCount,
       citationRate,
       mentionedCount,
-      mentionRate: mentionRate2,
+      mentionRate: mentionRate3,
       status: run.status
     };
   });
@@ -10795,10 +10817,6 @@ var ADS_MUTATION_SCOPES = /* @__PURE__ */ new Set([
   ADS_APPROVE_SCOPE,
   ADS_ACTIVATE_SCOPE
 ]);
-function isAdsMutationOnlyKey(scopes) {
-  const writeGrants = scopes.filter((scope) => scope === "*" || scope === "write" || scope.endsWith(".write") || scope === ADS_APPROVE_SCOPE || scope === ADS_ACTIVATE_SCOPE);
-  return writeGrants.length > 0 && writeGrants.every((scope) => ADS_MUTATION_SCOPES.has(scope));
-}
 function isAdsWriteRoute(url) {
   const rest = projectRouteRest(url);
   return rest !== null && rest.startsWith("ads/");
@@ -10829,8 +10847,8 @@ var VIEWER_DENIED_MESSAGE = "Your account has view-only access, so it cannot mak
 var ADMIN_ONLY_MESSAGE = "Only an administrator account can use this.";
 function requireAdminSession(request) {
   const principal = request.principal;
-  if (!principal || principal.kind !== "user") return;
-  if (principal.role === UserRoles.admin) return;
+  const role = principal?.kind === "user" ? principal.role : principal?.delegatedUser?.role;
+  if (!role || role === UserRoles.admin) return;
   throw forbidden(ADMIN_ONLY_MESSAGE);
 }
 function requirePaidReadScope(request) {
@@ -10841,16 +10859,20 @@ function requirePaidReadScope(request) {
     throw forbidden("This API key was not granted access to OpenAI Ads paid reads.");
   }
 }
+function canRunResearch(request, allowViewers) {
+  const principal = request.principal;
+  if (!principal) return true;
+  if (principal.kind === "user" && principal.role === UserRoles.viewer && !allowViewers) return false;
+  return principal.scopes.includes(WILDCARD_SCOPE) || principal.scopes.includes(RESEARCH_RUN_SCOPE);
+}
 function requireResearchGrant(request, allowViewers) {
   const principal = request.principal;
   if (!principal) return;
-  if (principal.kind === "api-key") {
-    if (principal.scopes.includes(WILDCARD_SCOPE)) return;
-    throw forbidden("This API key was not granted access to paid research queries.");
+  if (canRunResearch(request, allowViewers)) return;
+  if (principal.kind === "user" && principal.role === UserRoles.viewer && !allowViewers) {
+    throw forbidden("Research queries are not enabled for viewer accounts on this deployment.");
   }
-  if (principal.role === UserRoles.admin) return;
-  if (principal.role === UserRoles.viewer && allowViewers) return;
-  throw forbidden("Research queries are not enabled for viewer accounts on this deployment.");
+  throw forbidden('This credential was not granted the "research.run" capability.');
 }
 function requireBroadInstanceKey(request) {
   const principal = request.principal;
@@ -10893,8 +10915,8 @@ function shouldSkipAuth(url) {
 }
 var USERS_READ_SCOPE = "users.read";
 var USERS_WRITE_SCOPE = "users.write";
-function scopesForRole(role) {
-  return role === UserRoles.admin ? [WILDCARD_SCOPE] : [READ_ONLY_SCOPE];
+function scopesForRole(role, researchAllowViewers = false) {
+  return role === UserRoles.admin ? [WILDCARD_SCOPE] : researchAllowViewers ? [READ_ONLY_SCOPE, RESEARCH_RUN_SCOPE] : [READ_ONLY_SCOPE];
 }
 function queryValue(request, key) {
   const raw = request.query?.[key];
@@ -10984,7 +11006,7 @@ function enforceEmbedProjectTabs(request, configuredTabs) {
   if (tabs.includes("report") && isReportRead(url)) return;
   throw forbidden("This endpoint is not available for the configured embed tabs.");
 }
-function resolveSignedInPerson(app, request, reply, cookie) {
+function resolveSignedInPerson(app, request, reply, cookie, researchAllowViewers) {
   const sessionId = parseCookieHeader(request.headers.cookie)[USER_SESSION_COOKIE_NAME];
   if (!sessionId) return false;
   const resolved = resolveUserSession(app.db, sessionId);
@@ -10993,7 +11015,7 @@ function resolveSignedInPerson(app, request, reply, cookie) {
     kind: "user",
     id: resolved.user.id,
     name: resolved.user.name,
-    scopes: scopesForRole(resolved.user.role),
+    scopes: scopesForRole(resolved.user.role, researchAllowViewers),
     projectId: null,
     role: resolved.user.role,
     viaCookie: true
@@ -11009,12 +11031,24 @@ function resolveSignedInPerson(app, request, reply, cookie) {
 }
 function applyRoleGates(request) {
   const principal = request.principal;
-  if (!principal || principal.kind !== "user") return;
-  request.readSemanticGrant = principal.role === UserRoles.viewer && isReadSemanticRoute(request);
+  const role = principal?.kind === "user" ? principal.role : principal?.delegatedUser?.role;
+  if (!principal || !role) return;
+  request.readSemanticGrant = role === UserRoles.viewer && isReadSemanticRoute(request);
+  applyScopedWriteGates(request);
   if (isReadOnlyKey(principal.scopes) && WRITE_METHODS2.has(request.method) && !request.readSemanticGrant && !isPaidReadRoute(request) && !isTransportEnvelopeRoute(request)) {
     throw forbidden(VIEWER_DENIED_MESSAGE);
   }
 }
+function applyScopedWriteGates(request) {
+  if (!WRITE_METHODS2.has(request.method) || isTransportEnvelopeRoute(request) || request.readSemanticGrant) return;
+  const scopes = principalScopes(request) ?? [];
+  const restricted = restrictedWriteScopes(scopes);
+  if (!restricted) return;
+  const required2 = request.routeOptions.config.writeScope;
+  if (required2 && restricted.includes(required2)) return;
+  if (restricted.some((scope) => ADS_MUTATION_SCOPES.has(scope)) && isAdsWriteRoute(request.url.split("?")[0])) return;
+  throw forbidden("This credential can only perform operations explicitly granted by its scopes.");
+}
 async function authPlugin(app, opts = {}) {
   app.addHook("onRequest", async (request, reply) => {
     const url = request.url.split("?")[0];
@@ -11035,10 +11069,9 @@ async function authPlugin(app, opts = {}) {
         if (granted) {
           const account = app.db.select().from(users).where(eq2(users.id, granted.userId)).get();
           if (!account) throw authInvalid();
-          const roleScopes = scopesForRole(account.role);
+          const roleScopes = scopesForRole(account.role, opts.researchAllowViewers);
           const requested = (granted.scope ?? "").split(/\s+/).filter((part) => part.length > 0 && part !== "offline_access");
-          const narrowed = roleScopes.includes(WILDCARD_SCOPE) ? requested.length > 0 ? requested : [READ_ONLY_SCOPE] : roleScopes.filter((scope) => requested.includes(scope) || requested.includes(WILDCARD_SCOPE));
-          const effective = narrowed.length > 0 ? narrowed : [READ_ONLY_SCOPE];
+          const effective = intersectScopes(roleScopes, requested);
           request.principal = {
             kind: "user",
             id: account.id,
@@ -11055,7 +11088,7 @@ async function authPlugin(app, opts = {}) {
         }
         throw authInvalid();
       }
-    } else if (resolveSignedInPerson(app, request, reply, opts.userSessionCookie)) {
+    } else if (resolveSignedInPerson(app, request, reply, opts.userSessionCookie, opts.researchAllowViewers ?? false)) {
       applyRoleGates(request);
       assertSameOriginWrite(request);
       enforceEmbedProjectTabs(request, opts.embedProjectTabs);
@@ -11078,7 +11111,10 @@ async function authPlugin(app, opts = {}) {
       throw authRequired();
     }
     app.db.update(apiKeys).set({ lastUsedAt: (/* @__PURE__ */ new Date()).toISOString() }).where(eq2(apiKeys.id, key.id)).run();
-    const scopes = Array.isArray(key.scopes) ? key.scopes : [];
+    let scopes = Array.isArray(key.scopes) ? key.scopes : [];
+    const delegatedUser = key.delegatedUserId ? app.db.select().from(users).where(eq2(users.id, key.delegatedUserId)).get() : void 0;
+    if (key.delegatedUserId && !delegatedUser) throw authInvalid();
+    if (delegatedUser) scopes = intersectScopes(scopesForRole(delegatedUser.role, opts.researchAllowViewers), scopes);
     request.apiKey = { id: key.id, name: key.name, scopes, projectId: key.projectId ?? null };
     request.principal = {
       kind: "api-key",
@@ -11086,15 +11122,15 @@ async function authPlugin(app, opts = {}) {
       name: key.name,
       scopes,
       projectId: key.projectId ?? null,
-      viaCookie: keyArrivedInCookie
+      viaCookie: keyArrivedInCookie,
+      ...delegatedUser ? { delegatedUser: { id: delegatedUser.id, name: delegatedUser.name, role: delegatedUser.role } } : {}
     };
     assertSameOriginWrite(request);
-    if (isReadOnlyKey(scopes) && WRITE_METHODS2.has(request.method) && !isTransportEnvelopeRoute(request)) {
+    applyRoleGates(request);
+    applyScopedWriteGates(request);
+    if (isReadOnlyKey(scopes) && WRITE_METHODS2.has(request.method) && !request.readSemanticGrant && !isTransportEnvelopeRoute(request)) {
       throw forbidden("This API key is read-only and cannot perform write operations.");
     }
-    if (isAdsMutationOnlyKey(scopes) && WRITE_METHODS2.has(request.method) && !isAdsWriteRoute(url)) {
-      throw forbidden("This API key can only perform OpenAI Ads write operations.");
-    }
     enforceEmbedProjectTabs(request, opts.embedProjectTabs);
     if (key.projectId) {
       const match = url.match(/\/projects\/([^/?#]+)/);
@@ -11149,7 +11185,7 @@ function redirectUriAllowed(registered, presented) {
 function isLoopbackHost(hostname) {
   return hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]" || hostname === "localhost";
 }
-var SUPPORTED_SCOPES = ["read", "offline_access"];
+var SUPPORTED_SCOPES = ["read", RESEARCH_RUN_SCOPE, "offline_access"];
 function resolveRequestedScope(requested) {
   if (!requested || !requested.trim()) return "read";
   const parts = requested.trim().split(/\s+/);
@@ -11183,6 +11219,7 @@ function consentPage(o) {
    <dt>Permissions</dt><dd>${escapeHtml(o.scope)}</dd>
    <dt>Redirects to</dt><dd class="uri">${escapeHtml(o.redirectUri)}</dd>
  </dl>
+ ${o.scope.split(/\s+/).includes(RESEARCH_RUN_SCOPE) ? `<p class="warn">Run research queries using the operator's provider quota, subject to the shared daily research limit. This does not grant permission to change tracking or settings.</p>` : ""}
  <input type="hidden" name="csrf" value="${escapeHtml(o.csrf)}">
  <div class="row">
    <button type="submit" name="approve" value="no" class="ghost">Deny</button>
@@ -13293,7 +13330,7 @@ function normalizeMeasurementLocation(value) {
   return normalized || null;
 }
 function words(value) {
-  return value.normalize("NFKC").toLocaleLowerCase("en").match(/[\p{L}\p{N}]+/gu) ?? [];
+  return value.normalize("NFKC").toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
 }
 function measurementMentionAliasKey(value) {
   return words(value).join("\0");
@@ -13326,10 +13363,11 @@ function indexMentionAliases(aliases) {
   }
   return byFirstWord;
 }
-function mentionedTargetsForAliases(answerText, aliases) {
+function mentionedTargetsForAliases(answerText, aliases, preparedWords) {
   const result = /* @__PURE__ */ new Set();
-  if (answerText === null) return result;
-  const textWords = words(answerText);
+  const unknown = /* @__PURE__ */ new Set();
+  if (answerText === null) return { mentioned: result, unknown };
+  const textWords = preparedWords ?? words(answerText);
   for (let start = 0; start < textWords.length; ) {
     const matches = (aliases.get(textWords[start]) ?? []).filter((alias2) => aliasMatchesAt(textWords, alias2.words, start));
     if (matches.length === 0) {
@@ -13339,16 +13377,46 @@ function mentionedTargetsForAliases(answerText, aliases) {
     const longest = Math.max(...matches.map((match) => match.words.length));
     const owners = sortedUnique(matches.filter((match) => match.words.length === longest).map((match) => match.targetId));
     if (owners.length === 1) result.add(owners[0]);
+    else for (const owner of owners) unknown.add(owner);
     start += longest;
   }
-  return result;
+  for (const owner of result) unknown.delete(owner);
+  return { mentioned: result, unknown };
 }
-function mentionedTargets(answerText, targets) {
-  return mentionedTargetsForAliases(answerText, indexMentionAliases(compiledMentionAliases(targets)));
+function identityAmbiguityPatterns(aliases) {
+  const patterns = aliases.flatMap((alias2) => {
+    const name = words(alias2).join(" ").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (!name) return [];
+    return [{
+      clarification: new RegExp(`(?:^| )which (?:specific )?${name} (?:(?:(?:do|did) )?you mean|(?:(?:are|were) you|you(?: re| are| were)?) (?:asking about|referring to|talking about))(?= |$)`, "u"),
+      multipleEntities: [
+        new RegExp(`(?:^| )${name} (?:turns out to |can |could |may )?refers? to (?:a )?(?:few |several |multiple |different )`, "u"),
+        new RegExp(`(?:^| )${name} is (?:a |the )?name shared by(?= |$)`, "u"),
+        new RegExp(`(?:^| )(?:several|multiple|different) (?:places|properties|businesses|communities|entities) (?:called|named) ${name}(?= |$)`, "u")
+      ]
+    }];
+  });
+  return {
+    clarification: patterns.map((pattern) => pattern.clarification),
+    multipleEntities: patterns.flatMap((pattern) => pattern.multipleEntities)
+  };
 }
-function targetMentionedInAnswer(answerText, targetId, targets) {
-  if (answerText === null) return null;
-  return mentionedTargets(answerText, targets).has(targetId);
+function resolveMentionIdentity(text2, targets, aliases, citedTargetIds, ambiguityPatterns = new Map(targets.map((target) => [target.id, identityAmbiguityPatterns(target.aliases)]))) {
+  const textWords = text2 === null ? [] : words(text2);
+  const state = mentionedTargetsForAliases(text2, aliases, textWords);
+  if (text2 === null) return state;
+  const normalized = textWords.join(" ");
+  for (const target of targets) {
+    if (!state.mentioned.has(target.id)) continue;
+    const patterns = ambiguityPatterns.get(target.id);
+    const qualified = citedTargetIds.has(target.id) || (target.identityAliases?.length ?? 0) > 0 && containsAnyAlias(text2, target.identityAliases);
+    const unresolved = patterns?.clarification.some((pattern) => pattern.test(normalized)) || !qualified && (patterns?.multipleEntities.some((pattern) => pattern.test(normalized)) || (target.identityAliases?.length ?? 0) > 0);
+    if (unresolved) {
+      state.mentioned.delete(target.id);
+      state.unknown.add(target.id);
+    }
+  }
+  return state;
 }
 function observationSource(observation) {
   if (observation.citedUrls !== null) {
@@ -13364,15 +13432,28 @@ function observationSource(observation) {
     complete: observation.historicalCitedUrlsComplete === true
   };
 }
-function prepareReport(input, options = {}) {
+function prepareReport(input, options = {}, detailedEvidence = true) {
   const ambiguous = /* @__PURE__ */ new Set();
   const unmatched = /* @__PURE__ */ new Set();
   const bridged = /* @__PURE__ */ new Set();
   const candidates = /* @__PURE__ */ new Map();
   const mentionAliases = compiledMentionAliases(input.targets);
   const aliasesByFirstWord = indexMentionAliases(mentionAliases);
+  const ambiguityPatterns = new Map(input.targets.map((target) => [target.id, identityAmbiguityPatterns(target.aliases)]));
+  const slotsByIdentity = /* @__PURE__ */ new Map();
+  const slotsByLegacyIdentity = /* @__PURE__ */ new Map();
+  for (const slot of input.expectedSlots) {
+    for (const [index2, key] of [
+      [slotsByIdentity, JSON.stringify([slot.executionId, slot.provider])],
+      [slotsByLegacyIdentity, JSON.stringify([slot.queryText, slot.provider, normalizeMeasurementLocation(slot.location)])]
+    ]) {
+      const slots = index2.get(key) ?? [];
+      slots.push(slot);
+      index2.set(key, slots);
+    }
+  }
   for (const observation of input.observations) {
-    const slots = observation.executionId !== null ? input.expectedSlots.filter((slot2) => slot2.executionId === observation.executionId && slot2.provider === observation.provider) : input.expectedSlots.filter((slot2) => slot2.queryText === observation.queryText && slot2.provider === observation.provider && normalizeMeasurementLocation(slot2.location) === normalizeMeasurementLocation(observation.location));
+    const slots = (observation.executionId !== null ? slotsByIdentity.get(JSON.stringify([observation.executionId, observation.provider])) : slotsByLegacyIdentity.get(JSON.stringify([observation.queryText, observation.provider, normalizeMeasurementLocation(observation.location)]))) ?? [];
     if (slots.length === 0) {
       unmatched.add(observation.id);
       continue;
@@ -13409,7 +13490,9 @@ function prepareReport(input, options = {}) {
       historical: source.historical,
       sourceComplete: source.complete,
       sourceUrls: source.urls,
-      mentionedTargetIds: mentionedTargetsForAliases(observation.answerText, aliasesByFirstWord)
+      mentionedTargetIds: /* @__PURE__ */ new Set(),
+      unknownMentionTargetIds: /* @__PURE__ */ new Set(),
+      citedTargetIds: /* @__PURE__ */ new Set()
     });
   }
   const edgesByExecution = /* @__PURE__ */ new Map();
@@ -13433,6 +13516,15 @@ function prepareReport(input, options = {}) {
     mentionAliases.map((alias2) => alias2.targetId)
   );
   for (const observation of observationsBySlot.values()) {
+    const citedTargetIds = new Set(observation.sourceUrls.flatMap((url) => {
+      const source = sourceAttribution(url);
+      return source.classification === "matched" ? source.matchedTargetIds : [];
+    }));
+    const mentions = resolveMentionIdentity(observation.input.answerText, input.targets, aliasesByFirstWord, citedTargetIds, ambiguityPatterns);
+    observation.mentionedTargetIds = mentions.mentioned;
+    observation.unknownMentionTargetIds = mentions.unknown;
+    observation.citedTargetIds = citedTargetIds;
+    if (!detailedEvidence) continue;
     const edges = [...edgesByExecution.get(observation.slot.executionId) ?? []].sort((left, right) => compareText2(left.id, right.id));
     for (const edge of edges) {
       const sources = observation.sourceUrls.map((sourceUrl) => {
@@ -13502,6 +13594,17 @@ function prepareReport(input, options = {}) {
     }
   };
 }
+function buildMeasurementObservationSignals(input) {
+  const prepared = prepareReport(input, {}, false);
+  return [...prepared.observationsBySlot.values()].map((observation) => ({
+    observationId: observation.input.id,
+    mentionedTargetIds: [...observation.mentionedTargetIds],
+    unknownMentionTargetIds: [...observation.unknownMentionTargetIds],
+    citedTargetIds: [...observation.citedTargetIds],
+    sourceComplete: observation.sourceComplete,
+    sourceUrls: observation.sourceUrls
+  }));
+}
 function slotsForEdges(expectedSlots, edges) {
   const executionIds = new Set(edges.map((edge) => edge.executionId));
   const slots = /* @__PURE__ */ new Map();
@@ -13562,6 +13665,9 @@ function mentionRate(target, slots, prepared) {
   if (!status.complete || !status.answerComplete) {
     return { numerator: null, denominator: null, rate: null, reason: "incomplete" };
   }
+  if (slots.some((slot) => prepared.observationsBySlot.get(slot.id)?.unknownMentionTargetIds.has(target.id))) {
+    return unavailable("identity-ambiguous");
+  }
   return { numerator, denominator: slots.length, rate: numerator / slots.length };
 }
 function providersFor(slots) {
@@ -13679,6 +13785,7 @@ function buildMeasurementOverviewIndexes(input, prepared, onEvidenceIndexed) {
   const answeredSlotIds = /* @__PURE__ */ new Set();
   const sourceCompleteSlotIds = /* @__PURE__ */ new Set();
   const mentionedSlotIdsByTargetId = /* @__PURE__ */ new Map();
+  const unknownMentionSlotIdsByTargetId = /* @__PURE__ */ new Map();
   for (const [slotId, observation] of prepared.observationsBySlot) {
     if (observation.sourceComplete) sourceCompleteSlotIds.add(slotId);
     if (observation.input.answerText === null) continue;
@@ -13686,6 +13793,9 @@ function buildMeasurementOverviewIndexes(input, prepared, onEvidenceIndexed) {
     for (const targetId of observation.mentionedTargetIds) {
       addToSet(mentionedSlotIdsByTargetId, targetId, slotId);
     }
+    for (const targetId of observation.unknownMentionTargetIds) {
+      addToSet(unknownMentionSlotIdsByTargetId, targetId, slotId);
+    }
   }
   const assignedSlotIdsByEdgeId = /* @__PURE__ */ new Map();
   const ambiguousEvidenceKeysByTargetId = /* @__PURE__ */ new Map();
@@ -13710,6 +13820,7 @@ function buildMeasurementOverviewIndexes(input, prepared, onEvidenceIndexed) {
     answeredSlotIds,
     sourceCompleteSlotIds,
     mentionedSlotIdsByTargetId,
+    unknownMentionSlotIdsByTargetId,
     assignedSlotIdsByEdgeId,
     ambiguousEvidenceKeysByTargetId
   };
@@ -13733,27 +13844,34 @@ function mentionedForEdge(observation, edge, mentionableIds) {
   if (edge.type !== "target") return null;
   if (observation.input.answerText === null) return null;
   if (!mentionableIds.has(edge.targetId)) return null;
+  if (observation.unknownMentionTargetIds.has(edge.targetId)) return null;
   return observation.mentionedTargetIds.has(edge.targetId);
 }
 function mentionableTargets(input, targetIds) {
   return input.targets.filter((target) => targetIds.has(target.id) && target.aliases.some((alias2) => words(alias2).length > 0));
 }
-function scopeMentionRate(input, targetIds, slots, answered2, prepared) {
+function scopeMentionRate(input, targetIds, slots, answered2, prepared, edges) {
   const mentionable = mentionableTargets(input, targetIds);
   if (mentionable.length === 0) return unavailable("aliasless");
   if (slots.length === 0) return unavailable("no-population");
-  if (answered2.length === 0) return unavailable("evidence-incomplete");
-  const ids = mentionable.map((target) => target.id);
-  const numerator = answered2.filter((slot) => {
-    const mentioned = prepared.observationsBySlot.get(slot.id)?.mentionedTargetIds;
-    return mentioned !== void 0 && ids.some((id) => mentioned.has(id));
-  }).length;
+  if (answered2.length !== slots.length) return unavailable("evidence-incomplete");
+  const mentionableIds = new Set(mentionable.map((target) => target.id));
+  const idsByExecution = /* @__PURE__ */ new Map();
+  for (const edge of edges) if (mentionableIds.has(edge.targetId)) addToSet(idsByExecution, edge.executionId, edge.targetId);
+  let numerator = 0;
+  for (const slot of answered2) {
+    const observation = prepared.observationsBySlot.get(slot.id);
+    const ids = [...idsByExecution.get(slot.executionId) ?? []];
+    if (ids.length === 0) return unavailable("aliasless");
+    if (ids.some((id) => observation.mentionedTargetIds.has(id))) numerator++;
+    else if (ids.some((id) => observation.unknownMentionTargetIds.has(id))) return unavailable("identity-ambiguous");
+  }
   return { numerator, denominator: answered2.length, rate: numerator / answered2.length };
 }
 function indexedScopeCitationRate(slots, edges, indexes) {
   if (slots.length === 0) return unavailable("no-population");
   const basis = slots.filter((slot) => indexes.sourceCompleteSlotIds.has(slot.id));
-  if (basis.length === 0) return unavailable("evidence-incomplete");
+  if (basis.length !== slots.length) return unavailable("evidence-incomplete");
   const assignedSlots = /* @__PURE__ */ new Set();
   for (const edge of edges) {
     for (const slotId of indexes.assignedSlotIdsByEdgeId.get(edge.id) ?? []) assignedSlots.add(slotId);
@@ -13765,8 +13883,10 @@ function targetMentionRate(targets, slots, answered2, indexes) {
   const mentionable = targets?.filter((target) => target.aliases.some((alias2) => words(alias2).length > 0)) ?? [];
   if (mentionable.length === 0) return unavailable("aliasless");
   if (slots.length === 0) return unavailable("no-population");
-  if (answered2.length === 0) return unavailable("evidence-incomplete");
+  if (answered2.length !== slots.length) return unavailable("evidence-incomplete");
   const mentioned = indexes.mentionedSlotIdsByTargetId.get(mentionable[0].id) ?? /* @__PURE__ */ new Set();
+  const unknown = indexes.unknownMentionSlotIdsByTargetId.get(mentionable[0].id);
+  if (unknown && answered2.some((slot) => unknown.has(slot.id))) return unavailable("identity-ambiguous");
   const numerator = answered2.filter((slot) => mentioned.has(slot.id)).length;
   return { numerator, denominator: answered2.length, rate: numerator / answered2.length };
 }
@@ -13783,13 +13903,23 @@ function scopeBrandPresence(input, slots, answered2, prepared) {
   const numerator = presenceIn(answered2, input.projectBrandNames, prepared);
   return { numerator, denominator: answered2.length, rate: numerator / answered2.length };
 }
-function scopePropertiesMentioned(input, targetIds, slots, answered2, prepared) {
+function scopePropertiesMentioned(input, targetIds, slots, answered2, indexes) {
   const mentionable = mentionableTargets(input, targetIds);
   if (mentionable.length === 0) return unavailable("aliasless");
   if (slots.length === 0) return unavailable("no-population");
   if (answered2.length === 0) return unavailable("evidence-incomplete");
-  const mentioned = new Set(answered2.flatMap((slot) => [...prepared.observationsBySlot.get(slot.id)?.mentionedTargetIds ?? []]));
-  const numerator = mentionable.filter((target) => mentioned.has(target.id)).length;
+  let numerator = 0;
+  for (const target of mentionable) {
+    const own = indexedSlotsForEdges(indexes.targetEdgesByTargetId.get(target.id) ?? [], indexes);
+    const mentioned = indexes.mentionedSlotIdsByTargetId.get(target.id);
+    if (mentioned && own.some((slot) => mentioned.has(slot.id))) {
+      numerator++;
+      continue;
+    }
+    const unknown = indexes.unknownMentionSlotIdsByTargetId.get(target.id);
+    if (unknown && own.some((slot) => unknown.has(slot.id))) return unavailable("identity-ambiguous");
+    if (own.length === 0 || own.some((slot) => !indexes.answeredSlotIds.has(slot.id))) return unavailable("evidence-incomplete");
+  }
   return { numerator, denominator: mentionable.length, rate: numerator / mentionable.length };
 }
 function scopeNamedShareOfVoice(identities, answered2, prepared) {
@@ -13846,8 +13976,8 @@ function createMeasurementOverviewEvaluator(input, options = {}) {
         eligibleSlots: slots.length,
         answeredSlots: answered2.length,
         includesHistoricalData: prepared.diagnostics.bridgedObservationIds.length > 0 || prepared.diagnostics.historicalObservationIds.length > 0,
-        propertiesMentioned: scopePropertiesMentioned(input, targetIds, slots, answered2, prepared),
-        mentionCoverage: scopeMentionRate(input, targetIds, slots, answered2, prepared),
+        propertiesMentioned: scopePropertiesMentioned(input, targetIds, slots, answered2, indexes),
+        mentionCoverage: scopeMentionRate(input, targetIds, slots, answered2, prepared, edges),
         citationCoverage: indexedScopeCitationRate(slots, edges, indexes),
         brandPresence: scopeBrandPresence(input, slots, answered2, prepared),
         namedShareOfVoice: scopeNamedShareOfVoice(namedIdentities ?? [], answered2, prepared),
@@ -14127,6 +14257,7 @@ function buildMeasurementPlanV2ReportInput(revision, plan, manifest, snapshots)
         // The revision already decided this Property cannot be mentioned. Feeding
         // its aliases in anyway would turn "not applicable" into a 0% reading.
         aliases: target.mentionNotApplicable ? [] : target.aliases,
+        ...target.identityAliases === void 0 ? {} : { identityAliases: target.identityAliases },
         urls: target.urlMatchers.map((matcher, index2) => matcherInput(target.stableKey, matcher, index2))
       })),
       groups: plan.groups.map((group) => ({
@@ -14406,6 +14537,8 @@ function activeMeasurementPlan(db, projectId) {
 }
 function metricReason(reason) {
   switch (reason) {
+    case "identity-ambiguous":
+      return "identity_ambiguous";
     case "no-population":
       return "no_population";
     case "incomplete":
@@ -17537,6 +17670,14 @@ function compileMeasurementDraft(authoring, context) {
       aliasClaims.set(identity, target.stableKey);
     });
     const aliases = canonicalStrings(target.aliases);
+    const aliasKeys = aliases.map(measurementMentionAliasKey).filter(Boolean);
+    target.identityAliases?.forEach((identityAlias, index2) => {
+      const identityKey = measurementMentionAliasKey(identityAlias);
+      const qualifiesAlias = aliasKeys.some((aliasKey) => identityKey !== aliasKey && `\0${identityKey}\0`.includes(`\0${aliasKey}\0`));
+      if (!qualifiesAlias) {
+        sink.fail("target-identity-alias-unqualified", "An identity phrase must include a Property alias and additional identifying context.", ["targets", targetIndex, "identityAliases", index2]);
+      }
+    });
     if (aliases.length === 0) {
       sink.warn("target-without-aliases", `Target "${target.label}" has no aliases, so it can be cited but never mentioned.`, ["targets", targetIndex, "aliases"]);
     }
@@ -17545,6 +17686,7 @@ function compileMeasurementDraft(authoring, context) {
         stableKey: target.stableKey,
         label: target.label,
         aliases,
+        ...target.identityAliases === void 0 ? {} : { identityAliases: canonicalStrings(target.identityAliases) },
         urlMatchers: matchers,
         mentionNotApplicable: aliases.length === 0,
         discoveryIdentity: target.discoveryIdentity ?? null
@@ -18080,6 +18222,7 @@ function mergeTargets(authoring, body) {
   const merged = {
     ...survivor,
     aliases: unique([...survivor.aliases, ...authoring.targets.filter((target) => absorbedSet.has(target.stableKey)).flatMap((target) => target.aliases)]),
+    ...[survivor, ...authoring.targets.filter((target) => absorbedSet.has(target.stableKey))].some((target) => target.identityAliases !== void 0) ? { identityAliases: unique([...survivor.identityAliases ?? [], ...authoring.targets.filter((target) => absorbedSet.has(target.stableKey)).flatMap((target) => target.identityAliases ?? [])]) } : {},
     urlMatchers: unique([...survivor.urlMatchers, ...authoring.targets.filter((target) => absorbedSet.has(target.stableKey)).flatMap((target) => target.urlMatchers)])
   };
   const assignments = [];
@@ -19243,6 +19386,7 @@ function seedAuthoring(project, active, context, opts) {
         label: target.label,
         status: "included",
         aliases: [...target.aliases],
+        ...target.identityAliases === void 0 ? {} : { identityAliases: [...target.identityAliases] },
         urlMatchers: target.urlMatchers.map(formatDraftMatcher),
         source: target.discoveryIdentity ? "sitemap" : "manual",
         ...target.discoveryIdentity ? { discoveryIdentity: target.discoveryIdentity } : {}
@@ -21169,6 +21313,7 @@ function questionRows(plan, target, materialized, filters = {}) {
   }
   const ownEdgesByExecution = new Map(materialized.input.usageEdges.filter((edge) => edge.type === "target" && edge.targetId === targetKey).filter((edge) => assignmentsByExecution.has(edge.executionId)).map((edge) => [edge.executionId, edge]));
   const ownEdgeIds = new Set([...ownEdgesByExecution.values()].map((edge) => edge.id));
+  const answerBySlot = new Map(materialized.evidence.answers.filter((answer) => ownEdgeIds.has(answer.usageEdgeId)).map((answer) => [answer.expectedSlotId, answer]));
   const citedSlotIds = new Set(materialized.evidence.evidence.filter((row) => ownEdgeIds.has(row.usageEdgeId) && row.classification === "assigned").map((row) => row.expectedSlotId));
   const incompleteObservationIds = new Set(materialized.evidence.diagnostics.evidenceIncompleteObservationIds);
   const rows = [];
@@ -21200,8 +21345,8 @@ function questionRows(plan, target, materialized, filters = {}) {
       servedModel: snapshot?.servedModel ?? null,
       location: slot.location,
       status: answered2 ? "answered" : "missing",
-      mentioned: answered2 && !target.mentionNotApplicable ? targetMentionedInAnswer(answer, targetKey, materialized.input.targets) : null,
-      cited: answered2 ? incompleteObservationIds.has(snapshot.id) ? null : citedSlotIds.has(slot.id) : null,
+      mentioned: answered2 && !target.mentionNotApplicable ? answerBySlot.get(slot.id)?.mentioned ?? null : null,
+      cited: answered2 ? citedSlotIds.has(slot.id) ? true : incompleteObservationIds.has(snapshot.id) ? null : false : null,
       recommendedInstead: answered2 ? recommendedInstead(snapshot.recommendedCompetitors, target) : [],
       answerExcerpt: answered2 ? excerptOf(answer) : null,
       edgeId: edge.id
@@ -21382,6 +21527,8 @@ function runIdentity(run) {
 }
 function metricReason2(reason) {
   switch (reason) {
+    case "identity-ambiguous":
+      return "identity_ambiguous";
     case "no-population":
       return "no_population";
     case "incomplete":
@@ -21431,6 +21578,7 @@ function targetAnswers(plan, target, materialized, filters) {
   const assignmentsByExecution = new Map(plan.assignments.filter((assignment) => assignment.targetKey === target.stableKey).filter((assignment) => filters.queryClass === "all" || assignment.queryClass === filters.queryClass).map((assignment) => [assignment.executionNodeKey, assignment]));
   const edgesByExecution = new Map(materialized.input.usageEdges.filter((edge) => edge.type === "target" && edge.targetId === target.stableKey).filter((edge) => assignmentsByExecution.has(edge.executionId)).map((edge) => [edge.executionId, edge]));
   const ownEdgeIds = new Set([...edgesByExecution.values()].map((edge) => edge.id));
+  const answerBySlot = new Map(materialized.evidence.answers.filter((answer) => ownEdgeIds.has(answer.usageEdgeId)).map((answer) => [answer.expectedSlotId, answer]));
   const citedSlotIds = new Set(materialized.evidence.evidence.filter((row) => ownEdgeIds.has(row.usageEdgeId) && row.classification === "assigned").map((row) => row.expectedSlotId));
   const incompleteObservationIds = new Set(materialized.evidence.diagnostics.evidenceIncompleteObservationIds);
   const questionsById = new Map(plan.querySnapshots.map((question) => [question.queryId, question.queryText]));
@@ -21449,8 +21597,8 @@ function targetAnswers(plan, target, materialized, filters) {
       provider: slot.provider,
       question: questionsById.get(assignment.queryId) ?? slot.queryText,
       snapshot,
-      mentioned: target.mentionNotApplicable ? null : targetMentionedInAnswer(snapshot.answerText, target.stableKey, materialized.input.targets),
-      cited: incompleteObservationIds.has(snapshot.id) ? null : citedSlotIds.has(slot.id)
+      mentioned: target.mentionNotApplicable ? null : answerBySlot.get(slot.id)?.mentioned ?? null,
+      cited: citedSlotIds.has(slot.id) ? true : incompleteObservationIds.has(snapshot.id) ? null : false
     });
   }
   return { expected: slots.length, answers };
@@ -22065,10 +22213,10 @@ function selectedClasses(value) {
 function unavailable4(reason) {
   return { numerator: null, denominator: null, rate: null, reason };
 }
-function rate(values, expected) {
+function rate(values, expected, unknownReason = "evidence-incomplete") {
   if (expected === 0) return unavailable4("no-population");
   if (values.length !== expected) return unavailable4("incomplete");
-  if (values.some((value) => value === null)) return unavailable4("evidence-incomplete");
+  if (values.some((value) => value === null)) return unavailable4(unknownReason);
   const denominator = values.length;
   if (denominator === 0) return unavailable4("no-population");
   const numerator = values.filter(Boolean).length;
@@ -22170,17 +22318,30 @@ function targetValues(candidate, targets, targetKey) {
   const targetKeys = targetKey === void 0 ? [...new Set(candidate.edges.map((edge) => edge.targetKey))] : [targetKey];
   const eligible = targetKeys.filter((key) => targets.get(key)?.mentionEligible === true);
   const observation = candidate.observation;
+  const citation = observation && targetKeys.some((key) => observation.citedTargetKeys.includes(key)) ? true : observation?.citationComplete && targetKeys.length > 0 ? false : null;
   const mentionComplete = observation !== null && (observation.mentionComplete ?? observation.answerText !== null);
   if (!observation || !mentionComplete || eligible.length === 0) {
     return {
       mention: null,
-      citation: observation?.citationComplete === true && targetKeys.length > 0 ? targetKeys.some((key) => observation.citedTargetKeys.includes(key)) : null
+      citation
     };
   }
-  return {
-    mention: eligible.some((key) => observation.mentionedTargetKeys.includes(key)),
-    citation: observation.citationComplete ? targetKeys.some((key) => observation.citedTargetKeys.includes(key)) : null
-  };
+  if (eligible.some((key) => observation.mentionedTargetKeys.includes(key))) return { mention: true, citation };
+  if (eligible.some((key) => observation.unknownMentionTargetKeys?.includes(key))) {
+    return { mention: null, citation, mentionUnavailableReason: "identity-ambiguous" };
+  }
+  return { mention: false, citation };
+}
+function citationForCoverage(candidate, targets, targetKey) {
+  return candidate.observation?.citationComplete ? targetValues(candidate, targets, targetKey).citation : null;
+}
+function mentionRate2(candidates, targets, targetKey) {
+  const values = candidates.map((candidate) => targetValues(candidate, targets, targetKey));
+  return rate(
+    values.map((value) => value.mention),
+    values.length,
+    values.some((value) => value.mentionUnavailableReason === "identity-ambiguous") ? "identity-ambiguous" : "evidence-incomplete"
+  );
 }
 function answered(candidate) {
   return candidate.observation !== null;
@@ -22194,21 +22355,30 @@ function selectedTargetKeys(candidates) {
 function targetMetrics(candidates, targets, targetKey) {
   const own = candidates.filter((candidate) => candidate.edges.some((edge) => edge.targetKey === targetKey));
   return {
-    mentionCoverage: rate(own.map((candidate) => targetValues(candidate, targets, targetKey).mention), own.length),
-    citationCoverage: rate(own.map((candidate) => targetValues(candidate, targets, targetKey).citation), own.length)
+    mentionCoverage: mentionRate2(own, targets, targetKey),
+    citationCoverage: rate(own.map((candidate) => citationForCoverage(candidate, targets, targetKey)), own.length)
+  };
+}
+function targetPresence(candidates, targets, targetKey) {
+  const values = candidates.filter((candidate) => candidate.edges.some((edge) => edge.targetKey === targetKey)).map((candidate) => targetValues(candidate, targets, targetKey));
+  const anyKnown = (signals) => signals.includes(true) ? true : signals.length === 0 || signals.includes(null) ? null : false;
+  return {
+    targetKey,
+    mention: anyKnown(values.map((value) => value.mention)),
+    citation: anyKnown(values.map((value) => value.citation)),
+    identityAmbiguous: values.some((value) => value.mentionUnavailableReason === "identity-ambiguous")
   };
 }
-function outcomeCounts(candidates, targets, targetKeys) {
-  const counts2 = { bothSignals: 0, mentionedOnly: 0, citedOnly: 0, neither: 0, notMeasured: 0, total: targetKeys.length };
-  for (const targetKey of targetKeys) {
-    const metrics = targetMetrics(candidates, targets, targetKey);
-    if (metrics.mentionCoverage.numerator === null || metrics.citationCoverage.numerator === null) {
+function outcomeCounts(rows) {
+  const counts2 = { bothSignals: 0, mentionedOnly: 0, citedOnly: 0, neither: 0, notMeasured: 0, total: rows.length };
+  for (const row of rows) {
+    if (row.mention === null || row.citation === null) {
       counts2.notMeasured++;
-    } else if (metrics.mentionCoverage.numerator > 0 && metrics.citationCoverage.numerator > 0) {
+    } else if (row.mention && row.citation) {
       counts2.bothSignals++;
-    } else if (metrics.mentionCoverage.numerator > 0) {
+    } else if (row.mention) {
       counts2.mentionedOnly++;
-    } else if (metrics.citationCoverage.numerator > 0) {
+    } else if (row.citation) {
       counts2.citedOnly++;
     } else {
       counts2.neither++;
@@ -22223,19 +22393,20 @@ function coverageSummary(candidates, definition, targets = targetMap(definition)
     rows,
     queryCount: new Set(rows.map((candidate) => candidate.slot.queryKey)).size,
     answerCount: rows.filter(answered).length,
-    mentionCoverage: rate(rows.map((candidate) => targetValues(candidate, targets).mention), rows.length),
-    citationCoverage: rate(rows.map((candidate) => targetValues(candidate, targets).citation), rows.length)
+    mentionCoverage: mentionRate2(rows, targets),
+    citationCoverage: rate(rows.map((candidate) => citationForCoverage(candidate, targets)), rows.length)
   };
 }
 function summary(candidates, definition, populationTargetKeys = selectedTargetKeys(candidates)) {
   const targets = targetMap(definition);
   const base = coverageSummary(candidates, definition, targets);
   const { rows } = base;
-  const targetRows = populationTargetKeys.map((targetKey) => ({ targetKey, ...targetMetrics(rows, targets, targetKey) }));
+  const targetRows = populationTargetKeys.map((targetKey) => targetPresence(rows, targets, targetKey));
   const eligibleTargets = targetRows.filter((row) => targets.get(row.targetKey)?.mentionEligible === true);
   const propertyReach = rate(
-    eligibleTargets.map((row) => row.mentionCoverage.numerator === null ? null : row.mentionCoverage.numerator > 0),
-    eligibleTargets.length
+    eligibleTargets.map((row) => row.mention),
+    eligibleTargets.length,
+    eligibleTargets.some((row) => row.mention === null && row.identityAmbiguous) ? "identity-ambiguous" : "evidence-incomplete"
   );
   return {
     queryCount: base.queryCount,
@@ -22243,7 +22414,7 @@ function summary(candidates, definition, populationTargetKeys = selectedTargetKe
     mentionCoverage: base.mentionCoverage,
     citationCoverage: base.citationCoverage,
     propertyReach,
-    outcomes: outcomeCounts(rows, targets, populationTargetKeys)
+    outcomes: outcomeCounts(targetRows)
   };
 }
 function queryRows(candidates, definition, selection) {
@@ -22290,6 +22461,7 @@ function evidenceRows(candidates, definition, selection) {
       location: candidate.slot.location,
       targetKeys: selectedTargetKeys([candidate]),
       mentioned: signals.mention,
+      ...signals.mentionUnavailableReason === void 0 ? {} : { mentionUnavailableReason: signals.mentionUnavailableReason },
       cited: signals.citation,
       // Answer bodies are intentionally limited to the stable query-key
       // drill-in. A query-id is enough to locate an evidence page, but it
@@ -22360,8 +22532,8 @@ function breakdown(candidates, definition, populationTargetKeys = selectedTarget
   const groups = definition.groups.map((group) => ({ group, targetKeys: group.targetKeys.filter((targetKey) => populationTargetSet.has(targetKey)) })).filter(({ targetKeys }) => targetKeys.length > 0).map(({ group, targetKeys }) => {
     const groupTargetKeys = new Set(targetKeys);
     const own = candidates.map((candidate) => narrowedToTargetKeys(candidate, groupTargetKeys)).filter((candidate) => candidate !== null);
-    const metrics = rate(own.map((candidate) => targetValues(candidate, targets).mention), own.length);
-    const citations = rate(own.map((candidate) => targetValues(candidate, targets).citation), own.length);
+    const metrics = mentionRate2(own, targets);
+    const citations = rate(own.map((candidate) => citationForCoverage(candidate, targets)), own.length);
     return {
       id: group.id,
       label: group.label,
@@ -22756,52 +22928,42 @@ function v2Definition(plan, revision, manifest, run) {
     edges
   };
 }
-function v2Observations(plan, revision, run, snapshots) {
+function v2Observations(plan, revision, run, snapshots, includeEvidence = true) {
   const manifest = measurementRunExpectedSlots(run, plan);
   const materialized = buildMeasurementPlanV2ReportInput(revision, plan, manifest, adapterSnapshots(snapshots));
-  const evidence = buildMeasurementEvidence(materialized.input);
+  const signalsByObservation = new Map(buildMeasurementObservationSignals(materialized.input).map((signal) => [signal.observationId, signal]));
   const rawById = new Map(snapshots.map((snapshot) => [snapshot.id, snapshot]));
-  const answersByObservation = /* @__PURE__ */ new Map();
-  for (const answer of evidence.answers) {
-    const rows = answersByObservation.get(answer.observationId) ?? [];
-    rows.push(answer);
-    answersByObservation.set(answer.observationId, rows);
-  }
-  const edgeById = new Map(materialized.input.usageEdges.map((edge) => [edge.id, edge]));
   const competitors2 = exactCompetitorMatchers(plan);
   const output = [];
   for (const observation of materialized.input.observations) {
     const raw = rawById.get(observation.id);
     if (!raw || observation.executionId === null) continue;
-    const answers = answersByObservation.get(observation.id) ?? [];
-    const targetFor = (answer) => {
-      const edge = edgeById.get(answer.usageEdgeId);
-      return edge?.type === "target" ? edge.targetId : null;
-    };
-    const signals = competitorSignals(raw, competitors2);
+    const attribution = signalsByObservation.get(observation.id);
+    const signals = includeEvidence ? competitorSignals(raw, competitors2) : { mentioned: [], cited: [] };
     output.push({
       slotId: `slot:${observation.executionId}:${observation.provider}`,
       answerId: raw.id,
       model: raw.servedModel?.trim() || null,
-      answerText: raw.answerText,
+      answerText: includeEvidence ? raw.answerText : null,
       // `answerMentioned` is the legacy project-level boolean. It cannot say
       // WHICH Property an answer named, so a portfolio may use it neither as
       // a positive nor as a measured negative when the answer body is absent.
       mentionComplete: raw.answerText !== null,
-      mentionedTargetKeys: answers.filter((answer) => answer.mentioned === true).map(targetFor).filter((value) => value !== null),
-      citedTargetKeys: answers.filter((answer) => answer.cited === true).map(targetFor).filter((value) => value !== null),
-      citationComplete: answers.length > 0 && answers.every((answer) => answer.evidenceComplete),
+      mentionedTargetKeys: attribution?.mentionedTargetIds ?? [],
+      unknownMentionTargetKeys: attribution?.unknownMentionTargetIds ?? [],
+      citedTargetKeys: attribution?.citedTargetIds ?? [],
+      citationComplete: attribution?.sourceComplete ?? false,
       competitorMentionDomains: signals.mentioned,
       competitorCitationDomains: signals.cited,
-      observedCompetitorNames: observedCompetitorNames2(raw.recommendedCompetitors),
-      sources: [...new Set(answers.flatMap((answer) => answer.sources.map((source) => source.sourceUrl)))],
+      observedCompetitorNames: includeEvidence ? observedCompetitorNames2(raw.recommendedCompetitors) : [],
+      sources: includeEvidence ? attribution?.sourceUrls ?? [] : [],
       createdAt: raw.createdAt
     });
   }
   return { manifest, observations: output };
 }
-function advancedRun(run, version, plan, snapshots, comparableDefinitionIds) {
-  const populated = v2Observations(plan, version.revision, run, snapshots);
+function advancedRun(run, version, plan, snapshots, comparableDefinitionIds, includeEvidence = true) {
+  const populated = v2Observations(plan, version.revision, run, snapshots, includeEvidence);
   return {
     id: run.id,
     createdAt: run.createdAt,
@@ -22848,7 +23010,7 @@ function simpleModelFingerprint(definition) {
   const engines = [...definition.engines].map((engine) => ({ provider: normalizedText3(engine.provider), requestedModel: engine.requestedModel })).sort((left, right) => left.provider.localeCompare(right.provider, "en"));
   return `simple-model:${createHash4("sha256").update(JSON.stringify(engines)).digest("hex")}`;
 }
-function frozenSimpleRun(run, definition, snapshots) {
+function frozenSimpleRun(run, definition, snapshots, includeEvidence = true) {
   const matcher = compileBrandAliases(effectiveBrandNames({
     displayName: definition.identity.displayName,
     aliases: definition.identity.aliases,
@@ -22896,20 +23058,20 @@ function frozenSimpleRun(run, definition, snapshots) {
     if (!slotKeys.has(slotId)) throw new Error(`Frozen simple definition has no slot for stored snapshot ${snapshot.id}`);
     const preparedAnswerText = prepareBrandMatchText(snapshot.answerText);
     const mentioned = snapshot.answerText !== null ? matcherMatchesText(matcher, preparedAnswerText) : snapshot.answerMentioned === true;
-    const competitorSignalsForSnapshot = competitors2 === null ? { mentioned: [], cited: [] } : competitorSignals(snapshot, competitors2, preparedAnswerText);
+    const competitorSignalsForSnapshot = !includeEvidence || competitors2 === null ? { mentioned: [], cited: [] } : competitorSignals(snapshot, competitors2, preparedAnswerText);
     observations.push({
       slotId,
       answerId: snapshot.id,
       model: snapshot.servedModel?.trim() || null,
-      answerText: snapshot.answerText,
+      answerText: includeEvidence ? snapshot.answerText : null,
       mentionComplete: snapshot.answerText !== null || snapshot.answerMentioned !== null,
       mentionedTargetKeys: mentioned ? ["project"] : [],
       citedTargetKeys: snapshot.citationState === "cited" ? ["project"] : [],
       citationComplete: true,
       competitorMentionDomains: competitorSignalsForSnapshot.mentioned,
       competitorCitationDomains: competitorSignalsForSnapshot.cited,
-      observedCompetitorNames: observedCompetitorNames2(snapshot.recommendedCompetitors),
-      sources: snapshot.citedUrls ?? [],
+      observedCompetitorNames: includeEvidence ? observedCompetitorNames2(snapshot.recommendedCompetitors) : [],
+      sources: includeEvidence ? snapshot.citedUrls ?? [] : [],
       createdAt: snapshot.createdAt
     });
   }
@@ -22941,7 +23103,7 @@ function frozenSimpleRun(run, definition, snapshots) {
     observations
   };
 }
-function legacySimpleRun(project, run, snapshots) {
+function legacySimpleRun(project, run, snapshots, includeEvidence = true) {
   const slots = snapshots.map((snapshot) => ({
     id: `slot:legacy:${snapshot.id}`,
     executionId: `legacy:${snapshot.id}`,
@@ -22979,7 +23141,7 @@ function legacySimpleRun(project, run, snapshots) {
       slotId: `slot:legacy:${snapshot.id}`,
       answerId: snapshot.id,
       model: snapshot.servedModel?.trim() || null,
-      answerText: snapshot.answerText,
+      answerText: includeEvidence ? snapshot.answerText : null,
       // A legacy answer body cannot be matched against today's identity. Only
       // the stored boolean is a frozen mention fact; null stays incomplete.
       mentionComplete: snapshot.answerMentioned !== null,
@@ -22988,8 +23150,8 @@ function legacySimpleRun(project, run, snapshots) {
       citationComplete: true,
       competitorMentionDomains: [],
       competitorCitationDomains: [],
-      observedCompetitorNames: observedCompetitorNames2(snapshot.recommendedCompetitors),
-      sources: snapshot.citedUrls ?? [],
+      observedCompetitorNames: includeEvidence ? observedCompetitorNames2(snapshot.recommendedCompetitors) : [],
+      sources: includeEvidence ? snapshot.citedUrls ?? [] : [],
       createdAt: snapshot.createdAt
     }))
   };
@@ -23127,41 +23289,37 @@ function advancedReaderInput(db, projectId, active, query) {
   const presentationComparableIds = new Set(comparableVersionIds(allVersionRowsById, presentationVersion.id));
   const activeComparableIds = new Set(comparableVersionIds(allVersionRowsById, active.version.id));
   const sourceRuns = completedVisibilityRuns(db, projectId, false, query);
-  const snapshotsByRun = loadVisibilitySnapshots(db, sourceRuns.map((run) => run.id));
   const sourceCandidates = sourceRuns.flatMap((run) => {
     if (run.measurementPlanVersionId === null) return [];
     const source = versions.get(run.measurementPlanVersionId);
-    if (!source) return [];
-    const own = advancedRun(
-      run,
-      source.row,
-      source.plan,
-      snapshotsByRun.get(run.id) ?? [],
-      comparableVersionIds(allVersionRowsById, source.row.id)
-    );
-    return [{ run, source, own }];
-  }).filter((candidate) => query.revision === void 0 || presentationComparableIds.has(candidate.source.row.id));
+    if (!source || query.revision !== void 0 && !presentationComparableIds.has(source.row.id)) return [];
+    return [{ run, source }];
+  });
   if (query.runId !== void 0 && !sourceCandidates.some((candidate) => candidate.run.id === query.runId)) {
     throw validationError(`Measurement run "${query.runId}" is not an eligible advanced result.`);
   }
+  const compatibleSourceCandidates = sourceCandidates.filter((candidate) => activeComparableIds.has(candidate.source.row.id));
+  const preferredSource = query.runId === void 0 ? compatibleSourceCandidates.at(0) ?? sourceCandidates.at(0) : void 0;
+  const selectedSource = query.runId === void 0 ? preferredSource : sourceCandidates.find((candidate) => candidate.run.id === query.runId);
   const candidates = sourceCandidates.map((candidate) => {
-    if (candidate.source.row.id === presentationVersion.id) return candidate.own;
-    if (!presentationComparableIds.has(candidate.source.row.id)) return candidate.own;
+    const usePresentation = presentationComparableIds.has(candidate.source.row.id);
+    const version = usePresentation ? presentationVersion : candidate.source.row;
+    const plan = usePresentation ? presentationPlan : candidate.source.plan;
+    const snapshots = loadVisibilitySnapshots(db, [candidate.run.id]).get(candidate.run.id) ?? [];
     return advancedRun(
       candidate.run,
-      presentationVersion,
-      presentationPlan,
-      snapshotsByRun.get(candidate.run.id) ?? [],
-      [...presentationComparableIds]
+      version,
+      plan,
+      snapshots,
+      usePresentation ? [...presentationComparableIds] : comparableVersionIds(allVersionRowsById, candidate.source.row.id),
+      candidate.run.id === selectedSource?.run.id
     );
   });
-  const compatibleSourceCandidates = sourceCandidates.filter((candidate) => activeComparableIds.has(candidate.source.row.id));
-  const preferredSource = query.runId === void 0 ? compatibleSourceCandidates.at(0) ?? sourceCandidates.at(0) : void 0;
-  const selectedSource = query.runId === void 0 ? preferredSource : sourceCandidates.find((candidate) => candidate.run.id === query.runId);
+  const selectedDefinition = candidates.find((candidate) => candidate.id === selectedSource?.run.id)?.definition;
   return {
     mode: "advanced",
     activeRevision: active.version.revision,
-    pendingAssignmentCount: selectedSource !== void 0 && activeComparableIds.has(selectedSource.source.row.id) ? 0 : pendingAssignments(active.plan, selectedSource?.source.plan, selectedSource?.own.definition),
+    pendingAssignmentCount: selectedSource !== void 0 && activeComparableIds.has(selectedSource.source.row.id) ? 0 : pendingAssignments(active.plan, selectedSource?.source.plan, selectedDefinition),
     selection: query,
     activeDefinition: activeV2Definition(presentationPlan, presentationVersion.revision),
     ...preferredSource === void 0 ? {} : { preferredRunId: preferredSource.run.id },
@@ -23174,11 +23332,12 @@ function simpleReaderInput(db, project, query) {
     eq24(simpleMeasurementDefinitions.projectId, project.id),
     inArray9(simpleMeasurementDefinitions.runId, sourceRuns.map((run) => run.id))
   )).all().map((row) => [row.runId, row.definition]));
-  const snapshotsByRun = loadVisibilitySnapshots(db, sourceRuns.map((run) => run.id));
+  const selectedRunId = sourceRuns[0]?.id;
   const candidates = sourceRuns.map((run) => {
-    const snapshots = snapshotsByRun.get(run.id) ?? [];
+    const snapshots = loadVisibilitySnapshots(db, [run.id]).get(run.id) ?? [];
     const definition = frozen.get(run.id);
-    return definition ? frozenSimpleRun(run, definition, snapshots) : legacySimpleRun(project, run, snapshots);
+    const includeEvidence = run.id === selectedRunId;
+    return definition ? frozenSimpleRun(run, definition, snapshots, includeEvidence) : legacySimpleRun(project, run, snapshots, includeEvidence);
   });
   if (query.runId !== void 0 && !candidates.some((run) => run.id === query.runId)) {
     throw validationError(`Measurement run "${query.runId}" is not an eligible simple result.`);
@@ -23192,37 +23351,28 @@ function simpleReaderInput(db, project, query) {
     runs: candidates
   };
 }
+function readVisibilityReport(db, project, rawQuery) {
+  const query = parseQuery(rawQuery);
+  const active = activeMeasurementPlan(db, project.id);
+  const mode = query.mode === "auto" ? active === null ? "simple" : "advanced" : query.mode;
+  try {
+    if (mode === "advanced") {
+      if (active === null) throw validationError("This project has no advanced measurement plan.");
+      if (active.plan.schemaVersion !== MEASUREMENT_PLAN_V2_SCHEMA_VERSION) return unsupportedAdvancedResponse(query, active);
+      return buildVisibilityReport(advancedReaderInput(db, project.id, active, query));
+    }
+    return buildVisibilityReport(simpleReaderInput(db, project, query));
+  } catch (error) {
+    if (error instanceof VisibilityReportCursorError || error instanceof VisibilityReportScopeError) {
+      throw validationError(error.message);
+    }
+    throw error;
+  }
+}
 async function visibilityReportRoutes(app) {
   app.get(
     "/projects/:name/visibility-report",
-    async (request) => {
-      const project = resolveProject(app.db, request.params.name);
-      const query = parseQuery(request.query);
-      const active = activeMeasurementPlan(app.db, project.id);
-      const mode = query.mode === "auto" ? active === null ? "simple" : "advanced" : query.mode;
-      if (mode === "advanced") {
-        if (active === null) throw validationError("This project has no advanced measurement plan.");
-        if (active.plan.schemaVersion !== MEASUREMENT_PLAN_V2_SCHEMA_VERSION) {
-          return unsupportedAdvancedResponse(query, active);
-        }
-        try {
-          return buildVisibilityReport(advancedReaderInput(app.db, project.id, active, query));
-        } catch (error) {
-          if (error instanceof VisibilityReportCursorError || error instanceof VisibilityReportScopeError) {
-            throw validationError(error.message);
-          }
-          throw error;
-        }
-      }
-      try {
-        return buildVisibilityReport(simpleReaderInput(app.db, project, query));
-      } catch (error) {
-        if (error instanceof VisibilityReportCursorError || error instanceof VisibilityReportScopeError) {
-          throw validationError(error.message);
-        }
-        throw error;
-      }
-    }
+    async (request) => readVisibilityReport(app.db, resolveProject(app.db, request.params.name), request.query)
   );
 }
 
@@ -23471,6 +23621,7 @@ function frozenAssignmentSignature(plan, assignment) {
     target: {
       stableKey: target.stableKey,
       aliases: target.aliases,
+      ...target.identityAliases === void 0 ? {} : { identityAliases: target.identityAliases },
       urlMatchers: target.urlMatchers,
       mentionNotApplicable: target.mentionNotApplicable,
       discoveryIdentity: target.discoveryIdentity
@@ -23972,6 +24123,7 @@ function compileExecution(state, target, queryId, queryText, queryClass, classif
       label: target.label,
       status: "included",
       aliases: [...target.aliases],
+      ...target.identityAliases === void 0 ? {} : { identityAliases: [...target.identityAliases] },
       urlMatchers: target.urlMatchers.map(draftMatcher),
       source: target.discoveryIdentity ? "sitemap" : "manual",
       ...target.discoveryIdentity ? { discoveryIdentity: target.discoveryIdentity } : {}
@@ -28735,10 +28887,10 @@ function renderExecutiveSummary(report) {
   const trendLabel = s.trend === "up" ? "\u2191 Up" : s.trend === "down" ? "\u2193 Down" : s.trend === "flat" ? "\u2192 Flat" : "\u2014";
   const trendTone = s.trend === "up" ? "positive" : s.trend === "down" ? "negative" : "neutral";
   const queryNoun = s.totalQueryCount === 1 ? "query" : "queries";
-  const citedFragment = s.totalQueryCount > 0 ? `${s.citedQueryCount}/${s.totalQueryCount} ${queryNoun} cited` : "no queries";
-  const mentionedFragment = s.totalQueryCount > 0 ? `${s.mentionedQueryCount}/${s.totalQueryCount} ${queryNoun} mentioned` : "no queries";
-  const headlineTitle = s.totalQueryCount > 0 ? `${s.citedQueryCount} of ${s.totalQueryCount} tracked ${queryNoun} cite ${report.meta.project.displayName}` : "No AI citation data yet";
-  const headlineSubtitle = s.totalQueryCount > 0 ? `${s.citationRate}% citation coverage and ${s.mentionRate}% mention coverage across ${s.providerCount} ${pluralize(s.providerCount, "provider")}.` : "Run a check to populate the first citation and mention baseline.";
+  const citedFragment = (s.totalQueryCount ?? 0) > 0 ? `${s.citedQueryCount}/${s.totalQueryCount} ${queryNoun} cited` : "no queries";
+  const mentionedFragment = (s.totalQueryCount ?? 0) > 0 ? `${s.mentionedQueryCount}/${s.totalQueryCount} ${queryNoun} mentioned` : "no queries";
+  const headlineTitle = (s.totalQueryCount ?? 0) > 0 ? `${s.citedQueryCount} of ${s.totalQueryCount} tracked ${queryNoun} cite ${report.meta.project.displayName}` : "No AI citation data yet";
+  const headlineSubtitle = (s.totalQueryCount ?? 0) > 0 ? `${s.citationRate}% citation coverage and ${s.mentionRate}% mention coverage across ${s.providerCount} ${pluralize(s.providerCount, "provider")}.` : "Run a check to populate the first citation and mention baseline.";
   const priorityActions = report.agencyDiagnostics.priorities.length > 0 ? report.agencyDiagnostics.priorities : report.actionPlan;
   const actionCount = dedupeReportActions(report, priorityActions).length;
   const heroHtml = `<div class="executive-hero">
@@ -29835,9 +29987,9 @@ function renderAudienceActionPlan(report, audience) {
 function renderClientSummary(report) {
   const s = report.executiveSummary;
   const sc = report.citationScorecard;
-  const totalQ = s.totalQueryCount;
+  const totalQ = s.totalQueryCount ?? 0;
   const heroNumber = totalQ > 0 ? `${s.mentionRate}%` : "\u2014";
-  const heroSentence = totalQ > 0 ? `When customers asked AI ${totalQ} ${pluralize(totalQ, "query", "queries")} about your industry, AI mentioned you in ${s.mentionedQueryCount} of ${totalQ === 1 ? "them" : "those answers"}.` : "No AI check has been run yet. Run a check to see how AI tools answer customer queries about your business.";
+  const heroSentence = totalQ > 0 ? `When customers asked AI ${totalQ} ${pluralize(totalQ, "query", "queries")} about your industry, AI mentioned you in ${s.mentionedQueryCount} of ${totalQ === 1 ? "them" : "those queries"}.` : "No AI check has been run yet. Run a check to see how AI tools answer customer queries about your business.";
   const trend = clientTrendCopy(report.whatsChanged.mentionRate);
   const heroTrend = trend ? `<p class="client-hero-trend tone-${trend.tone}"><span style="margin-right:6px;">${trend.arrow}</span>${escapeHtml2(trend.text)}</p>` : "";
   const hero = `<div class="client-hero">
@@ -29851,12 +30003,12 @@ function renderClientSummary(report) {
     <div class="client-metric-tile">
       <div class="label">AI mentions your name</div>
       <div class="value">${s.mentionRate}%</div>
-      <div class="subtitle">${totalQ > 0 ? `Says your name in ${s.mentionedQueryCount} of ${totalQ} ${pluralize(totalQ, "answer")}` : "No data yet"}</div>
+      <div class="subtitle">${totalQ > 0 ? `Says your name in ${s.mentionedQueryCount} of ${totalQ} ${pluralize(totalQ, "query", "queries")}` : "No data yet"}</div>
     </div>
     <div class="client-metric-tile">
       <div class="label">AI links to your website</div>
       <div class="value">${s.citationRate}%</div>
-      <div class="subtitle">${totalQ > 0 ? `Cites your site as a source in ${s.citedQueryCount} of ${totalQ} ${pluralize(totalQ, "answer")}` : "No data yet"}</div>
+      <div class="subtitle">${totalQ > 0 ? `Cites your site as a source in ${s.citedQueryCount} of ${totalQ} ${pluralize(totalQ, "query", "queries")}` : "No data yet"}</div>
     </div>
     <div class="client-metric-tile">
       <div class="label">AI tools tested</div>
@@ -29997,9 +30149,9 @@ function renderReportHtml(report, opts = {}) {
   const audience = opts.audience ?? "agency";
   const title = opts.title ?? `Canonry ${audience} report \u2014 ${report.meta.project.displayName}`;
   const sections = audience === "client" ? [
-    renderClientSummary(report),
-    renderReportShareOfVoice(report),
-    renderWhatsChanged(report, "client"),
+    report.visibility ? renderReportVisibility(report.visibility) : renderClientSummary(report),
+    report.visibility?.selection.mode === "advanced" ? "" : renderReportShareOfVoice(report),
+    report.visibility ? "" : renderWhatsChanged(report, "client"),
     // Server-side AI visibility runs between WhatsChanged and the action
     // plan in BOTH the SPA and HTML so clients see the same ordered set
     // of sections in either surface (per the report-parity rule).
@@ -30007,13 +30159,13 @@ function renderReportHtml(report, opts = {}) {
     renderAudienceActionPlan(report, "client"),
     renderClientEvidenceSummary(report)
   ].join("\n") : [
-    renderExecutiveSummary(report),
-    renderReportShareOfVoice(report),
-    renderWhatsChanged(report, "agency"),
+    report.visibility ? renderReportVisibility(report.visibility) : renderExecutiveSummary(report),
+    report.visibility?.selection.mode === "advanced" ? "" : renderReportShareOfVoice(report),
+    report.visibility ? "" : renderWhatsChanged(report, "agency"),
     renderAudienceActionPlan(report, "agency"),
-    renderAgencyDiagnostics(report),
-    renderCitationScorecard(report),
-    renderCompetitorLandscape(report),
+    report.visibility?.selection.mode === "advanced" ? "" : renderAgencyDiagnostics(report),
+    report.visibility?.selection.mode === "advanced" ? "" : renderCitationScorecard(report),
+    report.visibility?.selection.mode === "advanced" ? "" : renderCompetitorLandscape(report),
     renderAiSourceOrigin(report),
     renderGsc(report),
     renderGa(report),
@@ -30021,7 +30173,7 @@ function renderReportHtml(report, opts = {}) {
     renderAiReferrals(report),
     renderServerActivity(report, "agency"),
     renderIndexingHealth(report),
-    renderCitationsTrend(report),
+    report.visibility?.selection.mode === "advanced" ? "" : renderCitationsTrend(report),
     renderInsights(report),
     renderOpportunities(report),
     renderContentGaps(report),
@@ -30043,7 +30195,7 @@ function renderReportHtml(report, opts = {}) {
   <header class="header">
     <div class="eyebrow">AI Visibility Report</div>
     <h1>${escapeHtml2(report.meta.project.displayName)}</h1>
-    <div class="subtitle">${escapeHtml2(report.meta.project.canonicalDomain)} \xB7 ${escapeHtml2(report.meta.project.country)} / ${escapeHtml2(report.meta.project.language.toUpperCase())}${renderHeaderLocationFragment(report.meta.location)} \xB7 Last ${report.meta.periodDays} days \xB7 Generated ${formatDate(report.meta.generatedAt)}</div>
+    <div class="subtitle">${escapeHtml2(report.meta.project.canonicalDomain)} \xB7 ${escapeHtml2(report.meta.project.country)} / ${escapeHtml2(report.meta.project.language.toUpperCase())}${report.visibility?.selection.mode === "advanced" ? ` \xB7 ${escapeHtml2(reportVisibilityLocationLabel(report.visibility))}` : renderHeaderLocationFragment(report.meta.location)} \xB7 Last ${report.meta.periodDays} days \xB7 Generated ${formatDate(report.meta.generatedAt)}</div>
   </header>
   ${sections}
   <footer class="footer">Generated by <a href="https://canonry.ai">canonry</a> \xB7 ${escapeHtml2(formatIsoDate(report.meta.generatedAt))}</footer>
@@ -30052,6 +30204,15 @@ function renderReportHtml(report, opts = {}) {
 </body>
 </html>`;
 }
+function renderReportVisibility(visibility) {
+  const populations = visibility.populations.filter((population) => population.queryClass !== "unknown" || population.summary.answerCount > 0);
+  const historyPopulations = visibility.populations.filter((population) => population.queryClass !== "unknown" || population.trend.some((point) => point.answerCount > 0));
+  const rateCell = (rate2) => `<td><strong>${escapeHtml2(reportVisibilityRate(rate2))}</strong><p class="muted">${escapeHtml2(reportVisibilityEvidence(rate2))}</p></td>`;
+  const headers = (labels) => `<thead><tr>${labels.map((label) => `<th>${escapeHtml2(label)}</th>`).join("")}</tr></thead>`;
+  const summary2 = `<table>${headers([REPORT_VISIBILITY_COPY.queryType, REPORT_VISIBILITY_COPY.queries, REPORT_VISIBILITY_COPY.answers, REPORT_VISIBILITY_COPY.mentioned, REPORT_VISIBILITY_COPY.cited])}<tbody>${populations.map((population) => `<tr><td>${escapeHtml2(reportQueryClassLabel(population.queryClass))}</td><td>${population.summary.queryCount}</td><td>${population.summary.answerCount}</td>${rateCell(population.summary.mentionCoverage)}${rateCell(population.summary.citationCoverage)}</tr>`).join("")}</tbody></table>`;
+  const trend = `<details><summary>${escapeHtml2(reportVisibilityHistoryLabel(visibility))}</summary><div class="table-scroll"><table>${headers([REPORT_VISIBILITY_COPY.date, REPORT_VISIBILITY_COPY.queryType, REPORT_VISIBILITY_COPY.mentioned, REPORT_VISIBILITY_COPY.cited, REPORT_VISIBILITY_COPY.comparison])}<tbody>${historyPopulations.flatMap((population) => population.trend.map((point) => `<tr><td><time datetime="${escapeHtml2(point.createdAt)}">${escapeHtml2(point.createdAt.slice(0, 10))}</time></td><td>${escapeHtml2(reportQueryClassLabel(population.queryClass))}</td>${rateCell(point.mentionCoverage)}${rateCell(point.citationCoverage)}<td>${escapeHtml2(reportVisibilityComparison(point.continuity.state, point.continuity.comparedRunId !== null && !population.trend.some((previous) => previous.runId === point.continuity.comparedRunId)))}</td></tr>`)).join("")}</tbody></table></div></details>`;
+  return `<section id="client-summary" class="report-section" aria-label="${escapeHtml2(REPORT_VISIBILITY_COPY.title)}"><h2>${escapeHtml2(REPORT_VISIBILITY_COPY.title)}</h2><p>${escapeHtml2(visibility.selection.mode === "advanced" ? REPORT_VISIBILITY_COPY.description : REPORT_VISIBILITY_COPY.simpleDescription)}</p><p>${escapeHtml2(reportVisibilityMeasurementLabel(visibility))}</p><div class="table-scroll">${summary2}</div>${trend}</section>`;
+}
 
 // ../api-routes/src/ga-ai-referral-aggregation.ts
 function normalizeAiTrafficClass(value) {
@@ -30913,7 +31074,6 @@ function buildIndexingHealth(db, projectId) {
 }
 function buildCitationsTrend(db, projectId, queryLookup, locationFilter) {
   const visibilityRuns = db.select().from(runs).where(and29(eq33(runs.projectId, projectId), eq33(runs.kind, RunKinds["answer-visibility"]), notProbeRun())).all().filter((r) => locationFilter === void 0 || (r.location ?? null) === locationFilter);
-  const totalQueries = queryLookup.byId.size;
   const points = [];
   for (const run of visibilityRuns) {
     if (run.status !== RunStatuses.completed) continue;
@@ -30935,10 +31095,11 @@ function buildCitationsTrend(db, projectId, queryLookup, locationFilter) {
       providerCounts.set(snap.provider, counts2);
     }
     if (considered === 0) continue;
+    const totalQueries = new Set(snaps.map((snapshot) => snapshot.queryId)).size;
     const citedQueryCount = citedQueryIds.size;
     const mentionedQueryCount = mentionedQueryIds.size;
     const citationRate = totalQueries > 0 ? Math.round(citedQueryCount / totalQueries * 100) : 0;
-    const mentionRate2 = totalQueries > 0 ? Math.round(mentionedQueryCount / totalQueries * 100) : 0;
+    const mentionRate3 = totalQueries > 0 ? Math.round(mentionedQueryCount / totalQueries * 100) : 0;
     const providerRates = [...providerCounts.entries()].map(([provider, counts2]) => ({
       provider,
       citationRate: counts2.total > 0 ? Math.round(counts2.cited / counts2.total * 100) : 0,
@@ -30950,7 +31111,7 @@ function buildCitationsTrend(db, projectId, queryLookup, locationFilter) {
       citationRate,
       citedQueryCount,
       totalQueryCount: totalQueries,
-      mentionRate: mentionRate2,
+      mentionRate: mentionRate3,
       mentionedQueryCount,
       providerRates
     });
@@ -31310,7 +31471,7 @@ function buildReportActionPlan(input) {
     });
   }
   if (actions.length === 0) {
-    const neverMeasured = input.citationScorecard.providers.length === 0;
+    const neverMeasured = !(input.hasVisibilityMeasurement ?? input.citationScorecard.providers.length > 0);
     actions.push({
       audience: "both",
       priority: 90,
@@ -31343,12 +31504,12 @@ function mentionTrendSentence(delta) {
 function buildClientSummary(reportLike) {
   const s = reportLike.executiveSummary;
   const queryNoun = s.totalQueryCount === 1 ? "query" : "queries";
-  const headline = s.totalQueryCount > 0 ? `${s.mentionedQueryCount} of ${s.totalQueryCount} tracked ${queryNoun} mention the brand in AI answers` : "No tracked queries have completed a check yet";
-  const overview = s.totalQueryCount > 0 ? `${reportLike.canonicalDomain} is mentioned on ${s.mentionRate}% of tracked queries and cited on ${s.citationRate}% of tracked queries. ${mentionTrendSentence(reportLike.whatsChanged.mentionRate)}` : "At least one completed check is needed before this can summarize how the brand appears in AI answers.";
+  const headline = (s.totalQueryCount ?? 0) > 0 ? `${s.mentionedQueryCount} of ${s.totalQueryCount} tracked ${queryNoun} mention the brand in AI answers` : "No tracked queries have completed a check yet";
+  const overview = (s.totalQueryCount ?? 0) > 0 ? `${reportLike.canonicalDomain} is mentioned on ${s.mentionRate}% of tracked queries and cited on ${s.citationRate}% of tracked queries. ${mentionTrendSentence(reportLike.whatsChanged.mentionRate)}` : "At least one completed check is needed before this can summarize how the brand appears in AI answers.";
   const confidenceNotes = [];
   if (s.totalQueryCount === 0) {
     confidenceNotes.push("Confidence is low until the first tracked query check completes.");
-  } else if (s.totalQueryCount < 5) {
+  } else if ((s.totalQueryCount ?? 0) < 5) {
     confidenceNotes.push("Directional read: the tracked query set is still small, so each query has outsized impact on the percentage.");
   }
   if (isTrendBaseline(reportLike.citationsTrend)) {
@@ -31473,7 +31634,7 @@ function buildWhatsChanged(input) {
     direction: rateDirection(citationRateSmoothed.deltaAbs, RATE_REAL_MOVEMENT_THRESHOLD_PP)
   } : null;
   const mentionRateSmoothed = smoothedRunDelta(citationsTrend, (p) => p.mentionRate);
-  const mentionRate2 = enoughHistory && mentionRateSmoothed ? {
+  const mentionRate3 = enoughHistory && mentionRateSmoothed ? {
     ...mentionRateSmoothed,
     direction: rateDirection(mentionRateSmoothed.deltaAbs, RATE_REAL_MOVEMENT_THRESHOLD_PP)
   } : null;
@@ -31520,7 +31681,7 @@ function buildWhatsChanged(input) {
     enoughHistory,
     headline,
     citationRate,
-    mentionRate: mentionRate2,
+    mentionRate: mentionRate3,
     citedQueryCount,
     mentionedQueryCount,
     gscClicksDelta,
@@ -31534,14 +31695,30 @@ function buildWhatsChanged(input) {
 function buildProjectReport(db, projectName, periodDays) {
   const project = resolveProject(db, projectName);
   const queryLookup = loadQueryLookup(db, project.id);
+  const canonicalVisibility = readVisibilityReport(db, project, { queryClass: "all", scope: "project" });
+  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const historyWindow = { from: new Date(Date.parse(generatedAt) - periodDays * 864e5).toISOString(), to: generatedAt };
+  const visibility = {
+    selection: canonicalVisibility.selection,
+    historyWindow,
+    populations: canonicalVisibility.populations.map(({ queryClass, summary: summary2, trend: trend2 }) => ({
+      queryClass,
+      summary: summary2,
+      // Keep each point's actual comparison. Renderers disclose when the prior
+      // measurement is outside this window rather than inventing a baseline.
+      trend: trend2.filter((point) => point.createdAt >= historyWindow.from && point.createdAt <= historyWindow.to)
+    }))
+  };
+  const canonicalVisibilitySupported = visibility.selection.availability.state === "available";
+  const advancedVisibility = canonicalVisibilitySupported && visibility.selection.mode === "advanced";
   const comparisonWindowDays = reportComparisonWindowDays(periodDays);
   const allRuns = db.select().from(runs).where(and29(eq33(runs.projectId, project.id), notProbeRun())).orderBy(desc14(runs.createdAt), desc14(runs.id)).all();
   const visibilityRuns = allRuns.filter((r) => r.kind === RunKinds["answer-visibility"]);
   const completedVisRunGroups = groupRunsByCreatedAt(
     visibilityRuns.filter((r) => r.status === RunStatuses.completed || r.status === RunStatuses.partial)
   );
-  const latestVisRunGroup = completedVisRunGroups[0] ?? [];
-  const representativeLatestRun = pickGroupRepresentative(latestVisRunGroup) ?? visibilityRuns[0] ?? null;
+  const latestVisRunGroup = advancedVisibility ? visibilityRuns.filter((run) => run.id === visibility.selection.run.id) : completedVisRunGroups[0] ?? [];
+  const representativeLatestRun = pickGroupRepresentative(latestVisRunGroup) ?? (advancedVisibility ? null : visibilityRuns[0] ?? null);
   const latestSnapshots = loadSnapshotsForRunIds(db, latestVisRunGroup.map((r) => r.id));
   const latestRunLocation = representativeLatestRun?.location ?? null;
   const competitorRows2 = db.select().from(competitors).where(eq33(competitors.projectId, project.id)).all();
@@ -31594,7 +31771,8 @@ function buildProjectReport(db, projectName, periodDays) {
     }));
   }
   Object.assign(mentionLandscape, mentionLandscape.nonBrand);
-  const aiSourceOrigin = buildAiSourceOrigin(latestSnapshots, projectDomains, competitorDomains);
+  const advancedSourceSnapshots = advancedVisibility && visibility.selection.run.id !== null ? db.select({ citedDomains: querySnapshots.citedDomains, provider: querySnapshots.provider, location: querySnapshots.location }).from(querySnapshots).where(eq33(querySnapshots.runId, visibility.selection.run.id)).all() : [];
+  const aiSourceOrigin = buildAiSourceOrigin(advancedVisibility ? advancedSourceSnapshots : latestSnapshots, projectDomains, competitorDomains);
   const trackedQueries = [...queryLookup.byId.values()];
   const gscSection = buildGscSection(
     db,
@@ -31629,7 +31807,7 @@ function buildProjectReport(db, projectName, periodDays) {
     insights: insightList,
     comparisonWindowDays
   });
-  const totalQueryCount = queryLookup.byId.size;
+  const totalQueryCount = new Set(latestSnapshots.map((snapshot) => snapshot.queryId)).size;
   const citedQueryIds = /* @__PURE__ */ new Set();
   const mentionedQueryIds = /* @__PURE__ */ new Set();
   for (const snap of latestSnapshots) {
@@ -31640,7 +31818,7 @@ function buildProjectReport(db, projectName, periodDays) {
   const citedQueryCount = citedQueryIds.size;
   const mentionedQueryCount = mentionedQueryIds.size;
   const citationRate = totalQueryCount > 0 ? Math.round(citedQueryCount / totalQueryCount * 100) : 0;
-  const mentionRate2 = totalQueryCount > 0 ? Math.round(mentionedQueryCount / totalQueryCount * 100) : 0;
+  const mentionRate3 = totalQueryCount > 0 ? Math.round(mentionedQueryCount / totalQueryCount * 100) : 0;
   const trendBaseline = isTrendBaseline(citationsTrend);
   const latestPoint = citationsTrend.at(-1);
   const previousPoint = citationsTrend.length >= 2 ? citationsTrend.at(-2) : null;
@@ -31665,21 +31843,22 @@ function buildProjectReport(db, projectName, periodDays) {
     insightList,
     competitorLandscape.competitors
   );
-  const periodStart = citationsTrend[0]?.date ?? null;
-  const periodEnd = citationsTrend.at(-1)?.date ?? null;
+  const visibilityDates = visibility.populations.flatMap((population) => population.trend.map((point) => point.createdAt)).sort();
+  const periodStart = advancedVisibility ? visibilityDates[0] ?? visibility.selection.measurement.completedAt : citationsTrend[0]?.date ?? null;
+  const periodEnd = advancedVisibility ? visibility.selection.measurement.completedAt : citationsTrend.at(-1)?.date ?? null;
   const configuredLocations = project.locations;
   const reportLocation = buildLocationMeta(representativeLatestRun?.location ?? null, configuredLocations);
-  const providerLocationHandling = reportLocation ? buildProviderLocationHandling(citationScorecard.providers) : [];
+  const providerLocationHandling = advancedVisibility ? buildProviderLocationHandling([...new Set(advancedSourceSnapshots.filter((snapshot) => snapshot.location !== null).map((snapshot) => snapshot.provider))]) : reportLocation ? buildProviderLocationHandling(citationScorecard.providers) : [];
   const executiveSummary = {
     citationRate,
     citedQueryCount,
     totalQueryCount,
-    mentionRate: mentionRate2,
+    mentionRate: mentionRate3,
     mentionedQueryCount,
     trend,
     queryCount: queryLookup.byId.size,
     competitorCount: competitorDomains.length,
-    providerCount: citationScorecard.providers.length,
+    providerCount: advancedVisibility ? new Set(advancedSourceSnapshots.map((snapshot) => snapshot.provider)).size : citationScorecard.providers.length,
     gsc: gscSection ? {
       clicks: gscSection.totalClicks,
       impressions: gscSection.totalImpressions,
@@ -31700,6 +31879,7 @@ function buildProjectReport(db, projectName, periodDays) {
     canonicalDomain: project.canonicalDomain,
     competitorDomains: actionPlanCompetitorDomains,
     citationScorecard,
+    hasVisibilityMeasurement: advancedVisibility ? visibility.selection.run.id !== null : void 0,
     aiSourceOrigin,
     gsc: gscSection,
     indexingHealth: indexingHealthSection,
@@ -31721,6 +31901,7 @@ function buildProjectReport(db, projectName, periodDays) {
     canonicalDomain: project.canonicalDomain,
     competitorDomains,
     citationScorecard,
+    hasVisibilityMeasurement: advancedVisibility ? visibility.selection.run.id !== null : void 0,
     aiSourceOrigin,
     gsc: gscSection,
     indexingHealth: indexingHealthSection,
@@ -31732,7 +31913,7 @@ function buildProjectReport(db, projectName, periodDays) {
   });
   return {
     meta: {
-      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      generatedAt,
       project: {
         id: project.id,
         name: project.name,
@@ -31747,7 +31928,18 @@ function buildProjectReport(db, projectName, periodDays) {
       periodEnd,
       periodDays
     },
-    executiveSummary,
+    ...canonicalVisibilitySupported ? { visibility } : {},
+    executiveSummary: advancedVisibility ? {
+      ...executiveSummary,
+      visibilityBasis: "frozen-populations",
+      citationRate: null,
+      citedQueryCount: null,
+      totalQueryCount: null,
+      mentionRate: null,
+      mentionedQueryCount: null,
+      trend: "unknown",
+      findings: []
+    } : { ...executiveSummary, visibilityBasis: "legacy-project-queries" },
     citationScorecard,
     competitorLandscape,
     mentionLandscape,
@@ -31758,12 +31950,28 @@ function buildProjectReport(db, projectName, periodDays) {
     aiReferrals: aiReferralsSection,
     serverActivity: serverActivitySection,
     indexingHealth: indexingHealthSection,
-    citationsTrend,
-    whatsChanged,
+    citationsTrend: advancedVisibility ? [] : citationsTrend,
+    whatsChanged: advancedVisibility ? {
+      ...whatsChanged,
+      enoughHistory: false,
+      headline: "See measurement history for each query type.",
+      citationRate: null,
+      mentionRate: null,
+      citedQueryCount: null,
+      mentionedQueryCount: null,
+      providerMovements: [],
+      wins: [],
+      regressions: []
+    } : whatsChanged,
     insights: insightList,
     recommendedNextSteps,
     actionPlan,
-    clientSummary,
+    clientSummary: advancedVisibility ? {
+      ...clientSummary,
+      headline: "AI visibility by query type",
+      overview: "Mention and citation coverage use the properties assigned to each measured query.",
+      confidenceNotes: []
+    } : clientSummary,
     agencyDiagnostics,
     contentOpportunities,
     contentGaps,
@@ -34078,7 +34286,7 @@ function summarizeFromSnapshots(snapshots) {
     if (wasMentioned) mentionedQueries += 1;
   }
   const notMentionedQueries = totalQueries - mentionedQueries;
-  const mentionRate2 = totalQueries === 0 ? 0 : Number((mentionedQueries / totalQueries).toFixed(4));
+  const mentionRate3 = totalQueries === 0 ? 0 : Number((mentionedQueries / totalQueries).toFixed(4));
   const providers = [...perProvider.entries()].map(([provider, { cited, total }]) => ({
     provider,
     cited,
@@ -34093,7 +34301,7 @@ function summarizeFromSnapshots(snapshots) {
       citedRate,
       mentionedQueries,
       notMentionedQueries,
-      mentionRate: mentionRate2
+      mentionRate: mentionRate3
     },
     providers
   };
@@ -34529,6 +34737,8 @@ var SCHEMA_TABLE = {
   DiscoveryPromoteResult: discoveryPromoteResultSchema,
   DiscoverySessionDetailDto: discoverySessionDetailDtoSchema,
   DiscoverySessionDto: discoverySessionDtoSchema,
+  ResearchBatchCreate: researchBatchCreateSchema,
+  ResearchBatchDto: researchBatchSchema,
   ResearchRunCreate: researchRunCreateSchema,
   ResearchRunDetailDto: researchRunDetailSchema,
   ResearchRunListDto: researchRunListSchema,
@@ -36230,6 +36440,16 @@ var routeCatalog = [
     requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ResearchRunCreate" } } } },
     responses: { 200: jsonResponse("Idempotent request returned its existing research run.", "ResearchRunDetailDto"), 202: jsonResponse("Research batch queued.", "ResearchRunDetailDto"), 400: errorResponse("Invalid provider, model, location, or request."), 403: errorResponse("Paid research was not granted to this principal."), 404: errorResponse("Project not found."), 409: errorResponse("Idempotency key was reused with a different payload."), 422: errorResponse("Research executor is unavailable on this deployment."), 429: errorResponse("The viewer reached the per-project UTC-day research limit.") }
   },
+  {
+    method: "post",
+    path: "/api/v1/projects/{name}/research/batches",
+    summary: "Start bounded explicit research destinations",
+    description: "Queues one to twenty saved research runs atomically, with no more than fifty exact editor questions in total. Every destination explicitly pins its configured API provider, model, and configured location (or null); a scoped destination also pins the published plan revision. The root idempotency key covers the complete ordered destination list: a retry returns the same saved runs even if plans, templates, or provider defaults later change. A changed, reordered, added, or removed destination conflicts. Research never creates tracked queries, shared runs, snapshots, insights, or notifications.",
+    tags: ["research"],
+    parameters: [nameParameter],
+    requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ResearchBatchCreate" } } } },
+    responses: { 200: jsonResponse("Idempotent request returned its existing saved runs.", "ResearchBatchDto"), 202: jsonResponse("All research destinations were queued.", "ResearchBatchDto"), 400: errorResponse("Each destination must explicitly supply a configured provider, model, location or null, and expected plan revision when scoped. The request permits at most 20 destinations and 50 total concrete queries."), 403: errorResponse("Paid research was not granted to this principal."), 404: errorResponse("Project not found."), 409: errorResponse("The root idempotency key was reused with different ordered destinations."), 422: errorResponse("Research execution is not available on this deployment."), 429: errorResponse("The viewer reached the per-project UTC-day research limit.") }
+  },
   {
     method: "get",
     path: "/api/v1/projects/{name}/query-tracking",
@@ -36273,7 +36493,7 @@ var routeCatalog = [
     path: "/api/v1/projects/{name}/research/runs",
     summary: "List saved research query batches",
     tags: ["research"],
-    parameters: [nameParameter, { name: "limit", in: "query", description: "Max runs, default 20 and maximum 100.", schema: integerSchema }],
+    parameters: [nameParameter, { name: "limit", in: "query", description: "Max runs, default 20 and maximum 100.", schema: integerSchema }, { name: "cursor", in: "query", description: "Opaque cursor from the previous page.", schema: stringSchema }],
     responses: { 200: jsonResponse("Research runs returned newest first.", "ResearchRunListDto"), 404: errorResponse("Project not found.") }
   },
   {
@@ -41978,7 +42198,7 @@ async function keysRoutes(app) {
     if (!row) {
       throw notFound("API key", id);
     }
-    return toApiKeyDto(row, projectNameById(app.db));
+    return toApiKeyDto({ ...row, scopes: request.apiKey?.scopes ?? row.scopes }, projectNameById(app.db));
   });
   app.post("/keys", async (request) => {
     requireAdminSession(request);
@@ -83168,22 +83388,33 @@ async function technicalAeoRoutes(app, opts) {
 
 // ../api-routes/src/research.ts
 import crypto49 from "crypto";
-import { and as and55, count as count3, desc as desc28, eq as eq65, gte as gte17, lt as lt11, sql as sql25 } from "drizzle-orm";
+import { z as z5 } from "zod";
+import { and as and55, count as count3, desc as desc28, eq as eq65, gte as gte17, lt as lt11, or as or14, sql as sql25 } from "drizzle-orm";
 var sameLocation = (a, b) => a.label === b.label && a.city === b.city && a.region === b.region && a.country === b.country && a.timezone === b.timezone;
+var BATCH_RECEIPT_PREFIX = "__canonry_research_batch__:";
 async function researchRoutes(app, opts) {
   const viewerDailyRunLimit = opts.viewerDailyRunLimit ?? DEFAULT_VIEWER_RESEARCH_DAILY_RUN_LIMIT;
   if (!Number.isInteger(viewerDailyRunLimit) || viewerDailyRunLimit <= 0) {
     throw new Error("viewerDailyRunLimit must be a positive integer");
   }
   app.post("/projects/:name/research/runs", {
-    config: { paidRead: true }
+    config: { paidRead: true, writeScope: RESEARCH_RUN_SCOPE }
   }, async (request, reply) => {
     requireResearchGrant(request, opts.allowViewers ?? false);
     const project = resolveProject(app.db, request.params.name);
-    if (!opts.onResearchRunRequested) throw missingDependency("Research execution is not available on this deployment.", { reason: "no-research-handler" });
     const parsed = researchRunCreateSchema.safeParse(request.body ?? {});
     if (!parsed.success) throw validationError("Invalid research run request", { issues: parsed.error.issues });
     const input = parsed.data;
+    if (input.idempotencyKey?.startsWith(BATCH_RECEIPT_PREFIX)) throw validationError("This idempotency key prefix is reserved for internal research batch receipts.");
+    const requestHash2 = directResearchRequestHash(input);
+    const existingReceipt = input.idempotencyKey ? app.db.select().from(researchRuns).where(and55(eq65(researchRuns.projectId, project.id), eq65(researchRuns.idempotencyKey, input.idempotencyKey))).get() : void 0;
+    if (existingReceipt) {
+      assertSameDirectResearchRequest(existingReceipt, input, requestHash2);
+      const result2 = getDetail(app, project.id, existingReceipt.id);
+      if (existingReceipt.status === ResearchRunStatuses.queued) opts.onResearchRunRequested?.(existingReceipt.id, project.id);
+      return reply.status(200).send(result2);
+    }
+    if (!opts.onResearchRunRequested) throw missingDependency("Research execution is not available on this deployment.", { reason: "no-research-handler" });
     const adapters = opts.providerAdapters ?? [];
     const configured = new Set(opts.configuredProviderNames ?? []);
     const providerName = input.provider ?? project.providers.find((name) => configured.has(name) && adapters.some((adapter2) => adapter2.name === name && adapter2.mode === "api")) ?? adapters.find((adapter2) => adapter2.mode === "api" && configured.has(adapter2.name))?.name;
@@ -83193,37 +83424,34 @@ async function researchRoutes(app, opts) {
       adapter.modelValidationPattern.lastIndex = 0;
       if (!adapter.modelConfigurable || !adapter.modelValidationPattern.test(input.model)) throw validationError(`Invalid model "${input.model}" for provider "${providerName}".`, { provider: providerName, model: input.model, hint: adapter.modelValidationHint });
     }
-    const existingReceipt = input.idempotencyKey ? app.db.select().from(researchRuns).where(and55(eq65(researchRuns.projectId, project.id), eq65(researchRuns.idempotencyKey, input.idempotencyKey))).get() : void 0;
     const active = activeMeasurementPlan(app.db, project.id);
-    const scope = input.scope ? existingReceipt ? resolveStoredResearchScope(existingReceipt.scope, input.scope, input.idempotencyKey) : resolveResearchScope(active, input.scope) : null;
-    const template = input.template ? existingReceipt ? resolveStoredResearchTemplate(existingReceipt.template, input.template, input.idempotencyKey) : resolveResearchTemplate(app, project.id, input.template, scope) : null;
+    const scope = input.scope ? resolveResearchScope(active, input.scope) : null;
     const location = input.location === void 0 ? scope ? null : project.defaultLocation ? project.locations.find((item2) => item2.label === project.defaultLocation) ?? null : null : input.location;
     if (location && !project.locations.some((item2) => sameLocation(item2, location))) throw validationError("Research location must exactly match a configured project location.", { location });
+    const template = input.template ? resolveResearchTemplate(app, project.id, input.template, scope, location) : null;
     const requestedModel2 = input.model ?? null;
     const resolvedModel = requestedModel2 ?? (project.providerModels[providerName] || opts.getEffectiveProviderModels?.()[providerName] || adapter.defaultModel);
     adapter.modelValidationPattern.lastIndex = 0;
     if (!adapter.modelValidationPattern.test(resolvedModel)) throw validationError('Invalid resolved model "' + resolvedModel + '" for provider "' + providerName + '".', { provider: providerName, model: resolvedModel, hint: adapter.modelValidationHint });
     if (deduplicateResearchQueries(input.queries).length !== input.queries.length) throw validationError("Research queries must be unique within a batch.");
     const queryClasses = classifyResearchQueries(project, active?.plan ?? null, input.queries);
-    const normalized = { queries: input.queries, provider: providerName, model: requestedModel2, location: location ?? null, ...scope ? { scope } : {}, ...template ? { template } : {} };
-    const requestHash2 = crypto49.createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const initiatedBy = researchPrincipal(request);
     const decision = app.db.transaction((tx) => {
       if (input.idempotencyKey) {
         const existing = tx.select().from(researchRuns).where(and55(eq65(researchRuns.projectId, project.id), eq65(researchRuns.idempotencyKey, input.idempotencyKey))).get();
         if (existing) {
-          if (existing.requestHash !== requestHash2) throw alreadyExists("Research idempotency key", input.idempotencyKey);
+          assertSameDirectResearchRequest(existing, input, requestHash2);
           return { reused: true, id: existing.id, shouldDispatch: existing.status === ResearchRunStatuses.queued };
         }
       }
-      if (initiatedBy?.kind === "user" && initiatedBy.role === UserRoles.viewer) {
+      if (initiatedBy?.limited) {
         const { start, end, date } = utcDayBounds(now);
         const used = tx.select({ value: count3() }).from(researchRuns).where(and55(
           eq65(researchRuns.projectId, project.id),
           gte17(researchRuns.createdAt, start),
           lt11(researchRuns.createdAt, end),
-          sql25`json_extract(${researchRuns.initiatedBy}, '$.role') = ${UserRoles.viewer}`
+          sql25`(json_extract(${researchRuns.initiatedBy}, '$.role') = ${UserRoles.viewer} OR json_extract(${researchRuns.initiatedBy}, '$.limited') = 1)`
         )).get()?.value ?? 0;
         if (used >= viewerDailyRunLimit) {
           throw researchDailyLimitExceeded(project.name, viewerDailyRunLimit, date);
@@ -83240,17 +83468,108 @@ async function researchRoutes(app, opts) {
     if (decision.reused) return reply.status(200).send(result);
     return reply.status(202).send(result);
   });
+  app.post("/projects/:name/research/batches", {
+    config: { paidRead: true, writeScope: RESEARCH_RUN_SCOPE }
+  }, async (request, reply) => {
+    requireResearchGrant(request, opts.allowViewers ?? false);
+    const project = resolveProject(app.db, request.params.name);
+    const parsed = researchBatchCreateSchema.safeParse(request.body ?? {});
+    if (!parsed.success) throw validationError("Invalid research batch request", { issues: parsed.error.issues });
+    const input = parsed.data;
+    if (input.idempotencyKey.startsWith(BATCH_RECEIPT_PREFIX)) throw validationError("This idempotency key prefix is reserved for internal research batch receipts.");
+    const requestHash2 = researchBatchRequestHash(input);
+    const receiptKeys = input.runs.map((_run, index2) => batchChildReceiptKey(input.idempotencyKey, index2));
+    const firstReceipt = app.db.select().from(researchRuns).where(and55(
+      eq65(researchRuns.projectId, project.id),
+      eq65(researchRuns.idempotencyKey, receiptKeys[0])
+    )).get();
+    if (firstReceipt) {
+      if (firstReceipt.requestHash !== requestHash2) throw alreadyExists("Research batch idempotency key", input.idempotencyKey);
+      const saved = receiptKeys.map((key) => app.db.select().from(researchRuns).where(and55(
+        eq65(researchRuns.projectId, project.id),
+        eq65(researchRuns.idempotencyKey, key)
+      )).get());
+      if (saved.some((row) => !row || row.requestHash !== requestHash2)) throw alreadyExists("Research batch idempotency key", input.idempotencyKey);
+      const runs3 = saved.map((row) => getDetail(app, project.id, row.id));
+      for (const run of runs3) if (run.status === ResearchRunStatuses.queued) opts.onResearchRunRequested?.(run.id, project.id);
+      return reply.status(200).send({ runs: runs3 });
+    }
+    if (!opts.onResearchRunRequested) throw missingDependency("Research execution is not available on this deployment.", { reason: "no-research-handler" });
+    const active = activeMeasurementPlan(app.db, project.id);
+    const prepared = input.runs.map((run) => prepareBatchRun(app, opts, project, active, run));
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const initiatedBy = researchPrincipal(request);
+    const decision = app.db.transaction((tx) => {
+      if (initiatedBy?.limited) {
+        const { start, end, date } = utcDayBounds(now);
+        const used = tx.select({ value: count3() }).from(researchRuns).where(and55(
+          eq65(researchRuns.projectId, project.id),
+          gte17(researchRuns.createdAt, start),
+          lt11(researchRuns.createdAt, end),
+          sql25`(json_extract(${researchRuns.initiatedBy}, '$.role') = ${UserRoles.viewer} OR json_extract(${researchRuns.initiatedBy}, '$.limited') = 1)`
+        )).get()?.value ?? 0;
+        if (used + prepared.length > viewerDailyRunLimit) throw researchDailyLimitExceeded(project.name, viewerDailyRunLimit, date);
+      }
+      const ids = [];
+      for (const [index2, run] of prepared.entries()) {
+        const id = crypto49.randomUUID();
+        ids.push(id);
+        tx.insert(researchRuns).values({
+          id,
+          projectId: project.id,
+          status: ResearchRunStatuses.queued,
+          provider: run.providerName,
+          requestedModel: run.requestedModel,
+          resolvedModel: run.resolvedModel,
+          location: run.location,
+          totalQueries: run.input.queries.length,
+          scope: run.scope,
+          template: run.template,
+          idempotencyKey: receiptKeys[index2],
+          requestHash: requestHash2,
+          initiatedBy,
+          createdAt: now
+        }).run();
+        for (const [position, query] of run.input.queries.entries()) tx.insert(researchRunQueries).values({
+          id: crypto49.randomUUID(),
+          researchRunId: id,
+          position,
+          queryText: query,
+          queryClass: run.queryClasses[position] ?? null,
+          status: ResearchQueryStatuses.queued,
+          requestedModel: run.requestedModel,
+          resolvedModel: run.resolvedModel,
+          groundingSources: [],
+          citedDomains: [],
+          searchQueries: [],
+          createdAt: now
+        }).run();
+        writeAuditLog(tx, { projectId: project.id, actor: initiatedBy ? `${initiatedBy.kind}:${initiatedBy.id}` : "api", action: "research.created", entityType: "research_run", entityId: id });
+      }
+      return { ids };
+    });
+    const runs2 = decision.ids.map((id) => getDetail(app, project.id, id));
+    for (const id of decision.ids) opts.onResearchRunRequested(id, project.id);
+    return reply.status(202).send({ runs: runs2 });
+  });
   app.get("/projects/:name/research/runs", async (request) => {
     const project = resolveProject(app.db, request.params.name);
     const requested = Number.parseInt(request.query.limit ?? "", 10);
     const limit = Number.isInteger(requested) && requested > 0 ? Math.min(requested, 100) : 20;
-    const runs2 = app.db.select().from(researchRuns).where(eq65(researchRuns.projectId, project.id)).orderBy(desc28(researchRuns.createdAt)).limit(limit).all().map(serializeRun);
+    const cursor = request.query.cursor ? parseResearchCursor(request.query.cursor, project.id) : null;
+    const rows = app.db.select().from(researchRuns).where(and55(
+      eq65(researchRuns.projectId, project.id),
+      cursor ? or14(lt11(researchRuns.createdAt, cursor.createdAt), and55(eq65(researchRuns.createdAt, cursor.createdAt), lt11(researchRuns.id, cursor.id))) : void 0
+    )).orderBy(desc28(researchRuns.createdAt), desc28(researchRuns.id)).limit(limit + 1).all();
+    const runs2 = rows.slice(0, limit).map(serializeRun);
+    const last = runs2.at(-1);
+    const nextCursor = rows.length > limit && last ? Buffer.from(JSON.stringify({ projectId: project.id, createdAt: last.createdAt, id: last.id })).toString("base64url") : null;
     const configured = new Set(opts.configuredProviderNames ?? []);
     const effectiveModels2 = opts.getEffectiveProviderModels?.() ?? {};
-    const providers = await Promise.all((opts.providerAdapters ?? []).filter((adapter) => adapter.mode === "api" && !isBrowserProvider(adapter.name) && configured.has(adapter.name)).map(async (adapter) => {
+    const providers = (opts.providerAdapters ?? []).filter((adapter) => adapter.mode === "api" && !isBrowserProvider(adapter.name) && configured.has(adapter.name)).map((adapter) => {
       const defaultModel = project.providerModels[adapter.name] || effectiveModels2[adapter.name] || adapter.defaultModel;
-      const discovered = opts.getProviderModels ? await opts.getProviderModels(adapter.name) : [];
-      const models = discovered.length ? discovered : adapter.knownModels;
+      const cached = opts.getCachedProviderModels?.(adapter.name) ?? [];
+      const models = cached.length ? cached : adapter.knownModels;
       return {
         name: adapter.name,
         displayName: adapter.displayName,
@@ -83258,20 +83577,94 @@ async function researchRoutes(app, opts) {
         defaultModel,
         knownModels: [...new Map([{ id: defaultModel, displayName: defaultModel }, ...models].map((model) => [model.id, { id: model.id, displayName: model.displayName }])).values()]
       };
-    }));
-    return { runs: runs2, providers };
+    });
+    const canRun = canRunResearch(request, opts.allowViewers ?? false);
+    const limited = request.principal !== void 0 && !request.principal.scopes.includes(WILDCARD_SCOPE);
+    return { runs: runs2, nextCursor, providers, access: { canRun, dailyRunLimit: canRun && limited ? viewerDailyRunLimit : null } };
   });
   app.get("/projects/:name/research/runs/:runId", async (request) => {
     const project = resolveProject(app.db, request.params.name);
     return getDetail(app, project.id, request.params.runId);
   });
 }
+var DIRECT_REQUEST_HASH_VERSION = "direct-v2:";
+function directResearchRequestHash(input) {
+  const { idempotencyKey: _key, ...request } = input;
+  return DIRECT_REQUEST_HASH_VERSION + crypto49.createHash("sha256").update(JSON.stringify(request)).digest("hex");
+}
+function assertSameDirectResearchRequest(existing, input, hash) {
+  if (existing.requestHash?.startsWith(DIRECT_REQUEST_HASH_VERSION)) {
+    if (existing.requestHash !== hash) throw alreadyExists("Research idempotency key", input.idempotencyKey);
+    return;
+  }
+  const scope = input.scope ? resolveStoredResearchScope(existing.scope, input.scope, input.idempotencyKey) : null;
+  const template = input.template ? resolveStoredResearchTemplate(existing.template, input.template, input.idempotencyKey) : null;
+  if (input.template?.bindingLocation !== void 0) throw alreadyExists("Research idempotency key", input.idempotencyKey);
+  const normalized = {
+    queries: input.queries,
+    provider: input.provider ?? existing.provider,
+    model: input.model ?? null,
+    location: input.location === void 0 ? existing.location ?? null : input.location,
+    ...scope ? { scope } : {},
+    ...template ? { template } : {}
+  };
+  if (crypto49.createHash("sha256").update(JSON.stringify(normalized)).digest("hex") !== existing.requestHash) throw alreadyExists("Research idempotency key", input.idempotencyKey);
+}
+var researchCursorSchema = z5.object({ projectId: z5.string().min(1), createdAt: z5.string().datetime({ offset: true }), id: z5.string().min(1).max(256) }).strict();
+function parseResearchCursor(value, projectId) {
+  try {
+    if (value.length > 2048 || !/^[\w-]+$/.test(value)) throw new Error("Invalid encoding");
+    const cursor = researchCursorSchema.parse(JSON.parse(Buffer.from(value, "base64url").toString("utf8")));
+    if (cursor.projectId !== projectId) throw new Error("Different project");
+    return cursor;
+  } catch {
+    throw validationError("Invalid research history cursor. Reload the first page and try again.");
+  }
+}
 function resolveStoredResearchScope(stored, selection, idempotencyKey) {
   if (!stored || stored.kind !== selection.kind || stored.key !== selection.key || selection.expectedPlanRevision !== void 0 && selection.expectedPlanRevision !== stored.planRevision) {
     throw alreadyExists("Research idempotency key", idempotencyKey);
   }
   return stored;
 }
+function batchChildReceiptKey(rootKey, index2) {
+  const derived = crypto49.createHash("sha256").update(`${rootKey}\0${index2}`).digest("hex");
+  return `${BATCH_RECEIPT_PREFIX}${derived}:${index2}`;
+}
+function researchBatchRequestHash(input) {
+  return crypto49.createHash("sha256").update(JSON.stringify({ runs: input.runs })).digest("hex");
+}
+function prepareBatchRun(app, opts, project, active, input) {
+  const adapters = opts.providerAdapters ?? [];
+  const configured = new Set(opts.configuredProviderNames ?? []);
+  const providerName = input.provider;
+  const adapter = adapters.find((candidate) => candidate.name === providerName);
+  if (!adapter || adapter.mode !== "api" || isBrowserProvider(providerName) || !configured.has(providerName)) {
+    throw validationError("Research requires a configured API provider.", { provider: providerName, validProviders: adapters.filter((a) => a.mode === "api" && configured.has(a.name)).map((a) => a.name) });
+  }
+  adapter.modelValidationPattern.lastIndex = 0;
+  if (!adapter.modelValidationPattern.test(input.model) || !adapter.modelConfigurable && input.model !== adapter.defaultModel) {
+    throw validationError(`Invalid model "${input.model}" for provider "${providerName}".`, { provider: providerName, model: input.model, hint: adapter.modelValidationHint });
+  }
+  const location = input.location;
+  if (location && !project.locations.some((item2) => sameLocation(item2, location))) {
+    throw validationError("Research location must exactly match a configured project location.", { location });
+  }
+  if (deduplicateResearchQueries(input.queries).length !== input.queries.length) throw validationError("Research queries must be unique within each batch destination.");
+  const scope = input.scope ? resolveResearchScope(active, input.scope) : null;
+  const template = input.template ? resolveResearchTemplate(app, project.id, input.template, scope, location) : null;
+  return {
+    input,
+    providerName,
+    requestedModel: input.model,
+    // The batch contract requires the model so retries never consult a project or instance default.
+    resolvedModel: input.model,
+    location,
+    scope,
+    template,
+    queryClasses: classifyResearchQueries(project, active?.plan ?? null, input.queries)
+  };
+}
 function resolveResearchScope(active, selection) {
   if (!active || active.plan.schemaVersion !== 2) {
     throw validationError("Research scope requires an active Advanced Measurement plan.");
@@ -83292,8 +83685,7 @@ function resolveStoredResearchTemplate(stored, selection, idempotencyKey) {
   }
   return stored;
 }
-function resolveResearchTemplate(app, projectId, selection, scope) {
-  if (!scope) throw validationError("Research templates require a selected market or property scope.");
+function resolveResearchTemplate(app, projectId, selection, scope, location) {
   const savedTemplate = app.db.select().from(measurementQueryTemplates).where(and55(
     eq65(measurementQueryTemplates.projectId, projectId),
     eq65(measurementQueryTemplates.id, selection.templateId)
@@ -83303,7 +83695,12 @@ function resolveResearchTemplate(app, projectId, selection, scope) {
   if (templateVersion !== selection.templateVersion) {
     throw validationError("The selected research template is stale. Reload it and try again.");
   }
-  const { bindings, output } = expandResearchTemplate(savedTemplate, scope);
+  const bindingLocation = selection.bindingLocation === void 0 ? location : selection.bindingLocation;
+  if (bindingLocation) {
+    const project = app.db.select({ locations: projects.locations }).from(projects).where(eq65(projects.id, projectId)).get();
+    if (!project.locations.some((item2) => sameLocation(item2, bindingLocation))) throw validationError("Research template binding location must match a configured project location.");
+  }
+  const { bindings, output } = expandResearchTemplate(savedTemplate, scope, bindingLocation);
   if (!output || output.length > 4e3) throw validationError("Research template output must be between 1 and 4000 characters.");
   return { templateId: selection.templateId, templateVersion, template: savedTemplate.pattern, bindings, output };
 }
@@ -83327,11 +83724,13 @@ function serializeQuery(row) {
 function researchPrincipal(request) {
   const principal = request.principal;
   if (!principal) return null;
+  const actor = principal.delegatedUser ? { ...principal.delegatedUser, kind: "user" } : principal;
   return {
-    kind: principal.kind,
-    id: principal.id,
-    name: principal.name,
-    role: principal.kind === "user" ? principal.role ?? null : null
+    kind: actor.kind,
+    id: actor.id,
+    name: actor.name,
+    role: actor.kind === "user" ? actor.role ?? null : null,
+    ...!principal.scopes.includes(WILDCARD_SCOPE) ? { limited: true } : {}
   };
 }
 function utcDayBounds(now) {
@@ -83455,6 +83854,7 @@ async function apiRoutes(app, opts) {
     });
     if (!opts.skipAuth) {
       await authPlugin(api, {
+        researchAllowViewers: opts.researchAllowViewers,
         // A bearer that is not an api key is tried as an OAuth access token.
         // Wired unconditionally: the table is empty until an operator registers
         // a client, so an install with no OAuth in use pays one indexed miss.
@@ -83671,7 +84071,7 @@ async function apiRoutes(app, opts) {
       embedQueries: opts.embedQueries
     });
     await api.register(researchRoutes, {
-      getProviderModels: opts.getProviderModels,
+      getCachedProviderModels: opts.getCachedProviderModels,
       getEffectiveProviderModels: opts.getEffectiveProviderModels,
       providerAdapters: opts.providerAdapters,
       configuredProviderNames: opts.providerSummary?.filter((provider) => provider.configured).map((provider) => provider.name),
@@ -84114,7 +84514,7 @@ function analyzableRunPredicates(projectId) {
     eq67(runs.projectId, projectId),
     // Only this kind writes query_snapshots.
     eq67(runs.kind, RunKinds["answer-visibility"]),
-    or14(eq67(runs.status, RunStatuses.completed), eq67(runs.status, RunStatuses.partial)),
+    or15(eq67(runs.status, RunStatuses.completed), eq67(runs.status, RunStatuses.partial)),
     // Defensive: RunCoordinator already skips probes before analyzeAndPersist
     // is called, but a future call site invoking it directly for a probe must
     // still not pollute the intelligence window.
@@ -84704,7 +85104,7 @@ var IntelligenceService = class {
       and57(
         eq67(runs.projectId, projectId),
         eq67(runs.kind, RunKinds["answer-visibility"]),
-        or14(eq67(runs.status, "completed"), eq67(runs.status, "partial")),
+        or15(eq67(runs.status, "completed"), eq67(runs.status, "partial")),
         // Defensive — see top of file.
         ne10(runs.trigger, RunTriggers.probe)
       )