opencode-skills-collection 3.0.34 → 3.0.36

package/bundled-skills/vercel-optimize/lib/reconcile-candidates.mjs

@@ -0,0 +1,372 @@
+// Deterministic post-deep-dive reconciliation.
+//
+// Runs after metrics deep-dive and before investigation briefs. Its job is to
+// prevent weak candidates from consuming investigator budget when the
+// follow-up metric evidence already disproves or reframes the gate hypothesis.
+
+const SLOW_ROUTE_P95_THRESHOLD_MS = 500;
+const ERROR_RATE_DOMINATES_THRESHOLD = 0.5;
+const DEPLOYMENT_OUTLIER_MULTIPLE = 2;
+const DEPLOYMENT_OUTLIER_MIN_MS = 1000;
+const ROUTE_ERROR_CONFIRMATION_RATIO = 0.1;
+const UNCACHED_HEALTHY_HIT_RATE = 0.9;
+const UNCACHED_MIN_GET_SHARE = 0.2;
+const ISR_WRITE_FLOOR = 100;
+const ISR_WRITE_READ_RATIO_THRESHOLD = 0.5;
+
+const SCANNER_ONLY_KINDS = new Set([
+  'cache_header_gap',
+  'image_optimization',
+  'rendering_candidate',
+]);
+
+export function reconcileInvestigation(investigation, { gate = null } = {}) {
+  if (!investigation || typeof investigation !== 'object') {
+    throw new TypeError('reconcileInvestigation investigation must be an object');
+  }
+
+  const preResolvedRecords = [];
+  const reconciliation = {
+    droppedBeforeInvestigation: 0,
+    reasons: {},
+  };
+
+  const reconcilePool = (pool, group) => {
+    if (!Array.isArray(pool)) return [];
+    const kept = [];
+    for (let i = 0; i < pool.length; i++) {
+      const candidate = pool[i];
+      const decision = reconcileCandidate(candidate, { group, index: i, gate });
+      if (decision.keep) {
+        kept.push(candidate);
+        continue;
+      }
+      reconciliation.droppedBeforeInvestigation++;
+      reconciliation.reasons[decision.reasonCode] = (reconciliation.reasons[decision.reasonCode] ?? 0) + 1;
+      preResolvedRecords.push(decision.record);
+    }
+    return kept;
+  };
+
+  const priorPreResolved = Array.isArray(investigation.preResolvedRecords)
+    ? investigation.preResolvedRecords
+    : [];
+
+  return {
+    ...investigation,
+    toLaunch: reconcilePool(investigation.toLaunch, 'toLaunch'),
+    platform: reconcilePool(investigation.platform, 'platform'),
+    preResolvedRecords: [...priorPreResolved, ...preResolvedRecords],
+    reconciliation: {
+      ...(investigation.reconciliation ?? {}),
+      ...reconciliation,
+    },
+  };
+}
+
+export function reconcileCandidate(candidate, ctx = {}) {
+  if (!candidate || typeof candidate !== 'object') return { keep: true };
+
+  const scannerOnly = scannerOnlyDecision(candidate, ctx);
+  if (scannerOnly) return scannerOnly;
+
+  if (candidate.kind === 'slow_route') {
+    const errorDecision = slowRouteErrorDecision(candidate, ctx);
+    if (errorDecision) return errorDecision;
+
+    const mismatchDecision = slowRouteMetricMismatchDecision(candidate, ctx);
+    if (mismatchDecision) return mismatchDecision;
+
+    const regressionDecision = deploymentRegressionDecision(candidate, ctx);
+    if (regressionDecision) return regressionDecision;
+  }
+
+  if (candidate.kind === 'route_errors') {
+    const mismatchDecision = routeErrorsMetricMismatchDecision(candidate, ctx);
+    if (mismatchDecision) return mismatchDecision;
+  }
+
+  if (candidate.kind === 'uncached_route') {
+    const cacheDecision = uncachedRouteCacheDecision(candidate, ctx);
+    if (cacheDecision) return cacheDecision;
+    const methodDecision = uncachedRouteMethodDecision(candidate, ctx);
+    if (methodDecision) return methodDecision;
+  }
+
+  if (candidate.kind === 'isr_overrevalidation') {
+    const isrDecision = isrOverrevalidationDecision(candidate, ctx);
+    if (isrDecision) return isrDecision;
+  }
+
+  return { keep: true };
+}
+
+function scannerOnlyDecision(candidate, ctx) {
+  if (!SCANNER_ONLY_KINDS.has(candidate.kind)) return null;
+  if (candidate.o11ySignal !== 'scanner-only') return null;
+  return dropWithObservation(candidate, ctx, {
+    reasonCode: 'scanner_only_no_metric',
+    reason: 'Static scanner found a possible optimization, but no Vercel metric tied traffic or cost to this target.',
+    observation: {
+      kind: 'scanner_only_no_metric',
+      summary: `${targetLabel(candidate)} has a static scanner finding, but no route-level Vercel metric signal.`,
+      evidence: `gate signal=${candidate.o11ySignal}`,
+      suggestedAction: 'Do not ship a recommendation from this finding unless a Vercel metric shows material traffic, cost, or latency for the same target.',
+    },
+  });
+}
+
+function slowRouteMetricMismatchDecision(candidate, ctx) {
+  const p95 = numberAt(candidate, ['evidence', 'deepDive', 'latency', 'p95']);
+  if (p95 == null) return null;
+  if (p95 >= SLOW_ROUTE_P95_THRESHOLD_MS) return null;
+  return dropWithObservation(candidate, ctx, {
+    reasonCode: 'metric_mismatch',
+    reason: `Deep-dive p95 (${formatMs(p95)}) is below the slow-route threshold, so the broad gate did not survive follow-up verification.`,
+    observation: {
+      kind: 'metric_mismatch',
+      summary: `${targetLabel(candidate)} was flagged as slow in the broad pass, but follow-up p95 is below threshold.`,
+      evidence: `${candidate.o11ySignal ?? 'gate signal unavailable'}; deepDive.latency.p95=${formatMs(p95)}`,
+      suggestedAction: 'Skip code investigation for this run. Re-check only if the broad and follow-up windows converge in a later run.',
+    },
+  });
+}
+
+function slowRouteErrorDecision(candidate, ctx) {
+  const rows = arrayAt(candidate, ['evidence', 'deepDive', 'statusDistribution']);
+  if (rows.length === 0) return null;
+  let total = 0;
+  let errors = 0;
+  for (const row of rows) {
+    const value = numberValue(row?.value);
+    if (value == null) continue;
+    total += value;
+    if (/^5/.test(String(row.http_status ?? ''))) errors += value;
+  }
+  if (total <= 0) return null;
+  const rate = errors / total;
+  if (rate <= ERROR_RATE_DOMINATES_THRESHOLD) return null;
+  return dropWithObservation(candidate, ctx, {
+    reasonCode: 'error_storm',
+    reason: `Function-level 5xx responses dominate this route (${formatPct(rate)}), so this is a reliability finding rather than a slow-route finding.`,
+    observation: {
+      kind: 'error_storm',
+      summary: `${targetLabel(candidate)} latency is dominated by function-level 5xx responses.`,
+      evidence: `deepDive.statusDistribution: ${formatInteger(errors)} 5xx of ${formatInteger(total)} function invocations (${formatPct(rate)})`,
+      suggestedAction: 'Investigate as route_errors with runtime logs and error classification before making performance recommendations.',
+    },
+  });
+}
+
+function deploymentRegressionDecision(candidate, ctx) {
+  const rows = arrayAt(candidate, ['evidence', 'deepDive', 'perDeployment'])
+    .filter((row) => row && typeof row.deployment_id === 'string' && numberValue(row.value) != null)
+    .map((row) => ({ deploymentId: row.deployment_id, p95: numberValue(row.value) }))
+    .sort((a, b) => b.p95 - a.p95);
+
+  if (rows.length < 3) return null;
+  const [worst, second] = rows;
+  if (!worst || !second || worst.p95 < DEPLOYMENT_OUTLIER_MIN_MS) return null;
+  if (worst.p95 < second.p95 * DEPLOYMENT_OUTLIER_MULTIPLE) return null;
+
+  return dropWithObservation(candidate, ctx, {
+    reasonCode: 'deployment_regression',
+    reason: `One deployment is a large latency outlier (${worst.deploymentId} at ${formatMs(worst.p95)}), so the next action is regression triage rather than generic code optimization.`,
+    observation: {
+      kind: 'deployment_regression',
+      summary: `${targetLabel(candidate)} p95 is concentrated in one deployment.`,
+      evidence: `${worst.deploymentId} p95=${formatMs(worst.p95)} vs next highest ${second.deploymentId} p95=${formatMs(second.p95)}`,
+      suggestedAction: 'Compare the outlier deployment against the prior deployment and inspect runtime logs before recommending a code-level performance change.',
+    },
+  });
+}
+
+function routeErrorsMetricMismatchDecision(candidate, ctx) {
+  const broadErrors = numberAt(candidate, ['evidence', 'count']) ?? parseSignalNumber(candidate.o11ySignal, 'errs');
+  if (broadErrors == null || broadErrors < 1000) return null;
+  const rows = [
+    ...arrayAt(candidate, ['evidence', 'deepDive', 'errorStatusPattern']),
+    ...arrayAt(candidate, ['evidence', 'deepDive', 'errorsByDeployment']),
+  ];
+  if (rows.length === 0) return null;
+  let confirmed5xx = 0;
+  for (const row of rows) {
+    if (!/^5\d\d$/.test(String(row?.http_status ?? ''))) continue;
+    const value = numberValue(row?.value);
+    if (value != null) confirmed5xx += value;
+  }
+  // errorStatusPattern and errorsByDeployment can both be present; avoid
+  // double-count inflation by taking the lower non-zero route-level view when available.
+  const statusRows = arrayAt(candidate, ['evidence', 'deepDive', 'errorStatusPattern']);
+  const status5xx = sumRows(statusRows, (row) => /^5\d\d$/.test(String(row?.http_status ?? '')));
+  if (status5xx > 0) confirmed5xx = status5xx;
+  if (confirmed5xx >= broadErrors * ROUTE_ERROR_CONFIRMATION_RATIO) return null;
+  return dropWithObservation(candidate, ctx, {
+    reasonCode: 'metric_mismatch',
+    reason: `Deep-dive 5xx volume (${formatInteger(confirmed5xx)}) does not confirm the broad route_errors gate (${formatInteger(broadErrors)}).`,
+    observation: {
+      kind: 'metric_mismatch',
+      summary: `${targetLabel(candidate)} was flagged for 5xx errors, but follow-up status data did not confirm the volume.`,
+      evidence: `${candidate.o11ySignal ?? 'gate signal unavailable'}; deepDive.confirmed5xx=${formatInteger(confirmed5xx)}`,
+      suggestedAction: 'Skip code recommendations from this run. Re-run with refreshed status metrics or runtime logs if the route is still suspected.',
+    },
+  });
+}
+
+function uncachedRouteCacheDecision(candidate, ctx) {
+  const rows = arrayAt(candidate, ['evidence', 'deepDive', 'cacheBreakdown']);
+  if (rows.length === 0) return null;
+  const total = sumRows(rows);
+  if (total <= 0) return null;
+  const hits = sumRows(rows, (row) => ['HIT', 'STALE'].includes(String(row?.cache_result ?? '').toUpperCase()));
+  const hitRate = hits / total;
+  if (hitRate < UNCACHED_HEALTHY_HIT_RATE) return null;
+  return dropWithObservation(candidate, ctx, {
+    reasonCode: 'metric_mismatch',
+    reason: `Deep-dive cache hit rate (${formatPct(hitRate)}) is already healthy, so the uncached-route gate did not survive follow-up verification.`,
+    observation: {
+      kind: 'metric_mismatch',
+      summary: `${targetLabel(candidate)} was flagged as low-cache, but follow-up cache data is already healthy.`,
+      evidence: `${candidate.o11ySignal ?? 'gate signal unavailable'}; deepDive.cacheHitRate=${formatPct(hitRate)}`,
+      suggestedAction: 'Skip cache recommendations for this candidate unless a later run shows sustained MISS/BYPASS traffic.',
+    },
+  });
+}
+
+function uncachedRouteMethodDecision(candidate, ctx) {
+  const rows = arrayAt(candidate, ['evidence', 'deepDive', 'methodDistribution']);
+  if (rows.length === 0) return null;
+  const total = sumRows(rows);
+  if (total <= 0) return null;
+  const gets = sumRows(rows, (row) => String(row?.request_method ?? '').toUpperCase() === 'GET');
+  const getShare = gets / total;
+  if (getShare >= UNCACHED_MIN_GET_SHARE) return null;
+  return dropWithObservation(candidate, ctx, {
+    reasonCode: 'protocol_mismatch',
+    reason: `Deep-dive GET share (${formatPct(getShare)}) is below the cacheable-route floor, so this is not a good shared-cache candidate.`,
+    observation: {
+      kind: 'protocol_mismatch',
+      summary: `${targetLabel(candidate)} is not GET-heavy enough for a shared-cache recommendation.`,
+      evidence: `${candidate.o11ySignal ?? 'gate signal unavailable'}; deepDive.getShare=${formatPct(getShare)}`,
+      suggestedAction: 'Do not recommend CDN caching for this route from aggregate traffic alone. Investigate write-path cost only if another metric gate fires.',
+    },
+  });
+}
+
+function isrOverrevalidationDecision(candidate, ctx) {
+  const writeRows = arrayAt(candidate, ['evidence', 'deepDive', 'writePattern']);
+  const readRows = arrayAt(candidate, ['evidence', 'deepDive', 'readPattern']);
+  if (writeRows.length === 0 && readRows.length === 0) return null;
+  const writes = sumRows(writeRows);
+  const reads = sumRows(readRows);
+  const ratio = reads > 0 ? writes / reads : (writes > 0 ? Infinity : 0);
+  if (reads <= 0) {
+    return dropWithObservation(candidate, ctx, {
+      reasonCode: 'metric_mismatch',
+      reason: 'Deep-dive ISR read units were not present, so the write/read over-revalidation signal was not confirmed.',
+      observation: {
+        kind: 'metric_mismatch',
+        summary: `${targetLabel(candidate)} was flagged for ISR over-revalidation, but follow-up ISR read data was empty.`,
+        evidence: `${candidate.o11ySignal ?? 'gate signal unavailable'}; deepDive.isrWrites=${formatInteger(writes)}; deepDive.isrReads=${formatInteger(reads)}`,
+        suggestedAction: 'Skip ISR recommendations for this candidate unless a later run confirms both ISR writes and reads for the same route.',
+      },
+    });
+  }
+  if (writes >= ISR_WRITE_FLOOR && ratio > ISR_WRITE_READ_RATIO_THRESHOLD) return null;
+  const ratioLabel = ratio === Infinity ? 'Infinity' : ratio.toFixed(2);
+  return dropWithObservation(candidate, ctx, {
+    reasonCode: 'metric_mismatch',
+    reason: `Deep-dive ISR writes per read (${ratioLabel}) no longer crosses the over-revalidation threshold.`,
+    observation: {
+      kind: 'metric_mismatch',
+      summary: `${targetLabel(candidate)} was flagged for ISR over-revalidation, but follow-up ISR data did not confirm it.`,
+      evidence: `${candidate.o11ySignal ?? 'gate signal unavailable'}; deepDive.isrWrites=${formatInteger(writes)}; deepDive.isrReads=${formatInteger(reads)}; ratio=${ratioLabel}`,
+      suggestedAction: 'Skip ISR recommendations for this candidate unless a later run shows sustained write amplification.',
+    },
+  });
+}
+
+function dropWithObservation(candidate, ctx, { reasonCode, reason, observation }) {
+  return {
+    keep: false,
+    reasonCode,
+    record: {
+      abstain: true,
+      candidateRef: candidateRefFor(candidate),
+      reason,
+      observation,
+      reconciliation: {
+        droppedBeforeInvestigation: true,
+        reasonCode,
+        group: ctx.group ?? null,
+        index: Number.isInteger(ctx.index) ? ctx.index : null,
+      },
+    },
+  };
+}
+
+export function candidateRefFor(candidate, files = candidate?.files) {
+  if (!candidate || typeof candidate !== 'object') return 'unknown:<unknown>';
+  const target = candidate.route
+    ?? candidate.hostname
+    ?? (Array.isArray(files) && files.length > 0 ? `<account>#${files[0]}` : '<account>');
+  return `${candidate.kind ?? 'unknown'}:${target}`;
+}
+
+function targetLabel(candidate) {
+  return candidate.route ?? candidate.hostname ?? candidate.files?.[0] ?? 'account-level target';
+}
+
+function arrayAt(obj, path) {
+  let cur = obj;
+  for (const p of path) cur = cur?.[p];
+  return Array.isArray(cur) ? cur : [];
+}
+
+function numberAt(obj, path) {
+  let cur = obj;
+  for (const p of path) cur = cur?.[p];
+  return numberValue(cur);
+}
+
+function numberValue(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function sumRows(rows, predicate = () => true) {
+  if (!Array.isArray(rows)) return 0;
+  let total = 0;
+  for (const row of rows) {
+    if (!predicate(row)) continue;
+    const value = numberValue(row?.value);
+    if (value != null) total += value;
+  }
+  return total;
+}
+
+function parseSignalNumber(signal, key) {
+  if (typeof signal !== 'string') return null;
+  const re = new RegExp(`(?:^|,)${key}=([\\d,.]+)`);
+  const m = signal.match(re);
+  if (!m) return null;
+  const n = Number(m[1].replace(/,/g, ''));
+  return Number.isFinite(n) ? n : null;
+}
+
+function formatMs(value) {
+  const n = numberValue(value);
+  if (n == null) return String(value);
+  return `${Math.round(n)}ms`;
+}
+
+function formatPct(value) {
+  const n = numberValue(value);
+  if (n == null) return String(value);
+  return `${(n * 100).toFixed(n >= 0.1 ? 1 : 2)}%`;
+}
+
+function formatInteger(value) {
+  const n = numberValue(value);
+  if (n == null) return String(value);
+  return Math.round(n).toLocaleString('en-US');
+}