@ainyc/canonry 4.190.0 → 4.191.0

package/dist/{chunk-6POEZ7GT.js → chunk-ZK4FJDCH.js}

@@ -88,6 +88,7 @@ import {
   MeasurementRunScopeError,
   PROJECTS_WRITE_SCOPE,
   READ_ONLY_SCOPE,
+  RESEARCH_RUN_SCOPE,
   ResearchQueryStatuses,
   ResearchRunStatuses,
   RunKinds,
@@ -381,6 +382,7 @@ import {
   inclusiveDayCount,
   indexingRequestResponseDtoSchema,
   internalError,
+  intersectScopes,
   isBrowserProvider,
   isLocationRedirectStatus,
   isReadOnlyKey,
@@ -560,6 +562,8 @@ import {
   reportConfidenceLabel,
   reportHorizonLabel,
   reportSeverityLabel,
+  researchBatchCreateSchema,
+  researchBatchSchema,
   researchDailyLimitExceeded,
   researchRunCreateSchema,
   researchRunDetailSchema,
@@ -570,6 +574,7 @@ import {
   resolveMeasurementRunQueryScope,
   resolveMeasurementRunScope,
   resolveSnapshotRequestQueries,
+  restrictedWriteScopes,
   resultsClearRequestSchema,
   resultsClearResponseSchema,
   resultsExportDtoSchema,
@@ -676,7 +681,7 @@ import {
   wordpressSchemaDeployResultDtoSchema,
   wordpressSchemaStatusResultDtoSchema,
   wordpressStatusDtoSchema
-} from "./chunk-ROPJUNQN.js";
+} from "./chunk-KBUV3HGS.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";
@@ -1181,6 +1186,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 +7184,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) {
@@ -10795,10 +10809,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 +10839,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 +10851,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 +10907,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 +10998,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 +11007,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 +11023,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 +11061,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 +11080,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 +11103,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 +11114,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 +11177,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 +11211,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>
@@ -13805,54 +13834,61 @@ function scopeNamedShareOfVoice(identities, answered2, prepared) {
     entries: credited.map((row) => ({ ...row, share: row.credits / denominator }))
   };
 }
-function buildMeasurementOverview(input, options = {}) {
+function createMeasurementOverviewEvaluator(input, options = {}) {
   const prepared = prepareReport(input, options);
   const indexes = buildMeasurementOverviewIndexes(input, prepared, options.onEvidenceIndexed);
-  const targetIds = new Set(input.scopeTargetIds);
-  const edges = indexedScopeEdges(indexes, targetIds);
-  const slots = indexedSlotsForEdges(edges, indexes);
-  const answered2 = indexedAnsweredSlots(slots, indexes);
-  const properties = sortedUnique([...targetIds]).map((targetId) => {
-    const ownEdges = indexes.targetEdgesByTargetId.get(targetId) ?? [];
-    const ownSlots = indexedSlotsForEdges(ownEdges, indexes);
-    const ownAnswered = indexedAnsweredSlots(ownSlots, indexes);
-    const ownTargets = indexes.targetsById.get(targetId);
-    return {
-      targetId,
-      mentionCoverage: targetMentionRate(ownTargets, ownSlots, ownAnswered, indexes),
-      citationCoverage: indexedScopeCitationRate(ownSlots, ownEdges, indexes),
-      // Each engine is measured over the slots it owns, using exactly the
-      // functions the Property total uses. A per-engine reading is therefore
-      // withheld for the same reasons the total is, never rounded down to zero.
-      providers: providersFor(ownSlots).map((provider) => {
-        const providerSlots = ownSlots.filter((slot) => slot.provider === provider);
+  return {
+    evaluate(scopeTargetIds, namedIdentities = input.namedIdentities) {
+      const targetIds = new Set(scopeTargetIds);
+      const edges = indexedScopeEdges(indexes, targetIds);
+      const slots = indexedSlotsForEdges(edges, indexes);
+      const answered2 = indexedAnsweredSlots(slots, indexes);
+      const properties = sortedUnique([...targetIds]).map((targetId) => {
+        const ownEdges = indexes.targetEdgesByTargetId.get(targetId) ?? [];
+        const ownSlots = indexedSlotsForEdges(ownEdges, indexes);
+        const ownAnswered = indexedAnsweredSlots(ownSlots, indexes);
+        const ownTargets = indexes.targetsById.get(targetId);
         return {
-          provider,
-          mentionCoverage: targetMentionRate(
-            ownTargets,
-            providerSlots,
-            indexedAnsweredSlots(providerSlots, indexes),
-            indexes
-          ),
-          citationCoverage: indexedScopeCitationRate(providerSlots, ownEdges, indexes)
+          targetId,
+          mentionCoverage: targetMentionRate(ownTargets, ownSlots, ownAnswered, indexes),
+          citationCoverage: indexedScopeCitationRate(ownSlots, ownEdges, indexes),
+          // Each engine is measured over the slots it owns, using exactly the
+          // functions the Property total uses. A per-engine reading is therefore
+          // withheld for the same reasons the total is, never rounded down to zero.
+          providers: providersFor(ownSlots).map((provider) => {
+            const providerSlots = ownSlots.filter((slot) => slot.provider === provider);
+            return {
+              provider,
+              mentionCoverage: targetMentionRate(
+                ownTargets,
+                providerSlots,
+                indexedAnsweredSlots(providerSlots, indexes),
+                indexes
+              ),
+              citationCoverage: indexedScopeCitationRate(providerSlots, ownEdges, indexes)
+            };
+          }),
+          flags: indexes.ambiguousEvidenceKeysByTargetId.get(targetId)?.size ?? 0
         };
-      }),
-      flags: indexes.ambiguousEvidenceKeysByTargetId.get(targetId)?.size ?? 0
-    };
-  });
-  return {
-    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),
-    citationCoverage: indexedScopeCitationRate(slots, edges, indexes),
-    brandPresence: scopeBrandPresence(input, slots, answered2, prepared),
-    namedShareOfVoice: scopeNamedShareOfVoice(input.namedIdentities ?? [], answered2, prepared),
-    properties,
-    flags: properties.reduce((total, row) => total + row.flags, 0)
+      });
+      return {
+        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),
+        citationCoverage: indexedScopeCitationRate(slots, edges, indexes),
+        brandPresence: scopeBrandPresence(input, slots, answered2, prepared),
+        namedShareOfVoice: scopeNamedShareOfVoice(namedIdentities ?? [], answered2, prepared),
+        properties,
+        flags: properties.reduce((total, row) => total + row.flags, 0)
+      };
+    }
   };
 }
+function buildMeasurementOverview(input, options = {}) {
+  return createMeasurementOverviewEvaluator(input, options).evaluate(input.scopeTargetIds, input.namedIdentities);
+}
 function buildMeasurementEvidence(input, options = {}) {
   const prepared = prepareReport(input, options);
   return { answers: prepared.answers, evidence: prepared.evidence, diagnostics: prepared.diagnostics };
@@ -21408,16 +21444,16 @@ function filteredOverviewWithDb(db, active, plan, run, filters, targetKeys) {
   const location = filters.location === void 0 ? void 0 : normalizeMeasurementLocation(filters.location);
   const expectedSlots = materialized.input.expectedSlots.filter((slot) => (provider === void 0 || normalizeText2(slot.provider) === provider) && (location === void 0 || normalizeMeasurementLocation(slot.location) === location));
   const usageEdges = materialized.input.usageEdges.filter((edge) => filters.queryClass === "all" || materialized.edgeQueryClass.get(edge.id) === filters.queryClass);
-  return {
-    materialized,
+  const evaluator = createMeasurementOverviewEvaluator({
+    ...materialized.input,
     expectedSlots,
     usageEdges,
-    overview: buildMeasurementOverview({
-      ...materialized.input,
-      expectedSlots,
-      usageEdges,
-      scopeTargetIds: [...targetKeys]
-    })
+    scopeTargetIds: [...targetKeys]
+  });
+  return {
+    materialized,
+    evaluator,
+    overview: evaluator.evaluate(targetKeys)
   };
 }
 function targetAnswers(plan, target, materialized, filters) {
@@ -21537,16 +21573,11 @@ function targetKeysForRun(plan, run, requested, requireEntireScope) {
   }
   return selected;
 }
-function marketRollup(plan, run, materialized, expectedSlots, usageEdges, scopedToOneGroup) {
+function marketRollup(plan, run, evaluator, scopedToOneGroup) {
   if (scopedToOneGroup) return [];
   return plan.groups.map((group) => {
     const targetKeys = targetKeysForRun(plan, run, group.targetKeys, false);
-    const overview = buildMeasurementOverview({
-      ...materialized.input,
-      expectedSlots,
-      usageEdges,
-      scopeTargetIds: targetKeys
-    });
+    const overview = evaluator.evaluate(targetKeys);
     return {
       groupKey: group.stableKey,
       label: group.label,
@@ -21618,22 +21649,28 @@ function portfolioResponse(db, active, plan, query) {
       truncated: rows2.length > limit2
     });
   }
-  const { materialized, overview, expectedSlots: filteredSlots, usageEdges: filteredEdges } = filteredOverviewWithDb(db, active, plan, run, filters, targetKeys);
+  const { materialized, overview, evaluator } = filteredOverviewWithDb(db, active, plan, run, filters, targetKeys);
   const measured = new Map(overview.properties.map((row) => [row.targetId, row]));
-  const rows = targets.map((target) => {
+  const ranked = targets.map((target) => {
     const row = measured.get(target.stableKey);
-    const recommendations = recommendationRows(target, targetAnswers(plan, target, materialized, filters));
     return {
+      target,
       ...propertyDto2(target),
       mentionCoverage: row ? coverageMetric2(row.mentionCoverage) : unavailable3("no_population"),
       citationCoverage: row ? coverageMetric2(row.citationCoverage) : unavailable3("no_population"),
-      flags: row?.flags ?? 0,
+      flags: row?.flags ?? 0
+    };
+  }).sort(compareWeakest);
+  const limit = query.limit ?? DEFAULT_LIMIT3;
+  const rows = ranked.slice(0, limit).map(({ target, ...row }) => {
+    const recommendations = recommendationRows(target, targetAnswers(plan, target, materialized, filters));
+    return {
+      ...row,
       recommendedInstead: recommendations.slice(0, 5).map(({ name, occurrences }) => ({ name, occurrences })),
       recommendedInsteadTotal: recommendations.length,
       recommendedInsteadTruncated: recommendations.length > 5
     };
-  }).sort(compareWeakest);
-  const limit = query.limit ?? DEFAULT_LIMIT3;
+  });
   return measurementPortfolioSummaryResponseSchema.parse({
     portfolio: {
       groupKey: group?.stableKey ?? null,
@@ -21648,9 +21685,9 @@ function portfolioResponse(db, active, plan, query) {
       citationCoverage: coverageMetric2(overview.citationCoverage)
     },
     weakestProperties: rows.slice(0, limit),
-    markets: marketRollup(plan, run, materialized, filteredSlots, filteredEdges, group !== void 0),
-    totalProperties: rows.length,
-    truncated: rows.length > limit
+    markets: marketRollup(plan, run, evaluator, group !== void 0),
+    totalProperties: ranked.length,
+    truncated: ranked.length > limit
   });
 }
 function propertyCompetitorsResponse(db, active, plan, query) {
@@ -34521,6 +34558,8 @@ var SCHEMA_TABLE = {
   DiscoveryPromoteResult: discoveryPromoteResultSchema,
   DiscoverySessionDetailDto: discoverySessionDetailDtoSchema,
   DiscoverySessionDto: discoverySessionDtoSchema,
+  ResearchBatchCreate: researchBatchCreateSchema,
+  ResearchBatchDto: researchBatchSchema,
   ResearchRunCreate: researchRunCreateSchema,
   ResearchRunDetailDto: researchRunDetailSchema,
   ResearchRunListDto: researchRunListSchema,
@@ -36222,6 +36261,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",
@@ -41970,7 +42019,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);
@@ -83162,13 +83211,14 @@ async function technicalAeoRoutes(app, opts) {
 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";
 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);
@@ -83176,6 +83226,7 @@ async function researchRoutes(app, opts) {
     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 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;
@@ -83188,9 +83239,9 @@ async function researchRoutes(app, opts) {
     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 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 ? existingReceipt ? resolveStoredResearchTemplate(existingReceipt.template, input.template, input.idempotencyKey) : 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;
@@ -83209,13 +83260,13 @@ async function researchRoutes(app, opts) {
           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);
@@ -83232,6 +83283,90 @@ 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);
@@ -83239,10 +83374,10 @@ async function researchRoutes(app, opts) {
     const runs2 = app.db.select().from(researchRuns).where(eq65(researchRuns.projectId, project.id)).orderBy(desc28(researchRuns.createdAt)).limit(limit).all().map(serializeRun);
     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,
@@ -83250,8 +83385,10 @@ 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, 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);
@@ -83264,6 +83401,44 @@ function resolveStoredResearchScope(stored, selection, 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.");
@@ -83284,8 +83459,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)
@@ -83295,7 +83469,7 @@ 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 { bindings, output } = expandResearchTemplate(savedTemplate, scope, location);
   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 };
 }
@@ -83319,11 +83493,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) {
@@ -83447,6 +83623,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.
@@ -83663,7 +83840,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),