@olives/devos 2.1.0

package/.agents/skills/vercel-optimize/lib/gates/cold-start.mjs

@@ -0,0 +1,66 @@
+// Signal: `function_start_type` dimension on `vercel.function_invocation.count` (cold|hot|prewarmed).
+// Threshold WHY: 40%+ cold is fixable via Fluid keep-warm; 30% is the noise floor for serverless without keep-warm.
+// total>=1000/14d (~3/hr) keeps Poisson CI on cold rate at ~±5% near the 40% threshold.
+export const metadata = {
+  id: 'cold_start',
+  threshold: 'coldPct > 0.4 AND total >= 1000',
+  billingDimension: 'function-duration',
+  scope: 'route',
+  sourceCitation: 'vercel-optimize gate threshold',
+  description:
+    'Routes where > 40% of invocations are cold-start, at meaningful traffic (>=1,000 total invocations in window). Cold starts add 200-800ms per request and break the perceived latency budget on cache-miss paths. The 40% threshold is where cold-rate becomes a real signal vs Poisson noise on serverless. Sourced from vercel.function_invocation.count grouped by function_start_type.',
+};
+
+export function gate(signals) {
+  const cs = extractColdStarts(signals);
+  return cs
+    .filter((r) => r.coldPct > 0.4 && r.total >= 1000)
+    .map((r) => ({
+      kind: metadata.id,
+      scope: 'route',
+      route: r.route,
+      files: [],
+      priority: Math.round(r.total * r.coldPct),
+      confidence: 0.92,
+      o11ySignal: `cold=${(r.coldPct * 100).toFixed(0)}%,inv=${r.total}`,
+      reason: 'high cold-start rate on hot route',
+      question: `What initialization or bundle overhead makes ${r.route} cold-start ${(r.coldPct * 100).toFixed(0)}% of ${r.total} invocations?`,
+      evidence: { metric: 'fnStartTypeByRoute', route: r.route, coldPct: r.coldPct, total: r.total, coldCount: r.coldCount ?? null },
+    }));
+}
+
+function extractColdStarts(signals) {
+  const live = signals.metrics?.fnStartTypeByRoute;
+  if (Array.isArray(live?.rows) && live.rows.some((r) => 'coldCount' in r || 'coldPct' in r)) {
+    return live.rows
+      .filter((r) => r.route)
+      .map((r) => ({
+        route: r.route,
+        total: r.total ?? 0,
+        coldCount: r.coldCount ?? 0,
+        coldPct: r.coldPct ?? 0,
+      }));
+  }
+
+  // Legacy fixture: pre-derived coldStartByRoute rows.
+  const direct = signals.metrics?.coldStartByRoute;
+  if (Array.isArray(direct?.rows)) {
+    return direct.rows
+      .filter((r) => r.route)
+      .map((r) => ({ route: r.route, coldPct: r.coldPct ?? 0, total: r.total ?? 0 }));
+  }
+
+  // Older legacy fixture: series + summary shape.
+  const legacy = signals.metrics?.coldStarts;
+  if (Array.isArray(legacy?.series)) {
+    return legacy.series
+      .map((s) => {
+        const total = s.summary?.count ?? 0;
+        const coldCount = s.summary?.coldCount ?? s.summary?.sum ?? 0;
+        return { route: s.groupValues?.route, total, coldPct: total > 0 ? coldCount / total : 0 };
+      })
+      .filter((r) => r.route);
+  }
+
+  return [];
+}

package/.agents/skills/vercel-optimize/lib/gates/contract.mjs

