@ainyc/canonry 4.189.1 → 4.190.1

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

@@ -267,6 +267,7 @@ import {
   createdApiKeyDtoSchema,
   dedupeReportActions,
   dedupeReportOpportunities,
+  deduplicateResearchQueries,
   deliveryFailed,
   deltaPercent,
   deltaTone,
@@ -293,6 +294,8 @@ import {
   emptyCitationVisibility,
   escapeLikePattern,
   evaluateModelPointerExposure,
+  expandQueryTemplate,
+  expandResearchTemplate,
   extractAnswerMentions,
   extractDomainsFromText,
   factorStatusFromScore,
@@ -441,6 +444,7 @@ import {
   measurementDraftTargetPageSchema,
   measurementDraftUpsertCompetitorRequestSchema,
   measurementDraftUpsertGroupRequestSchema,
+  measurementDraftUpsertMarketRequestSchema,
   measurementDraftUpsertTargetRequestSchema,
   measurementIdempotencyKeyConflict,
   measurementIdempotencyKeyRequired,
@@ -672,7 +676,7 @@ import {
   wordpressSchemaDeployResultDtoSchema,
   wordpressSchemaStatusResultDtoSchema,
   wordpressStatusDtoSchema
-} from "./chunk-CDI3YR57.js";
+} from "./chunk-ROPJUNQN.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";
@@ -2723,6 +2727,8 @@ var researchRuns = sqliteTable("research_runs", {
   requestedModel: text("requested_model"),
   resolvedModel: text("resolved_model").notNull(),
   location: text("location", { mode: "json" }).$type(),
+  scope: text("scope", { mode: "json" }).$type(),
+  template: text("template", { mode: "json" }).$type(),
   totalQueries: integer("total_queries").notNull(),
   completedQueries: integer("completed_queries").notNull().default(0),
   failedQueries: integer("failed_queries").notNull().default(0),
@@ -2739,6 +2745,7 @@ var researchRunQueries = sqliteTable("research_run_queries", {
   researchRunId: text("research_run_id").notNull().references(() => researchRuns.id, { onDelete: "cascade" }),
   position: integer("position").notNull(),
   queryText: text("query_text").notNull(),
+  queryClass: text("query_class").$type(),
   status: text("status").notNull().default("queued"),
   requestedModel: text("requested_model"),
   resolvedModel: text("resolved_model").notNull(),
@@ -7161,6 +7168,15 @@ var MIGRATION_VERSIONS = [
     statements: [
       `ALTER TABLE schedules ADD COLUMN recurrence TEXT`
     ]
+  },
+  {
+    version: 153,
+    name: "research-run-scope",
+    statements: [
+      `ALTER TABLE research_runs ADD COLUMN scope TEXT`,
+      `ALTER TABLE research_runs ADD COLUMN template TEXT`,
+      `ALTER TABLE research_run_queries ADD COLUMN query_class TEXT`
+    ]
   }
 ];
 function addRunsMeasurementPlanVersionForeignKey(tx) {
@@ -13789,54 +13805,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 };
@@ -17891,6 +17914,7 @@ var MEASUREMENT_DRAFT_ACTIONS = [
   "clear-assignments",
   "classify-assignments",
   "upsert-group",
+  "upsert-market",
   "remove-group",
   "upsert-competitor",
   "remove-competitor"
@@ -18288,6 +18312,23 @@ function upsertGroup(authoring, body) {
     warnings: unknown.length ? [warn("group-unknown-target", `Group "${group.stableKey}" names ${unknown.length} Target(s) the draft does not hold yet.`, ["groups", groupIndex, "targetKeys"])] : []
   };
 }
+function upsertMarket(authoring, body) {
+  const { market } = parseBody(measurementDraftUpsertMarketRequestSchema, body, "upsert-market");
+  const included = new Set(authoring.targets.filter((target) => target.status === "included").map((target) => target.stableKey));
+  const frozen = new Set(authoring.assignments.flatMap((assignment) => (assignment.executionContexts ?? []).filter((context) => context.executionNodeKey !== void 0).map((context) => measurementV2UsageEdgeKey({ targetKey: assignment.targetKey, queryId: assignment.queryId, executionNodeKey: context.executionNodeKey }))));
+  const seen2 = /* @__PURE__ */ new Set();
+  for (const edge of market.usageEdges) {
+    const key = measurementV2UsageEdgeKey(edge);
+    if (!included.has(edge.targetKey) || !frozen.has(key)) throw validationError("Market members must be existing frozen assignments on included Properties.");
+    if (seen2.has(key)) throw validationError("Market membership contains a duplicate assignment.");
+    seen2.add(key);
+  }
+  const reportingScopes = [...authoring.reportingScopes ?? []];
+  const index2 = reportingScopes.findIndex((scope) => scope.stableKey === market.stableKey);
+  if (index2 === -1) reportingScopes.push(market);
+  else reportingScopes[index2] = market;
+  return { authoring: { ...authoring, reportingScopes }, warnings: [] };
+}
 function removeGroup(authoring, body) {
   const { groupKey } = parseBody(measurementDraftRemoveGroupRequestSchema, body, "remove-group");
   const children = authoring.groups.filter((group) => group.parentGroupKey === groupKey);
@@ -18352,6 +18393,8 @@ function applyDraftAction(action, authoring, body, context) {
         return classifyAssignments(authoring, body);
       case "upsert-group":
         return upsertGroup(authoring, body);
+      case "upsert-market":
+        return upsertMarket(authoring, body);
       case "remove-group":
         return removeGroup(authoring, body);
       case "upsert-competitor":
@@ -20220,9 +20263,9 @@ async function measurementDraftRoutes(app, opts = {}) {
       if (missing.length) {
         throw validationError(`Binding ${index2} does not supply ${missing.map((name) => `"${name}"`).join(", ")}.`);
       }
-      let text2 = template.pattern;
-      for (const variable of template.variables) text2 = text2.split(`{${variable}}`).join(binding[variable]);
-      const trimmed = text2.trim();
+      const trimmed = expandQueryTemplate(template.pattern, Object.fromEntries(
+        template.variables.map((variable) => [variable, binding[variable]])
+      ));
       if (!trimmed) throw validationError(`Binding ${index2} expands to an empty question.`);
       if (!expansions.includes(trimmed)) expansions.push(trimmed);
     });
@@ -21372,16 +21415,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) {
@@ -21501,16 +21544,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,
@@ -21582,22 +21620,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,
@@ -21612,9 +21656,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) {
@@ -23842,9 +23886,9 @@ function templateRecords(db, state, addition, audience) {
   const needsMarket = template.variables.includes("market");
   const needsProperty = template.variables.includes("property");
   const expand = (bindings, scopedAudience) => {
-    let queryText = template.pattern;
-    for (const variable of template.variables) queryText = queryText.split(`{${variable}}`).join(bindings[variable] ?? "");
-    queryText = queryText.trim();
+    const queryText = expandQueryTemplate(template.pattern, Object.fromEntries(
+      template.variables.map((variable) => [variable, bindings[variable] ?? ""])
+    ));
     if (!queryText) throw validationError("Template expansion produced an empty query.");
     return {
       queryText,
@@ -34582,6 +34626,7 @@ var SCHEMA_TABLE = {
   MeasurementDraftTargetPage: measurementDraftTargetPageSchema,
   MeasurementDraftUpsertCompetitorRequest: measurementDraftUpsertCompetitorRequestSchema,
   MeasurementDraftUpsertGroupRequest: measurementDraftUpsertGroupRequestSchema,
+  MeasurementDraftUpsertMarketRequest: measurementDraftUpsertMarketRequestSchema,
   MeasurementDraftUpsertTargetRequest: measurementDraftUpsertTargetRequestSchema,
   MeasurementOverviewResponse: measurementOverviewResponseSchema,
   MeasurementPortfolioSummaryResponse: measurementPortfolioSummaryResponseSchema,
@@ -35707,6 +35752,12 @@ var routeCatalog = [
     description: "Reporting membership only. When `competitors` is present it replaces the complete competitor list atomically; omission preserves the existing list for backward compatibility. A payload carrying queries, providers, locations or models is rejected.",
     request: "MeasurementDraftUpsertGroupRequest"
   }),
+  measurementDraftAction({
+    action: "upsert-market",
+    summary: "Configure an explicit market name and frozen membership",
+    description: "Adds or updates a reporting market using existing frozen assignment edges. It never infers geography from groups or creates query executions. Requires draft review and publication before Research can select it.",
+    request: "MeasurementDraftUpsertMarketRequest"
+  }),
   measurementDraftAction({
     action: "remove-group",
     summary: "Remove a draft group",
@@ -36173,7 +36224,7 @@ var routeCatalog = [
     method: "post",
     path: "/api/v1/projects/{name}/research/runs",
     summary: "Start an isolated research query batch",
-    description: "Runs one to fifty ad-hoc queries through one API provider and saves the answer evidence. Research never creates tracked queries, shared runs, snapshots, insights, or notifications. Administrators are always allowed; signed-in viewers require the deployment opt-in and a per-project daily allowance. Read-only and narrowly scoped API keys are refused.",
+    description: "Runs one to fifty ad-hoc queries through one API provider and saves the answer evidence. An optional published Advanced Measurement market or property scope and optional template provenance are frozen with the batch. The provider receives the exact submitted editor question; scope never infers geographic provider location. Research never creates tracked queries, shared runs, snapshots, insights, or notifications. Administrators are always allowed; signed-in viewers require the deployment opt-in and a per-project daily allowance. Read-only and narrowly scoped API keys are refused.",
     tags: ["research"],
     parameters: [nameParameter],
     requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ResearchRunCreate" } } } },
@@ -83142,14 +83193,19 @@ 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 location = input.location === void 0 ? project.defaultLocation ? project.locations.find((item2) => item2.label === project.defaultLocation) ?? null : null : input.location;
+    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 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 (new Set(input.queries.map((query) => query.toLocaleLowerCase())).size !== input.queries.length) throw validationError("Research queries must be unique within a batch.");
-    const normalized = { queries: input.queries, provider: providerName, model: requestedModel2, location: location ?? null };
+    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);
@@ -83174,8 +83230,8 @@ async function researchRoutes(app, opts) {
         }
       }
       const id = crypto49.randomUUID();
-      tx.insert(researchRuns).values({ id, projectId: project.id, status: ResearchRunStatuses.queued, provider: providerName, requestedModel: requestedModel2, resolvedModel, location: location ?? null, totalQueries: input.queries.length, idempotencyKey: input.idempotencyKey ?? null, requestHash: input.idempotencyKey ? requestHash2 : null, initiatedBy, createdAt: now }).run();
-      for (const [position, query] of input.queries.entries()) tx.insert(researchRunQueries).values({ id: crypto49.randomUUID(), researchRunId: id, position, queryText: query, status: ResearchQueryStatuses.queued, requestedModel: requestedModel2, resolvedModel, groundingSources: [], citedDomains: [], searchQueries: [], createdAt: now }).run();
+      tx.insert(researchRuns).values({ id, projectId: project.id, status: ResearchRunStatuses.queued, provider: providerName, requestedModel: requestedModel2, resolvedModel, location: location ?? null, totalQueries: input.queries.length, scope, template, idempotencyKey: input.idempotencyKey ?? null, requestHash: input.idempotencyKey ? requestHash2 : null, initiatedBy, createdAt: now }).run();
+      for (const [position, query] of input.queries.entries()) tx.insert(researchRunQueries).values({ id: crypto49.randomUUID(), researchRunId: id, position, queryText: query, queryClass: queryClasses[position] ?? null, status: ResearchQueryStatuses.queued, requestedModel: requestedModel2, 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 { reused: false, id, shouldDispatch: true };
     });
@@ -83210,6 +83266,52 @@ async function researchRoutes(app, opts) {
     return getDetail(app, project.id, request.params.runId);
   });
 }
+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 resolveResearchScope(active, selection) {
+  if (!active || active.plan.schemaVersion !== 2) {
+    throw validationError("Research scope requires an active Advanced Measurement plan.");
+  }
+  if (selection.expectedPlanRevision !== void 0 && selection.expectedPlanRevision !== active.version.revision) {
+    throw validationError("The selected research scope is stale. Reload the published measurement plan and try again.", {
+      expectedPlanRevision: selection.expectedPlanRevision,
+      activePlanRevision: active.version.revision
+    });
+  }
+  const label = selection.kind === "market" ? active.plan.reportingScopes?.find((scope) => scope.stableKey === selection.key)?.label : active.plan.targets.find((target) => target.stableKey === selection.key)?.label;
+  if (!label) throw validationError("Unknown published research " + selection.kind + ' scope "' + selection.key + '".');
+  return { kind: selection.kind, key: selection.key, label, planRevision: active.version.revision };
+}
+function resolveStoredResearchTemplate(stored, selection, idempotencyKey) {
+  if (!stored || stored.templateId !== selection.templateId || stored.templateVersion !== selection.templateVersion) {
+    throw alreadyExists("Research idempotency key", idempotencyKey);
+  }
+  return stored;
+}
+function resolveResearchTemplate(app, projectId, selection, scope) {
+  if (!scope) throw validationError("Research templates require a selected market or property scope.");
+  const savedTemplate = app.db.select().from(measurementQueryTemplates).where(and55(
+    eq65(measurementQueryTemplates.projectId, projectId),
+    eq65(measurementQueryTemplates.id, selection.templateId)
+  )).get();
+  if (!savedTemplate) throw validationError("Unknown or stale research template. Reload the selected template and try again.");
+  const templateVersion = savedTemplate.updatedAt;
+  if (templateVersion !== selection.templateVersion) {
+    throw validationError("The selected research template is stale. Reload it and try again.");
+  }
+  const { bindings, output } = expandResearchTemplate(savedTemplate, scope);
+  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 };
+}
+function classifyResearchQueries(project, plan, queries2) {
+  const propertyNames = plan ? plan.targets.flatMap((target) => [target.label, ...target.aliases]) : [];
+  const classifier = compileQueryClassifier([...effectiveBrandNames(project), ...propertyNames]);
+  return queries2.map((query) => classifier?.classify(query) ?? null);
+}
 function getDetail(app, projectId, id) {
   const row = app.db.select().from(researchRuns).where(and55(eq65(researchRuns.id, id), eq65(researchRuns.projectId, projectId))).get();
   if (!row) throw notFound("Research run", id);
@@ -83217,10 +83319,10 @@ function getDetail(app, projectId, id) {
   return { ...serializeRun(row), queries: queries2 };
 }
 function serializeRun(row) {
-  return { id: row.id, projectId: row.projectId, status: row.status, provider: row.provider, requestedModel: row.requestedModel, resolvedModel: row.resolvedModel, location: row.location ?? null, totalQueries: row.totalQueries, completedQueries: row.completedQueries, failedQueries: row.failedQueries, error: row.error, initiatedBy: row.initiatedBy ?? null, startedAt: row.startedAt, finishedAt: row.finishedAt, createdAt: row.createdAt };
+  return { id: row.id, projectId: row.projectId, status: row.status, provider: row.provider, requestedModel: row.requestedModel, resolvedModel: row.resolvedModel, location: row.location ?? null, scope: row.scope ?? null, template: row.template ?? null, totalQueries: row.totalQueries, completedQueries: row.completedQueries, failedQueries: row.failedQueries, error: row.error, initiatedBy: row.initiatedBy ?? null, startedAt: row.startedAt, finishedAt: row.finishedAt, createdAt: row.createdAt };
 }
 function serializeQuery(row) {
-  return { id: row.id, position: row.position, query: row.queryText, status: row.status, requestedModel: row.requestedModel, resolvedModel: row.resolvedModel, servedModel: row.servedModel, answerText: row.answerText, groundingSources: row.groundingSources, citedDomains: row.citedDomains, searchQueries: row.searchQueries, namedCompetitors: row.namedCompetitors, citedCompetitorDomains: row.citedCompetitorDomains, answerMentioned: row.answerMentioned, citationState: row.citationState, error: row.error, startedAt: row.startedAt, finishedAt: row.finishedAt, createdAt: row.createdAt };
+  return { id: row.id, position: row.position, query: row.queryText, queryClass: row.queryClass ?? null, status: row.status, requestedModel: row.requestedModel, resolvedModel: row.resolvedModel, servedModel: row.servedModel, answerText: row.answerText, groundingSources: row.groundingSources, citedDomains: row.citedDomains, searchQueries: row.searchQueries, namedCompetitors: row.namedCompetitors, citedCompetitorDomains: row.citedCompetitorDomains, answerMentioned: row.answerMentioned, citationState: row.citationState, error: row.error, startedAt: row.startedAt, finishedAt: row.finishedAt, createdAt: row.createdAt };
 }
 function researchPrincipal(request) {
   const principal = request.principal;

package/dist/{chunk-CDI3YR57.js → chunk-ROPJUNQN.js}

@@ -6379,6 +6379,11 @@ var visibilityReportResponseSchema = z15.object({
 
 // ../contracts/src/query-tracking.ts
 import { z as z16 } from "zod";
+function expandQueryTemplate(pattern, bindings) {
+  let output = pattern;
+  for (const [variable, value] of Object.entries(bindings)) output = output.split(`{${variable}}`).join(value);
+  return output.trim();
+}
 var sha256HexSchema2 = z16.string().regex(/^[a-f0-9]{64}$/);
 var queryTrackingIdSchema = z16.string().trim().min(1).max(256);
 var queryTrackingTextSchema = z16.string().trim().min(1).max(4e3);
@@ -7611,6 +7616,9 @@ var measurementDraftUpsertGroupRequestSchema = z19.object({
     competitors: z19.array(measurementDraftCompetitorSchema).optional()
   }).strict()
 }).strict();
+var measurementDraftUpsertMarketRequestSchema = z19.object({
+  market: measurementDraftReportingScopeSchema
+}).strict();
 var measurementDraftRemoveGroupRequestSchema = z19.object({
   groupKey: measurementV2StableKeySchema
 }).strict();
@@ -16217,11 +16225,50 @@ var ResearchRunStatuses = researchRunStatusSchema.enum;
 var researchQueryStatusSchema = z56.enum(["queued", "running", "completed", "failed"]);
 var ResearchQueryStatuses = researchQueryStatusSchema.enum;
 var DEFAULT_VIEWER_RESEARCH_DAILY_RUN_LIMIT = 20;
+var researchScopeSelectionSchema = z56.object({
+  kind: z56.enum(["market", "property"]),
+  key: measurementV2StableKeySchema,
+  /** Guards a reviewed scope preview from silently using a newer plan revision. */
+  expectedPlanRevision: z56.number().int().positive().optional()
+}).strict();
+var researchRunScopeSchema = z56.object({
+  kind: z56.enum(["market", "property"]),
+  key: measurementV2StableKeySchema,
+  label: z56.string().trim().min(1),
+  planRevision: z56.number().int().positive()
+}).strict();
+var researchQueryTextSchema = z56.string().min(1).max(4e3).refine((value) => value.trim().length > 0, "Research queries cannot be blank.");
+function deduplicateResearchQueries(queries) {
+  const seen = /* @__PURE__ */ new Set();
+  return queries.filter((query) => {
+    const key = normalizeQueryText(query);
+    if (!key || seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+function researchTemplateBindings(scope) {
+  if (!scope) return {};
+  return scope.kind === "market" ? { market: scope.label, submarket: scope.label } : { property: scope.label, propertyBrand: scope.label };
+}
+function expandResearchTemplate(template, scope) {
+  const available = researchTemplateBindings(scope);
+  const unavailable = template.variables.filter((variable) => available[variable] === void 0);
+  if (unavailable.length) throw validationError("The selected research template requires unavailable bindings: " + unavailable.join(", "));
+  const bindings = Object.fromEntries(template.variables.map((variable) => [variable, available[variable]]));
+  return { bindings, output: expandQueryTemplate(template.pattern, bindings) };
+}
+var researchTemplateSelectionSchema = z56.object({
+  templateId: z56.string().trim().min(1).max(256),
+  templateVersion: z56.string().trim().min(1).max(256)
+}).strict();
 var researchRunCreateSchema = z56.object({
-  queries: z56.array(z56.string().trim().min(1).max(4e3)).min(1).max(50),
+  queries: z56.array(researchQueryTextSchema).min(1).max(50),
   provider: z56.string().trim().min(1).optional(),
   model: z56.string().trim().min(1).max(200).optional(),
   location: locationContextSchema.nullable().optional(),
+  scope: researchScopeSelectionSchema.optional(),
+  template: researchTemplateSelectionSchema.optional(),
   idempotencyKey: z56.string().trim().min(1).max(128).optional()
 }).superRefine((value, ctx) => {
   if (value.model && !value.provider) ctx.addIssue({ code: z56.ZodIssueCode.custom, path: ["provider"], message: "provider is required when model is supplied" });
@@ -16240,6 +16287,8 @@ var researchRunSummarySchema = z56.object({
   requestedModel: z56.string().nullable(),
   resolvedModel: z56.string(),
   location: locationContextSchema.nullable(),
+  scope: researchRunScopeSchema.nullable().optional(),
+  template: queryTrackingTemplateProvenanceSchema.nullable().optional(),
   totalQueries: z56.number().int(),
   completedQueries: z56.number().int(),
   failedQueries: z56.number().int(),
@@ -16253,6 +16302,7 @@ var researchRunQuerySchema = z56.object({
   id: z56.string(),
   position: z56.number().int(),
   query: z56.string(),
+  queryClass: queryClassSchema.nullable().optional(),
   status: researchQueryStatusSchema,
   requestedModel: z56.string().nullable(),
   resolvedModel: z56.string(),
@@ -17667,6 +17717,7 @@ export {
   visibilityReportRequestSchema,
   visibilityReportQuerySchema,
   visibilityReportResponseSchema,
+  expandQueryTemplate,
   queryTrackingProvenanceSchema,
   queryTrackingPreviewRequestSchema,
   queryTrackingCommitRequestSchema,
@@ -17732,6 +17783,7 @@ export {
   measurementDraftClearAssignmentsRequestSchema,
   measurementDraftClassifyAssignmentsRequestSchema,
   measurementDraftUpsertGroupRequestSchema,
+  measurementDraftUpsertMarketRequestSchema,
   measurementDraftRemoveGroupRequestSchema,
   measurementDraftUpsertCompetitorRequestSchema,
   measurementDraftPinCompetitorRequestSchema,
@@ -18169,6 +18221,8 @@ export {
   ResearchRunStatuses,
   ResearchQueryStatuses,
   DEFAULT_VIEWER_RESEARCH_DAILY_RUN_LIMIT,
+  deduplicateResearchQueries,
+  expandResearchTemplate,
   researchRunCreateSchema,
   researchRunDetailSchema,
   researchRunListSchema,