@olives/devos 2.1.0

package/.agents/skills/vercel-optimize/lib/observation-safety.mjs

@@ -0,0 +1,174 @@
+export function splitCustomerSafeObservations(observations, abstentions = [], signals = {}) {
+  const safe = [];
+  const heldBack = [];
+  for (const observation of Array.isArray(observations) ? observations : []) {
+    const unsafeReason = unsupportedObservationReason(observation, abstentions, signals);
+    if (unsafeReason) {
+      heldBack.push({
+        candidateRef: observation?.candidateRef ?? null,
+        reason: unsafeReason,
+        needsEvidence: true,
+      });
+    } else {
+      safe.push(observation);
+    }
+  }
+  return { observations: safe, heldBackObservations: heldBack };
+}
+
+function unsupportedObservationReason(observation, abstentions = [], signals = {}) {
+  if (contradictsNoChangeReason(observation, abstentions)) {
+    return 'This observation repeated an action that another investigation rejected. Re-run with a single scoped candidate before applying it.';
+  }
+  if (hasUnsupportedWafBotCategoryClaim(observation)) {
+    return 'This observation described an Observability bot category as a WAF-rule condition without supported rule evidence. Re-run with documented WAF condition evidence before applying it.';
+  }
+  if (hasUnsafeBotProtectionObservation(observation)) {
+    return 'This observation recommended Bot Protection or WAF changes without a staged safe-rollout plan and allowlist review. Promote it to a verified platform recommendation before applying it.';
+  }
+  if (hasStaleNextCacheApiObservation(observation, signals)) {
+    return 'This observation used a cache API that does not match the detected framework-version evidence. Re-run with the current Next.js cache evidence before applying it.';
+  }
+  if (hasUnsupportedFrameworkCausalClaim(observation)) {
+    return 'This observation made a framework-specific cause claim that verification could not support. Re-run with runtime logs or official framework evidence before applying it.';
+  }
+  if (hasUnsupportedStaticGenerationClaim(observation)) {
+    return 'This observation made a static-generation behavior claim that verification could not support. Re-run with route-manifest or runtime evidence before applying it.';
+  }
+  if (hasUnsupportedSourceAbsenceClaim(observation)) {
+    return 'This observation made a source-file absence claim that verification could not support. Re-run with a file-existence check or runtime logs before applying it.';
+  }
+  if (hasUnsupportedCacheLifeCdnClaim(observation)) {
+    return 'This observation depended on an unsupported cacheLife-to-CDN claim. Re-run with production header evidence before applying it.';
+  }
+  if (hasUnsupportedRuntimeRootCauseClaim(observation)) {
+    return 'This observation made a runtime root-cause claim that needs log, stack, or upstream response evidence before it can ship.';
+  }
+  if (hasImplementationGradeObservationAction(observation)) {
+    return 'This observation described an implementation change that needs the ready-to-apply recommendation evidence bar before it can ship.';
+  }
+  return null;
+}
+
+function observationText(observation) {
+  return [
+    observation?.summary,
+    observation?.evidence,
+    observation?.suggestedAction,
+  ].filter(Boolean).join(' ');
+}
+
+function evidenceText(observation) {
+  return [
+    observation?.summary,
+    observation?.evidence,
+  ].filter(Boolean).join(' ');
+}
+
+function hasUnsupportedWafBotCategoryClaim(observation) {
+  const text = observationText(observation);
+  if (!/\bWAF\b/i.test(text)) return false;
+  return /\bbot_category\s*=/i.test(text) ||
+    /\btarget(?:ing)?\s+(?:browser_impersonation|automated_browser|ecommerce|monitor)\b/i.test(text);
+}
+
+function hasUnsafeBotProtectionObservation(observation) {
+  const text = observationText(observation);
+  if (!/\b(?:Bot Protection|BotID|bot_filter|WAF|managed bot rules?)\b/i.test(text)) return false;
+  const recommendsAction = /\b(?:enable|add|create|configure|challenge|deny|block|rate-limit|target)\b/i.test(String(observation?.suggestedAction ?? ''));
+  if (!recommendsAction) return false;
+  const hasSafeRollout = /\b(?:staged|log mode|log action|dry run)\b/i.test(text);
+  const hasAllowlist = /\ballowlist|exclusions?\b/i.test(text);
+  return !(hasSafeRollout && hasAllowlist);
+}
+
+function hasStaleNextCacheApiObservation(observation, signals = {}) {
+  const text = observationText(observation);
+  if (!/\bunstable_cache\b/.test(text)) return false;
+  if (signals?.stack?.framework !== 'next') return false;
+  const major = parseInt(String(signals?.stack?.frameworkVersion ?? '').match(/\d+/)?.[0] ?? '', 10);
+  return Number.isFinite(major) && major >= 16;
+}
+
+function hasImplementationGradeObservationAction(observation) {
+  const action = String(observation?.suggestedAction ?? '');
+  if (action.trim() === '') return false;
+  if (/\b(?:use cache:\s*remote|unstable_cache|Cache-Control|s-maxage|cacheLife|export const revalidate|checkBotId|BotID)\b/i.test(action)) return true;
+  return /\b(?:enable|add|wrap|apply|move|parallelize|set|create|configure|deny|challenge|block|fix|replace|refactor|rewrite|upgrade|downgrade)\b/i.test(action) ||
+    /\bcache\s+(?:the|this|that|shared|public|origin|response|route|data|lookup|fetch|helper)\b/i.test(action) ||
+    /\bturn\s+(?:on|off)\b/i.test(action) ||
+    /\bswitch\s+(?:to|from|the|this)\b/i.test(action) ||
+    /\buse\s+Promise\.all\b/i.test(action) ||
+    /\b(?:raise|lower|increase|decrease)\s+(?:the\s+)?(?:TTL|timeout|memory|CPU|cache|cache lifetime|duration)\b/i.test(action);
+}
+
+function contradictsNoChangeReason(observation, abstentions) {
+  const target = candidateTarget(observation?.candidateRef);
+  if (!target) return false;
+  const lowerObservationText = observationText(observation).toLowerCase();
+  const relevantReasons = abstentions
+    .filter((a) => candidateTarget(a?.candidateRef) === target)
+    .map((a) => String(a?.reason ?? '').toLowerCase());
+  if (relevantReasons.length === 0) return false;
+
+  if (/\bparalleliz(?:e|ing)\b/.test(lowerObservationText) &&
+      /\bgetsession\b/.test(lowerObservationText) &&
+      relevantReasons.some((reason) => /\bgetsession\b/.test(reason) && /\b(?:gates?|redirect|auth-preserving|blocked)\b/.test(reason))) {
+    return true;
+  }
+  return false;
+}
+
+function candidateTarget(ref) {
+  if (typeof ref !== 'string') return null;
+  const idx = ref.indexOf(':');
+  if (idx === -1) return null;
+  return ref.slice(idx + 1);
+}
+
+function hasUnsupportedFrameworkCausalClaim(observation) {
+  const text = observationText(observation).toLowerCase();
+  if (!text.includes('notfound') || !text.includes('use cache')) return false;
+  return (
+    /known next\.js cache components edge case/.test(text) ||
+    /next\.js\s+\d+(?:\.\d+)?[^.]{0,120}treats[^.]{0,120}dynamic api/.test(text) ||
+    /can surface as 5xx/.test(text) ||
+    /surface as 500/.test(text) ||
+    /instead of throwing inside (?:the )?cache/.test(text) ||
+    /cache boundary/.test(text)
+  );
+}
+
+function hasUnsupportedStaticGenerationClaim(observation) {
+  const text = observationText(observation).toLowerCase();
+  if (!/\bgeneratestaticparams\b/.test(text)) return false;
+  return /\b(?:returns?\s*(?:an\s+)?empty|\[\])\b[^.\n]{0,240}\b(?:every request|on[- ]demand|no params? (?:are )?prebuilt|populate generatestaticparams|served from (?:the )?cdn|hit bucket|cachebreakdown)\b/i.test(text) ||
+    /\b(?:every request|on[- ]demand|no params? (?:are )?prebuilt|populate generatestaticparams|served from (?:the )?cdn|hit bucket|cachebreakdown)\b[^.\n]{0,240}\b(?:returns?\s*(?:an\s+)?empty|\[\])\b/i.test(text) ||
+    /\bdynamic\s*=\s*['"`]error['"`]\b[^.\n]{0,240}\b(?:generatestaticparams|dynamicparams|every request|on[- ]demand)\b/i.test(text);
+}
+
+function hasUnsupportedSourceAbsenceClaim(observation) {
+  const ref = String(observation?.candidateRef ?? '');
+  if (!ref.startsWith('route_errors:')) return false;
+  const text = observationText(observation).toLowerCase();
+  return /\b(?:enoent|no\s+(?:matching|corresponding)\s+(?:mdx|file|post)|missing\s+(?:mdx|file|post)|does\s+not\s+exist|not\s+found\s+on\s+disk)\b/.test(text);
+}
+
+function hasUnsupportedCacheLifeCdnClaim(observation) {
+  return hasUnsupportedCacheLifeCdnText(observationText(observation));
+}
+
+export function hasUnsupportedCacheLifeCdnText(text) {
+  if (typeof text !== 'string' || !/\bcacheLife\b/i.test(text)) return false;
+  if (/\btoLaunch-\d+\b/i.test(text)) return true;
+  return /\bcacheLife\b[^.\n]{0,240}\b(?:Cache-Control|s-maxage|CDN|edge cache|cache breakdown|x-vercel-cache|HIT|MISS|function (?:still )?runs per request|every request invokes the function|canonical|toLaunch-\d+)\b/i.test(text) ||
+    /\b(?:Cache-Control|s-maxage|CDN|edge cache|cache breakdown|x-vercel-cache|HIT|MISS|function (?:still )?runs per request|every request invokes the function|canonical|toLaunch-\d+)\b[^.\n]{0,240}\bcacheLife\b/i.test(text) ||
+    /\b(?:no|never|without|missing)\s+cacheLife\b[^.\n]{0,240}\b(?:no|not|never|0%|every|per request|function)\b[^.\n]{0,120}\b(?:cache|cached|hit|runs?|invoke)/i.test(text);
+}
+
+function hasUnsupportedRuntimeRootCauseClaim(observation) {
+  const text = observationText(observation);
+  if (!/\b(?:caused by|root cause|responsible for failures|would produce)\b/i.test(text)) return false;
+  if (!/\b(?:5xx|500|error|failures?)\b/i.test(text)) return false;
+  return !/\b(?:logs?\s+(?:show|confirm|include|contain)|stack\s+(?:shows|trace|evidence)|trace\s+(?:shows|confirms)|exception\s+(?:shows|confirms)|response body\s+(?:shows|confirms)|runtime evidence)\b/i.test(evidenceText(observation));
+}

package/.agents/skills/vercel-optimize/lib/project-facts.mjs

@@ -0,0 +1,99 @@
+// Single source for "already on" project facts. Feeds report Strengths, sub-agent brief, and verifier contradiction check.
+// contradictPhrases must lowercase exactly — verifier does case-insensitive substring match.
+
+// Stable order = byte-identical brief output. Empty result when project config didn't load — don't pretend.
+export function deriveProjectFacts(signals) {
+  const out = [];
+  const cfg = signals?.project?.defaultResourceConfig;
+  const projectErr = signals?.project?.error;
+  if (!cfg || projectErr) return out;
+
+  if (cfg.fluid === true) {
+    out.push({
+      id: 'fluid_compute',
+      strength: 'Fluid Compute is enabled (`defaultResourceConfig.fluid=true`) — instance reuse + reduced cold starts active.',
+      briefLine: 'Fluid Compute is ENABLED on this project (`defaultResourceConfig.fluid=true`). Do not recommend toggling it on.',
+      contradictPhrases: [
+        'enable fluid compute',
+        'enable fluid',
+        'turn on fluid compute',
+        'switch to fluid compute',
+        'migrate to fluid compute',
+        'opt in to fluid compute',
+      ],
+    });
+  }
+  if (cfg.elasticConcurrencyEnabled === true) {
+    out.push({
+      id: 'in_function_concurrency',
+      strength: 'In-function concurrency is enabled — multiple invocations share a single function instance, lowering active CPU costs on I/O-bound work.',
+      briefLine: 'In-function concurrency is ENABLED. Do not recommend toggling it on.',
+      contradictPhrases: [
+        'enable in-function concurrency',
+        'enable elastic concurrency',
+        'turn on in-function concurrency',
+        'enable concurrent invocations',
+      ],
+    });
+  }
+  if (cfg.functionDefaultMemoryType === 'standard') {
+    out.push({
+      id: 'memory_standard',
+      strength: 'Function memory tier: Standard (2GB) — the cost-efficient default; upgrade to Performance (4GB) only with memory, CPU-bound, or latency-sensitive route evidence.',
+      briefLine: 'Function memory tier is Standard (2GB), the cost-efficient default. Recommending an upgrade to Performance (4GB) requires memory, CPU-bound, or latency-sensitive route evidence.',
+      contradictPhrases: [],
+    });
+  } else if (cfg.functionDefaultMemoryType === 'performance') {
+    out.push({
+      id: 'memory_performance',
+      strength: 'Function memory tier: **Performance (4GB)** — verify this is intentional; Performance costs ~2x Standard. If your routes don\'t saturate Standard\'s memory headroom, downgrade.',
+      briefLine: 'Function memory tier is Performance (4GB). Do not recommend upgrading further — the next valid tier change is downgrading to Standard.',
+      contradictPhrases: [
+        'upgrade memory to performance',
+        'upgrade to performance memory',
+        'switch to performance memory',
+        'enable performance memory',
+      ],
+    });
+  }
+  if (Array.isArray(cfg.functionDefaultRegions) && cfg.functionDefaultRegions.length > 0) {
+    const r = cfg.functionDefaultRegions;
+    out.push({
+      id: 'function_regions',
+      strength: `Function regions: \`${r.join(', ')}\` (${r.length === 1 ? 'single region' : 'multi-region'}).`,
+      briefLine: `Function regions configured: ${r.join(', ')}. If your rec hinges on region placement, it must accept this configuration as the starting point.`,
+      contradictPhrases: [],
+    });
+  }
+  if (cfg.functionZeroConfigFailover === true) {
+    out.push({
+      id: 'zero_config_failover',
+      strength: 'Function failover is enabled in project config.',
+      briefLine: 'Function failover is ENABLED in project config. Do not recommend enabling it.',
+      contradictPhrases: [
+        'enable zero-config failover',
+        'enable multi-region failover',
+        'turn on zero-config failover',
+      ],
+    });
+  }
+  return out;
+}
+
+// `why` excluded — citing a fact as evidence ("fluid is on, so …") is legitimate, not contradiction.
+export function findRecContradictions(rec, facts) {
+  if (!rec || typeof rec !== 'object') return [];
+  if (!Array.isArray(facts) || facts.length === 0) return [];
+  const haystack = [
+    rec.what,
+    rec.fix,
+    rec.desiredBehavior,
+    rec.currentBehavior,
+  ]
+    .map((s) => (typeof s === 'string' ? s.toLowerCase() : ''))
+    .join('\n');
+  if (!haystack) return [];
+  return facts.filter((f) =>
+    (f.contradictPhrases ?? []).some((p) => haystack.includes(p.toLowerCase()))
+  );
+}

package/.agents/skills/vercel-optimize/lib/queries.mjs

@@ -0,0 +1,315 @@
+// Declarative metric-query registry. Single source for every `vercel metrics ...` call.
+//
+// CLI default --since is 1h. Mixing 1h with 14d windows silently produces incompatible rollups — every query MUST pass since: TIME_WINDOW. test/time-window.test.mjs enforces this.
+// 14d: long enough for weekly cycles, short enough to surface recent regressions before stale data dilutes them.
+
+import { normalizeSummary } from './vercel.mjs';
+
+export const TIME_WINDOW = '14d';
+
+// CLI default cardinality cap is 10 — too small for a typical app.
+const ROUTE_LIMIT = 200;
+const HOST_LIMIT = 50;
+const DIM_LIMIT = 50;
+
+// CLI emits value under `<metric_id_with_underscores>_<aggregation>` (e.g. `vercel_request_count_sum`).
+function defaultNormalize(metricId, aggregation, groupBy) {
+  return (resp) => ({ rows: normalizeSummary(resp, metricId, aggregation, groupBy) });
+}
+
+// Collapse (route × function_start_type) rows into one row per route. Observed values: "cold", "hot", "prewarmed".
+function normalizeColdStart(metricId, aggregation) {
+  return (resp) => {
+    const rows = normalizeSummary(resp, metricId, aggregation, ['route', 'function_start_type']);
+    const byRoute = new Map();
+    for (const r of rows) {
+      if (!r.route) continue;
+      const prior = byRoute.get(r.route) ?? { route: r.route, total: 0, coldCount: 0, warmCount: 0, prewarmedCount: 0 };
+      const v = r.value ?? 0;
+      prior.total += v;
+      if (r.function_start_type === 'cold') prior.coldCount += v;
+      else if (r.function_start_type === 'hot') prior.warmCount += v;
+      else if (r.function_start_type === 'prewarmed') prior.prewarmedCount += v;
+      byRoute.set(r.route, prior);
+    }
+    return {
+      rows: [...byRoute.values()].map((r) => ({
+        ...r,
+        coldPct: r.total > 0 ? r.coldCount / r.total : 0,
+      })),
+    };
+  };
+}
+
+export const QUERIES = [
+  {
+    id: 'requestsByRouteCache',
+    metricId: 'vercel.request.count',
+    aggregation: 'sum',
+    groupBy: ['route', 'cache_result'],
+    limit: ROUTE_LIMIT,
+    description: 'Request count per route × cache_result. Source of cache hit rate; total invocations folds across cache_result.',
+  },
+  {
+    id: 'fnDurationP95ByRoute',
+    metricId: 'vercel.function_invocation.function_duration_ms',
+    aggregation: 'p95',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'p95 wall-clock function duration per route. Canonical slow-route signal.',
+  },
+  {
+    id: 'requestsByRouteStatus',
+    metricId: 'vercel.request.count',
+    aggregation: 'sum',
+    groupBy: ['route', 'http_status'],
+    limit: ROUTE_LIMIT,
+    description: 'Request count per route × http_status. Compatibility fallback for older route_errors fixtures.',
+  },
+  {
+    id: 'fnStatusByRoute',
+    metricId: 'vercel.function_invocation.count',
+    aggregation: 'sum',
+    groupBy: ['route', 'http_status'],
+    limit: ROUTE_LIMIT,
+    description: 'Function invocation count per route × http_status. Canonical 5xx source for slow_route disqualification and route_errors.',
+  },
+  {
+    id: 'requestsByRouteMethod',
+    metricId: 'vercel.request.count',
+    aggregation: 'sum',
+    groupBy: ['route', 'request_method'],
+    limit: ROUTE_LIMIT,
+    description: 'Request count per route × request_method. Uncached_route gate uses this to skip mostly-POST routes (Server Actions, mutations) where 0% cache is correct behavior.',
+  },
+  {
+    id: 'externalApiP75',
+    metricId: 'vercel.external_api_request.request_duration_ms',
+    aggregation: 'p75',
+    groupBy: ['origin_hostname'],
+    limit: HOST_LIMIT,
+    description: 'p75 external API duration per origin hostname.',
+  },
+
+  {
+    id: 'fnStartTypeByRoute',
+    metricId: 'vercel.function_invocation.count',
+    aggregation: 'sum',
+    groupBy: ['route', 'function_start_type'],
+    limit: ROUTE_LIMIT,
+    description: 'Function invocation count split by cold | hot | prewarmed. Feeds cold_start gate.',
+    normalizer: normalizeColdStart('vercel.function_invocation.count', 'sum'),
+  },
+  {
+    id: 'fnGbHrByRoute',
+    metricId: 'vercel.function_invocation.function_duration_gbhr',
+    aggregation: 'sum',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'Billed GB-hours per route (function duration in Fluid billing).',
+  },
+  {
+    id: 'fnCpuMsByRoute',
+    metricId: 'vercel.function_invocation.function_cpu_time_ms',
+    aggregation: 'sum',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'Active CPU time per route. Fluid Compute bills on this; high CPU = expensive route.',
+  },
+  {
+    id: 'fnPeakMemoryByRoute',
+    metricId: 'vercel.function_invocation.peak_memory_mb',
+    aggregation: 'max',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'Peak memory observed per route. Compared against provisioned to right-size.',
+  },
+  {
+    id: 'fnProvisionedMemoryByRoute',
+    metricId: 'vercel.function_invocation.provisioned_memory_mb',
+    aggregation: 'max',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'Provisioned memory per route. Feeds oversized_memory gate.',
+  },
+  {
+    id: 'fnTtfbP95ByRoute',
+    metricId: 'vercel.function_invocation.ttfb_ms',
+    aggregation: 'p95',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'Server-measured time-to-first-byte per route. Complements function_duration_ms p95.',
+  },
+
+  {
+    id: 'fdtByRoute',
+    metricId: 'vercel.request.fdt_total_bytes',
+    aggregation: 'sum',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'Fast Data Transfer bytes per route. Bandwidth cost driver.',
+  },
+  {
+    id: 'fdtByBot',
+    metricId: 'vercel.request.fdt_total_bytes',
+    aggregation: 'sum',
+    groupBy: ['bot_category'],
+    limit: DIM_LIMIT,
+    description: 'FDT bytes by bot category. Empty `bot_category` = human traffic; non-empty = bots.',
+  },
+  {
+    id: 'fdtByCache',
+    metricId: 'vercel.request.fdt_total_bytes',
+    aggregation: 'sum',
+    groupBy: ['cache_result'],
+    limit: DIM_LIMIT,
+    description: 'FDT bytes by cache_result. Uncached vs cached bandwidth.',
+  },
+
+  {
+    id: 'middlewareCount',
+    metricId: 'vercel.middleware_invocation.count',
+    aggregation: 'sum',
+    groupBy: ['request_path'],
+    limit: ROUTE_LIMIT,
+    description: 'Middleware invocations per request_path. Heavy middleware traffic = missing matcher.',
+  },
+  {
+    id: 'middlewareDurationP95',
+    metricId: 'vercel.middleware_invocation.duration_ms',
+    aggregation: 'p95',
+    groupBy: ['request_path'],
+    limit: ROUTE_LIMIT,
+    description: 'p95 middleware duration per request_path.',
+  },
+
+  {
+    id: 'isrReadsByRoute',
+    metricId: 'vercel.isr_operation.read_units',
+    aggregation: 'sum',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'ISR read units per route. Healthy when high relative to writes.',
+  },
+  {
+    id: 'isrWritesByRoute',
+    metricId: 'vercel.isr_operation.write_units',
+    aggregation: 'sum',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'ISR write units per route. High writes/reads = over-aggressive revalidate.',
+  },
+
+  {
+    id: 'imageCount',
+    metricId: 'vercel.image_transformation.count',
+    aggregation: 'sum',
+    groupBy: [],
+    limit: 1,
+    description: 'Total image transformations performed.',
+  },
+  {
+    id: 'imageByHost',
+    metricId: 'vercel.image_transformation.count',
+    aggregation: 'sum',
+    groupBy: ['source_image_hostname'],
+    limit: HOST_LIMIT,
+    description: 'Image transformations per source hostname. Identify which hosts dominate the bill.',
+  },
+  {
+    id: 'imageSourceBytes',
+    metricId: 'vercel.image_transformation.source_size_bytes',
+    aggregation: 'sum',
+    groupBy: [],
+    limit: 1,
+    description: 'Bytes of source images optimized. High = ingress bandwidth cost.',
+  },
+
+  {
+    id: 'cwvLcpByRoute',
+    metricId: 'vercel.speed_insights_metric.lcp',
+    aggregation: 'p75',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'p75 Largest Contentful Paint per route. > 2500ms = poor.',
+  },
+  {
+    id: 'cwvInpByRoute',
+    metricId: 'vercel.speed_insights_metric.inp',
+    aggregation: 'p75',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'p75 Interaction to Next Paint per route. > 200ms = poor.',
+  },
+  {
+    id: 'cwvClsByRoute',
+    metricId: 'vercel.speed_insights_metric.cls',
+    aggregation: 'p75',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'p75 Cumulative Layout Shift per route. > 0.1 = poor.',
+  },
+  {
+    id: 'cwvTtfbByRoute',
+    metricId: 'vercel.speed_insights_metric.ttfb_ms',
+    aggregation: 'p75',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'p75 client-measured TTFB per route.',
+  },
+  {
+    id: 'cwvCount',
+    metricId: 'vercel.speed_insights_metric.count',
+    aggregation: 'sum',
+    groupBy: [],
+    limit: 1,
+    description: 'Total Speed Insights measurements. Use to decide whether CWV gates have enough signal.',
+  },
+  {
+    id: 'cwvCountByRoute',
+    metricId: 'vercel.speed_insights_metric.count',
+    aggregation: 'sum',
+    groupBy: ['route'],
+    limit: ROUTE_LIMIT,
+    description: 'Speed Insights measurements per route. CWV route gates require at least 50 samples on the specific route.',
+  },
+
+  {
+    id: 'firewallByAction',
+    metricId: 'vercel.firewall_action.count',
+    aggregation: 'sum',
+    groupBy: ['waf_action'],
+    limit: DIM_LIMIT,
+    description: 'Firewall action count per waf_action (allow | challenge | block | log).',
+  },
+  {
+    id: 'botIdChecks',
+    metricId: 'vercel.bot_id_check.count',
+    aggregation: 'sum',
+    groupBy: [],
+    limit: 1,
+    description: 'Total BotID checks. > 0 confirms BotID is wired up; = 0 confirms it is not.',
+  },
+
+  {
+    id: 'externalApiCount',
+    metricId: 'vercel.external_api_request.count',
+    aggregation: 'sum',
+    groupBy: ['origin_hostname'],
+    limit: HOST_LIMIT,
+    description: 'External API call count per origin hostname.',
+  },
+  {
+    id: 'externalApiBytes',
+    metricId: 'vercel.external_api_request.transfer_bytes',
+    aggregation: 'sum',
+    groupBy: ['origin_hostname'],
+    limit: HOST_LIMIT,
+    description: 'Outbound bytes per external API hostname.',
+  },
+];
+
+export function normalizerFor(entry) {
+  if (entry.normalizer) return entry.normalizer;
+  return defaultNormalize(entry.metricId, entry.aggregation, entry.groupBy);
+}