@@ -0,0 +1,79 @@
+const VALID_SCOPES = new Set(['route', 'file', 'account']);
+
+export class CandidateContractError extends Error {
+  constructor(errors) {
+    super(`gate candidate contract failed:\n${errors.map((e) => `- ${e}`).join('\n')}`);
+    this.name = 'CandidateContractError';
+    this.errors = errors;
+  }
+}
+
+export function validateCandidates(candidates, ctx = {}) {
+  if (!Array.isArray(candidates)) {
+    throw new CandidateContractError([`${ctx.source ?? 'gate'}: expected candidate array`]);
+  }
+  const errors = [];
+  for (let i = 0; i < candidates.length; i++) {
+    errors.push(...validateCandidate(candidates[i], { ...ctx, index: i }).errors);
+  }
+  if (errors.length > 0) throw new CandidateContractError(errors);
+  return candidates;
+}
+
+export function validateCandidate(candidate, ctx = {}) {
+  const label = candidateLabel(candidate, ctx);
+  const errors = [];
+  if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+    return { ok: false, errors: [`${label}: candidate must be an object`] };
+  }
+
+  if (!nonEmptyString(candidate.kind)) errors.push(`${label}: kind must be a non-empty string`);
+  if (!VALID_SCOPES.has(candidate.scope)) {
+    errors.push(`${label}: scope must be one of route, file, account`);
+  }
+  if (!Number.isFinite(candidate.priority)) errors.push(`${label}: priority must be a finite number`);
+  if (!Number.isFinite(candidate.confidence)) errors.push(`${label}: confidence must be a finite number`);
+  if (Array.isArray(candidate.files)) {
+    if (!candidate.files.every((f) => typeof f === 'string' && f.length > 0)) {
+      errors.push(`${label}: files must contain only non-empty strings`);
+    }
+  } else {
+    errors.push(`${label}: files must be an array`);
+  }
+  if (!nonEmptyString(candidate.reason)) errors.push(`${label}: reason must be a non-empty string`);
+  if (!nonEmptyString(candidate.question)) errors.push(`${label}: question must be a non-empty string`);
+
+  if (candidate.scope === 'route') {
+    const hasRoute = nonEmptyString(candidate.route);
+    const hasHostname = nonEmptyString(candidate.hostname);
+    if (!hasRoute && !hasHostname) {
+      errors.push(`${label}: route-scoped candidates must set route or hostname`);
+    }
+  }
+  if (candidate.scope === 'file') {
+    if (candidate.route != null || candidate.hostname != null) {
+      errors.push(`${label}: file-scoped candidates must not set route or hostname`);
+    }
+    if (!Array.isArray(candidate.files) || candidate.files.length === 0) {
+      errors.push(`${label}: file-scoped candidates must include at least one file`);
+    }
+  }
+  if (candidate.scope === 'account') {
+    if (candidate.route != null || candidate.hostname != null) {
+      errors.push(`${label}: account-scoped candidates must not set route or hostname`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+function candidateLabel(candidate, ctx) {
+  const source = ctx.source ?? 'gate';
+  const index = ctx.index == null ? '?' : ctx.index;
+  const kind = candidate?.kind ?? '?';
+  return `${source}[${index}] ${kind}`;
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}

package/.agents/skills/vercel-optimize/lib/gates/cwv-poor.mjs

@@ -0,0 +1,87 @@
+// Thresholds are Google's "Poor" band (https://web.dev/articles/vitals): LCP p75 > 2500ms, INP > 200ms, CLS > 0.1.
+// When Speed Insights isn't wired up the metrics come back empty and the gate is a no-op.
+import { withRouteShapeWarnings } from '../route-normalize.mjs';
+
+export const metadata = {
+  id: 'cwv_poor',
+  threshold: 'LCP p75>2500 OR INP p75>200 OR CLS p75>0.1, AND speed_insights count > 50',
+  billingDimension: 'speed-insights',
+  scope: 'route',
+  sourceCitation: 'https://web.dev/articles/vitals',
+  description:
+    'Routes where Core Web Vitals fall into Google\'s "Poor" band on real-user traffic. LCP > 2500ms, INP > 200ms, or CLS > 0.1 each hurt SEO and conversion. Surfaces one candidate per (route, metric) pair to keep recommendations focused.',
+};
+
+// Below this floor p75 is too noisy to act on.
+const MIN_PER_ROUTE_SAMPLES = 50;
+
+export function gate(signals) {
+  const totalSamples = sumRows(signals.metrics?.cwvCount?.rows);
+  if (totalSamples === 0) return [];
+
+  const countByRoute = byRoute(signals.metrics?.cwvCountByRoute?.rows);
+  const lcpBy = byRoute(signals.metrics?.cwvLcpByRoute?.rows);
+  const inpBy = byRoute(signals.metrics?.cwvInpByRoute?.rows);
+  const clsBy = byRoute(signals.metrics?.cwvClsByRoute?.rows);
+
+  const routes = new Set([...lcpBy.keys(), ...inpBy.keys(), ...clsBy.keys()]);
+  const out = [];
+  for (const route of routes) {
+    const routeSamples = countByRoute.get(route) ?? 0;
+    if (routeSamples < MIN_PER_ROUTE_SAMPLES) continue;
+    const lcp = lcpBy.get(route);
+    const inp = inpBy.get(route);
+    const cls = clsBy.get(route);
+    const issues = [];
+    if (lcp != null && lcp > 2500) issues.push({ metric: 'LCP', value: Math.round(lcp), threshold: 2500, unit: 'ms' });
+    if (inp != null && inp > 200) issues.push({ metric: 'INP', value: Math.round(inp), threshold: 200, unit: 'ms' });
+    if (cls != null && cls > 0.1) issues.push({ metric: 'CLS', value: round2(cls), threshold: 0.1, unit: '' });
+    if (issues.length === 0) continue;
+
+    const summary = issues.map((i) => `${i.metric}=${i.value}${i.unit}`).join(',');
+    out.push(withRouteShapeWarnings({
+      kind: metadata.id,
+      scope: 'route',
+      route,
+      files: [],
+      priority: issues.reduce((s, i) => s + ratioOverThreshold(i), 0) * 10,
+      confidence: 0.82,
+      o11ySignal: summary,
+      reason: 'real-user Core Web Vitals in poor band',
+      question: `On ${route}, ${summary}. Which client-side work (bundle weight, blocking scripts, layout shifts, hydration) is responsible, and which change would land first?`,
+      evidence: {
+        metric: 'cwv',
+        route,
+        lcpMs: lcp != null ? Math.round(lcp) : null,
+        inpMs: inp != null ? Math.round(inp) : null,
+        cls: cls != null ? round2(cls) : null,
+        issues,
+        totalSpeedInsightsSamples: totalSamples,
+        routeSpeedInsightsSamples: routeSamples,
+      },
+    }, signals));
+  }
+  return out;
+}
+
+function byRoute(rows) {
+  const m = new Map();
+  for (const r of rows ?? []) {
+    if (!r.route || r.value == null) continue;
+    m.set(r.route, r.value);
+  }
+  return m;
+}
+
+function sumRows(rows) {
+  if (!Array.isArray(rows)) return 0;
+  return rows.reduce((s, r) => s + (r.value ?? 0), 0);
+}
+
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+
+function ratioOverThreshold(i) {
+  return i.value / (i.threshold || 1);
+}

package/.agents/skills/vercel-optimize/lib/gates/external-api-slow.mjs

@@ -0,0 +1,55 @@
+// Volume floor pairs p75 with call_count so a single 5s cron/day doesn't fire the gate.
+const MIN_CALL_COUNT = 500;
+
+export const metadata = {
+  id: 'external_api_slow',
+  threshold: `p75Ms > 2000 AND callCount >= ${MIN_CALL_COUNT}`,
+  billingDimension: 'function-duration',
+  scope: 'route',
+  sourceCitation: 'vercel-optimize gate threshold',
+  description:
+    'External API hostnames with p75 latency above 2 seconds AND at least 500 calls in the window. External API latency is a primary driver of function duration cost when the upstream is on a hot path; a single slow stale call isn\'t worth recommending against.',
+};
+
+export function gate(signals) {
+  const apis = extractExternalApis(signals);
+  const calls = extractCallCounts(signals);
+  return apis
+    .map((a) => ({ ...a, callCount: calls.get(a.hostname) ?? 0 }))
+    .filter((a) => a.p75Ms > 2000 && a.callCount >= MIN_CALL_COUNT)
+    .map((a) => ({
+      kind: metadata.id,
+      scope: 'route',
+      route: null,
+      files: [],
+      hostname: a.hostname,
+      // Weight by latency × call volume so 100k-call/2.1s outranks 1k-call/8s.
+      priority: Math.round((a.p75Ms * a.callCount) / 1000),
+      confidence: 0.88,
+      o11ySignal: `host=${a.hostname},p75=${a.p75Ms}ms,calls=${a.callCount}`,
+      reason: 'slow external dependency on hot path',
+      question: `Which routes call ${a.hostname} (p75=${a.p75Ms}ms across ${a.callCount} calls), and can the call be parallelized, cached, or moved off the critical path?`,
+      evidence: { metric: 'externalApiP75', hostname: a.hostname, p75Ms: a.p75Ms, callCount: a.callCount },
+    }));
+}
+
+function extractExternalApis(signals) {
+  const m = signals.metrics?.externalApiP75;
+  if (!m?.ok && !Array.isArray(m?.rows)) return [];
+  return (m?.rows ?? [])
+    .map((r) => ({
+      hostname: r.origin_hostname,
+      p75Ms: Math.round(r.value ?? 0),
+    }))
+    .filter((a) => a.hostname);
+}
+
+function extractCallCounts(signals) {
+  const m = signals.metrics?.externalApiCount;
+  const out = new Map();
+  if (!m) return out;
+  for (const r of m.rows ?? []) {
+    if (r?.origin_hostname) out.set(r.origin_hostname, r.value ?? 0);
+  }
+  return out;
+}

package/.agents/skills/vercel-optimize/lib/gates/hard-gates.mjs

@@ -0,0 +1,73 @@
+import { canonicalizeRoute } from '../route-normalize.mjs';
+
+export const FLAGS_ENDPOINT = '/.well-known/vercel/flags';
+export const VERCEL_FLAGS_PACKAGES = [
+  '@vercel/flags',
+  '@vercel/flags/next',
+  '@vercel/flags/sveltekit',
+  '@vercel/flags/nuxt',
+];
+export const WORKFLOW_ENDPOINT_PREFIXES = [
+  '/.well-known/workflow',
+  '/api/.well-known/workflow',
+];
+
+export function applyHardGates(candidates, signals = {}) {
+  const allowed = [];
+  const gated = [];
+  for (const candidate of candidates) {
+    if (isFlagsEndpointCandidate(candidate)) {
+      gated.push({
+        ...candidate,
+        gatedReason: flagsEndpointReason(signals),
+      });
+      continue;
+    }
+    if (isWorkflowRuntimeEndpointCandidate(candidate)) {
+      gated.push({
+        ...candidate,
+        gatedReason: workflowEndpointReason(signals),
+      });
+      continue;
+    }
+    allowed.push(candidate);
+  }
+  return { allowed, gated };
+}
+
+export function isFlagsEndpointCandidate(candidate) {
+  if (!candidate || candidate.scope === 'account') return false;
+  const route = normalizeRoute(candidate.route);
+  return route === FLAGS_ENDPOINT;
+}
+
+export function isWorkflowRuntimeEndpointCandidate(candidate) {
+  if (!candidate || candidate.scope === 'account') return false;
+  const route = normalizeRoute(candidate.route);
+  if (!route) return false;
+  return WORKFLOW_ENDPOINT_PREFIXES.some((prefix) => (
+    route === prefix || route.startsWith(`${prefix}/`)
+  ));
+}
+
+function normalizeRoute(route) {
+  if (typeof route !== 'string') return null;
+  const normalized = canonicalizeRoute(route).replace(/\/+$/, '');
+  return normalized === '' ? '/' : normalized;
+}
+
+function flagsEndpointReason(signals) {
+  const packages = signals.stack?.vercelFlagsPackages;
+  if (Array.isArray(packages) && packages.length > 0) {
+    return `hardGated: ${FLAGS_ENDPOINT} is the Vercel Flags endpoint (${packages.join(', ')} detected), not an optimization target`;
+  }
+  return `hardGated: ${FLAGS_ENDPOINT} is the Vercel Flags endpoint, not an optimization target`;
+}
+
+function workflowEndpointReason(signals) {
+  const packages = signals.stack?.workflowPackages;
+  if (Array.isArray(packages) && packages.length > 0) {
+    return `hardGated: Vercel Workflow runtime endpoint (${packages.join(', ')} detected); long-running step/flow requests are expected orchestration, not an app-route optimization target`;
+  }
+  return 'hardGated: Vercel Workflow runtime endpoint; long-running step/flow requests are expected orchestration, not an app-route optimization target';
+}

package/.agents/skills/vercel-optimize/lib/gates/index.mjs

@@ -0,0 +1,45 @@
+import * as uncachedRoute from './uncached-route.mjs';
+import * as slowRoute from './slow-route.mjs';
+import * as routeErrors from './route-errors.mjs';
+import * as coldStart from './cold-start.mjs';
+import * as isrOverrevalidation from './isr-overrevalidation.mjs';
+import * as cwvPoor from './cwv-poor.mjs';
+import * as platformFluidCompute from './platform-fluid-compute.mjs';
+import * as platformBotProtection from './platform-bot-protection.mjs';
+import * as middlewareHeavy from './middleware-heavy.mjs';
+import * as externalApiSlow from './external-api-slow.mjs';
+import * as scannerDriven from './scanner-driven.mjs';
+import * as observabilityEventsAttribution from './observability-events-attribution.mjs';
+import * as usageSpikeTriage from './usage-spike-triage.mjs';
+import * as buildMinutesFanout from './build-minutes-fanout.mjs';
+import * as regionMisconfig from './region-misconfig.mjs';
+
+// Intentionally NOT registered:
+//   - `oversized_memory`: Fluid Compute floor is 2GB; per-route memory right-sizing isn't a customer lever.
+//   - `deploy_regression`: overlaps Vercel Agent Investigations; `vercel inspect` 404s across teams. slow_route deep-dive already carries per-deployment p95 trend.
+export const gates = [
+  uncachedRoute,
+  slowRoute,
+  routeErrors,
+  coldStart,
+  isrOverrevalidation,
+  cwvPoor,
+  externalApiSlow,
+  scannerDriven,
+  // Account-scoped last so platform-scoped sort doesn't dilute code-scoped priority ordering during budget application.
+  platformFluidCompute,
+  platformBotProtection,
+  middlewareHeavy,
+  observabilityEventsAttribution,
+  usageSpikeTriage,
+  buildMinutesFanout,
+  regionMisconfig,
+];
+
+// Overridable via `--max-candidates N` or `VERCEL_OPTIMIZE_MAX_CANDIDATES` (accepts `all`).
+// `MAX_CODE_CANDIDATES` is a back-compat alias for tests importing the old name.
+export const DEFAULT_MAX_CODE_CANDIDATES = 6;
+export const MAX_CODE_CANDIDATES = DEFAULT_MAX_CODE_CANDIDATES;
+
+// Bump on any threshold change so report + iteration baselines can detect gate-logic drift.
+export const GATE_VERSION = '1.8.0';

package/.agents/skills/vercel-optimize/lib/gates/isr-overrevalidation.mjs

@@ -0,0 +1,62 @@
+// ISR writes re-execute the page render. A w/r ratio above 0.5 means writes are
+// happening at least once for every two reads — high enough for the default
+// audit to spend investigation budget. writes>100 avoids flapping on quiet routes.
+export const metadata = {
+  id: 'isr_overrevalidation',
+  threshold: 'writes/reads > 0.5 AND writes > 100',
+  billingDimension: 'isr',
+  scope: 'route',
+  sourceCitation: 'https://vercel.com/docs/incremental-static-regeneration',
+  description:
+    'ISR routes with > 1 write per 2 reads. The revalidate interval is too aggressive relative to read traffic — many reads pay to regenerate. Investigate whether the page can tolerate a longer revalidate window or on-demand revalidation via revalidateTag.',
+};
+
+export function gate(signals) {
+  const rows = extractRows(signals);
+  return rows
+    .filter((r) => r.writes > 100 && r.reads > 0 && r.writes / r.reads > 0.5)
+    .map((r) => {
+      const ratio = r.writes / r.reads;
+      return {
+        kind: metadata.id,
+        scope: 'route',
+        route: r.route,
+        files: [],
+        priority: Math.round(r.writes),
+        confidence: 0.88,
+        o11ySignal: `writes=${r.writes},reads=${r.reads},w/r=${ratio.toFixed(2)}`,
+        reason: 'ISR revalidating faster than read traffic justifies',
+        question: `On ${r.route}, ${r.writes} ISR writes against ${r.reads} reads (${(ratio * 100).toFixed(0)} writes per 100 reads) — what is the current revalidate interval and can it be lengthened or switched to on-demand?`,
+        evidence: {
+          metric: 'isrWritesByRoute',
+          route: r.route,
+          writes: r.writes,
+          reads: r.reads,
+          ratio,
+        },
+      };
+    });
+}
+
+function extractRows(signals) {
+  const writes = signals.metrics?.isrWritesByRoute?.rows ?? [];
+  const reads = signals.metrics?.isrReadsByRoute?.rows ?? [];
+
+  const writeByRoute = new Map();
+  for (const r of writes) {
+    if (!r.route) continue;
+    writeByRoute.set(r.route, (writeByRoute.get(r.route) ?? 0) + (r.value ?? 0));
+  }
+  const readByRoute = new Map();
+  for (const r of reads) {
+    if (!r.route) continue;
+    readByRoute.set(r.route, (readByRoute.get(r.route) ?? 0) + (r.value ?? 0));
+  }
+
+  const routes = new Set([...writeByRoute.keys(), ...readByRoute.keys()]);
+  return [...routes].map((route) => ({
+    route,
+    writes: writeByRoute.get(route) ?? 0,
+    reads: readByRoute.get(route) ?? 0,
+  }));
+}

package/.agents/skills/vercel-optimize/lib/gates/middleware-heavy.mjs

@@ -0,0 +1,51 @@
+// Middleware runs in front of every matching request and is billed as edge invocations.
+// If >50% of traffic hits middleware, the matcher is probably broader than necessary.
+export const metadata = {
+  id: 'middleware_heavy',
+  threshold: 'middlewareInv/totalInv > 0.5 AND middlewareInv > 1000',
+  billingDimension: 'edge-requests',
+  scope: 'account',
+  sourceCitation: 'https://nextjs.org/docs/app/building-your-application/routing/middleware',
+  description:
+    'Middleware invocations cover > 50% of total requests at non-trivial volume. The matcher is probably broader than necessary; narrow it to the paths that actually need auth/rewrites/headers.',
+};
+
+export function gate(signals) {
+  const middlewareInv = sumRows(signals.metrics?.middlewareCount?.rows);
+  if (middlewareInv < 1000) return [];
+
+  const totalInv = sumRows(signals.metrics?.requestsByRouteCache?.rows);
+  if (totalInv === 0) return [];
+
+  const ratio = middlewareInv / totalInv;
+  if (ratio <= 0.5) return [];
+
+  const top = [...(signals.metrics?.middlewareCount?.rows ?? [])]
+    .filter((r) => r.request_path)
+    .sort((a, b) => (b.value ?? 0) - (a.value ?? 0))
+    .slice(0, 5)
+    .map((r) => ({ request_path: r.request_path, count: r.value ?? 0 }));
+
+  return [{
+    kind: metadata.id,
+    scope: 'account',
+    files: [],
+    priority: Math.round(middlewareInv / 1000),
+    confidence: 0.84,
+    o11ySignal: `middleware_inv=${middlewareInv},total_req=${totalInv},ratio=${(ratio * 100).toFixed(0)}%`,
+    reason: 'middleware ran on more than half of all requests',
+    question: `Middleware invocations (${middlewareInv}) are ${(ratio * 100).toFixed(0)}% of all requests (${totalInv}). Which paths in middleware.ts require interception, and can the matcher be narrowed to exclude static assets, images, and routes that do not need rewriting?`,
+    evidence: {
+      metric: 'middlewareCount',
+      middlewareInv,
+      totalInv,
+      ratio,
+      topPaths: top,
+    },
+  }];
+}
+
+function sumRows(rows) {
+  if (!Array.isArray(rows)) return 0;
+  return rows.reduce((s, r) => s + (r.value ?? 0), 0);
+}

package/.agents/skills/vercel-optimize/lib/gates/observability-events-attribution.mjs

@@ -0,0 +1,56 @@
+// Observability Events is the metered SKU under Observability Plus.
+// Threshold at >20% surfaces material spend; >30% is the critical band.
+// Drivers correlate with low cache hit rate, high middleware invocation, and high custom-span cardinality.
+export const metadata = {
+  id: 'observability_events_attribution',
+  threshold: 'observabilityEventsShare > 0.20 (critical at > 0.30)',
+  billingDimension: 'observability-events',
+  scope: 'account',
+  sourceCitation: 'vercel-optimize gate threshold',
+  description:
+    'Observability Events line item exceeds 20% of total billed cost. High share usually traces to low cache hit rate, middleware-heavy traffic, or unconstrained custom-span cardinality. No sampling lever exists for Observability Plus; reduce upstream invocations instead.',
+};
+
+const EVENTS_RE = /^Observability Events$/i;
+
+export function gate(signals) {
+  const services = signals?.usage?.services;
+  if (!Array.isArray(services) || services.length === 0) return [];
+
+  const total = sumBilled(services);
+  if (total <= 0) return [];
+
+  const eventsBilled = services
+    .filter((s) => EVENTS_RE.test(String(s?.name ?? '')))
+    .reduce((acc, s) => acc + Number(s.billedCost ?? s.cost ?? 0), 0);
+  if (eventsBilled <= 0) return [];
+
+  const share = eventsBilled / total;
+  if (share <= 0.20) return [];
+
+  const critical = share > 0.30;
+
+  return [{
+    kind: metadata.id,
+    scope: 'account',
+    files: [],
+    priority: critical ? 70 : 55,
+    confidence: 0.82,
+    o11ySignal: `observability_events_share=${(share * 100).toFixed(0)}%`,
+    reason: critical
+      ? 'observability events exceed 30% of total billed cost'
+      : 'observability events exceed 20% of total billed cost',
+    question: `Observability Events are ${(share * 100).toFixed(0)}% of the bill. Which routes drive event volume — low-cache-hit traffic, broad middleware invocation, or high custom-span cardinality — and can event volume be reduced upstream of the meter?`,
+    evidence: {
+      metric: 'usage.services',
+      eventsBilled,
+      totalBilled: total,
+      observabilityEventsShare: share,
+      critical,
+    },
+  }];
+}
+
+function sumBilled(services) {
+  return services.reduce((acc, s) => acc + Number(s.billedCost ?? s.cost ?? 0), 0);
+}