Setting the file. One moment.
Reconcile Candidates · Vercel Optimize · vercel-labs/agent-skills · Skills Docs
Back to the top of the page — line 256
This file
Number 7.115
Position 115 of 155
Type JavaScript
Size 16 KB
Lines 372 lib/ reconcile-candidates.mjs
JavaScript · 372 lines · 16 KB
11 const ROUTE_ERROR_CONFIRMATION_RATIO = 0.1 ;
12 const UNCACHED_HEALTHY_HIT_RATE = 0.9 ;
13 const UNCACHED_MIN_GET_SHARE = 0.2 ;
14 const ISR_WRITE_FLOOR = 100 ;
15 const ISR_WRITE_READ_RATIO_THRESHOLD = 0.5 ;
16
17 const SCANNER_ONLY_KINDS = new Set ([
18 'cache_header_gap' ,
19 'image_optimization' ,
20 'rendering_candidate' ,
21 ]);
22
23 export function reconcileInvestigation ( investigation , { gate = null } = {}) {
24 if ( ! investigation || typeof investigation !== 'object' ) {
25 throw new TypeError ( 'reconcileInvestigation investigation must be an object' );
26 }
27
28 const preResolvedRecords = [];
29 const reconciliation = {
30 droppedBeforeInvestigation: 0 ,
31 reasons: {},
32 };
33
34 const reconcilePool = ( pool , group ) => {
35 if ( ! Array. isArray (pool)) return [];
36 const kept = [];
37 for ( let i = 0 ; i < pool. length ; i ++ ) {
38 const candidate = pool[i];
39 const decision = reconcileCandidate (candidate, { group, index: i, gate });
40 if (decision.keep) {
41 kept. push (candidate);
42 continue ;
43 }
44 reconciliation.droppedBeforeInvestigation ++ ;
45 reconciliation.reasons[decision.reasonCode] = (reconciliation.reasons[decision.reasonCode] ?? 0 ) + 1 ;
46 preResolvedRecords. push (decision.record);
47 }
48 return kept;
49 };
50
51 const priorPreResolved = Array. isArray (investigation.preResolvedRecords)
52 ? investigation.preResolvedRecords
53 : [];
54
55 return {
56 ... investigation,
57 toLaunch: reconcilePool (investigation.toLaunch, 'toLaunch' ),
58 platform: reconcilePool (investigation.platform, 'platform' ),
59 preResolvedRecords: [ ... priorPreResolved, ... preResolvedRecords],
60 reconciliation: {
61 ... (investigation.reconciliation ?? {}),
62 ... reconciliation,
63 },
64 };
65 }
66
67 export function reconcileCandidate ( candidate , ctx = {}) {
68 if ( ! candidate || typeof candidate !== 'object' ) return { keep: true };
69
70 const scannerOnly = scannerOnlyDecision (candidate, ctx);
71 if (scannerOnly) return scannerOnly;
72
73 if (candidate.kind === 'slow_route' ) {
74 const errorDecision = slowRouteErrorDecision (candidate, ctx);
75 if (errorDecision) return errorDecision;
76
77 const mismatchDecision = slowRouteMetricMismatchDecision (candidate, ctx);
78 if (mismatchDecision) return mismatchDecision;
79
80 const regressionDecision = deploymentRegressionDecision (candidate, ctx);
81 if (regressionDecision) return regressionDecision;
82 }
83
84 if (candidate.kind === 'route_errors' ) {
85 const mismatchDecision = routeErrorsMetricMismatchDecision (candidate, ctx);
86 if (mismatchDecision) return mismatchDecision;
87 }
88
89 if (candidate.kind === 'uncached_route' ) {
90 const cacheDecision = uncachedRouteCacheDecision (candidate, ctx);
91 if (cacheDecision) return cacheDecision;
92 const methodDecision = uncachedRouteMethodDecision (candidate, ctx);
93 if (methodDecision) return methodDecision;
94 }
95
96 if (candidate.kind === 'isr_overrevalidation' ) {
97 const isrDecision = isrOverrevalidationDecision (candidate, ctx);
98 if (isrDecision) return isrDecision;
99 }
100
101 return { keep: true };
102 }
103
104 function scannerOnlyDecision ( candidate , ctx ) {
105 if ( ! SCANNER_ONLY_KINDS . has (candidate.kind)) return null ;
106 if (candidate.o11ySignal !== 'scanner-only' ) return null ;
107 return dropWithObservation (candidate, ctx, {
108 reasonCode: 'scanner_only_no_metric' ,
109 reason: 'Static scanner found a possible optimization, but no Vercel metric tied traffic or cost to this target.' ,
110 observation: {
111 kind: 'scanner_only_no_metric' ,
112 summary: `${ targetLabel ( candidate ) } has a static scanner finding, but no route-level Vercel metric signal.` ,
113 evidence: `gate signal=${ candidate . o11ySignal }` ,
114 suggestedAction: 'Do not ship a recommendation from this finding unless a Vercel metric shows material traffic, cost, or latency for the same target.' ,
115 },
116 });
117 }
118
119 function slowRouteMetricMismatchDecision ( candidate , ctx ) {
120 const p95 = numberAt (candidate, [ 'evidence' , 'deepDive' , 'latency' , 'p95' ]);
121 if (p95 == null ) return null ;
122 if (p95 >= SLOW_ROUTE_P95_THRESHOLD_MS ) return null ;
123 return dropWithObservation (candidate, ctx, {
124 reasonCode: 'metric_mismatch' ,
125 reason: `Deep-dive p95 (${ formatMs ( p95 ) }) is below the slow-route threshold, so the broad gate did not survive follow-up verification.` ,
126 observation: {
127 kind: 'metric_mismatch' ,
128 summary: `${ targetLabel ( candidate ) } was flagged as slow in the broad pass, but follow-up p95 is below threshold.` ,
129 evidence: `${ candidate . o11ySignal ?? 'gate signal unavailable'}; deepDive.latency.p95=${ formatMs ( p95 ) }` ,
130 suggestedAction: 'Skip code investigation for this run. Re-check only if the broad and follow-up windows converge in a later run.' ,
131 },
132 });
133 }
134
135 function slowRouteErrorDecision ( candidate , ctx ) {
136 const rows = arrayAt (candidate, [ 'evidence' , 'deepDive' , 'statusDistribution' ]);
137 if (rows. length === 0 ) return null ;
138 let total = 0 ;
139 let errors = 0 ;
140 for ( const row of rows) {
141 const value = numberValue (row?.value);
142 if (value == null ) continue ;
143 total += value;
144 if ( / ^ 5/ . test ( String (row.http_status ?? '' ))) errors += value;
145 }
146 if (total <= 0 ) return null ;
147 const rate = errors / total;
148 if (rate <= ERROR_RATE_DOMINATES_THRESHOLD ) return null ;
149 return dropWithObservation (candidate, ctx, {
150 reasonCode: 'error_storm' ,
151 reason: `Function-level 5xx responses dominate this route (${ formatPct ( rate ) }), so this is a reliability finding rather than a slow-route finding.` ,
152 observation: {
153 kind: 'error_storm' ,
154 summary: `${ targetLabel ( candidate ) } latency is dominated by function-level 5xx responses.` ,
155 evidence: `deepDive.statusDistribution: ${ formatInteger ( errors ) } 5xx of ${ formatInteger ( total ) } function invocations (${ formatPct ( rate ) })` ,
156 suggestedAction: 'Investigate as route_errors with runtime logs and error classification before making performance recommendations.' ,
157 },
158 });
159 }
160
161 function deploymentRegressionDecision ( candidate , ctx ) {
162 const rows = arrayAt (candidate, [ 'evidence' , 'deepDive' , 'perDeployment' ])
163 . filter (( row ) => row && typeof row.deployment_id === 'string' && numberValue (row.value) != null )
164 . map (( row ) => ({ deploymentId: row.deployment_id, p95: numberValue (row.value) }))
165 . sort (( a , b ) => b.p95 - a.p95);
166
167 if (rows. length < 3 ) return null ;
168 const [ worst , second ] = rows;
169 if ( ! worst || ! second || worst.p95 < DEPLOYMENT_OUTLIER_MIN_MS ) return null ;
170 if (worst.p95 < second.p95 * DEPLOYMENT_OUTLIER_MULTIPLE ) return null ;
171
172 return dropWithObservation (candidate, ctx, {
173 reasonCode: 'deployment_regression' ,
174 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.` ,
175 observation: {
176 kind: 'deployment_regression' ,
177 summary: `${ targetLabel ( candidate ) } p95 is concentrated in one deployment.` ,
178 evidence: `${ worst . deploymentId } p95=${ formatMs ( worst . p95 ) } vs next highest ${ second . deploymentId } p95=${ formatMs ( second . p95 ) }` ,
179 suggestedAction: 'Compare the outlier deployment against the prior deployment and inspect runtime logs before recommending a code-level performance change.' ,
180 },
181 });
182 }
183
184 function routeErrorsMetricMismatchDecision ( candidate , ctx ) {
185 const broadErrors = numberAt (candidate, [ 'evidence' , 'count' ]) ?? parseSignalNumber (candidate.o11ySignal, 'errs' );
186 if (broadErrors == null || broadErrors < 1000 ) return null ;
187 const rows = [
188 ... arrayAt (candidate, [ 'evidence' , 'deepDive' , 'errorStatusPattern' ]),
189 ... arrayAt (candidate, [ 'evidence' , 'deepDive' , 'errorsByDeployment' ]),
190 ];
191 if (rows. length === 0 ) return null ;
192 let confirmed5xx = 0 ;
193 for ( const row of rows) {
194 if ( ! / ^ 5 \d\d $ / . test ( String (row?.http_status ?? '' ))) continue ;
195 const value = numberValue (row?.value);
196 if (value != null ) confirmed5xx += value;
197 }
198 // errorStatusPattern and errorsByDeployment can both be present; avoid
199 // double-count inflation by taking the lower non-zero route-level view when available.
200 const statusRows = arrayAt (candidate, [ 'evidence' , 'deepDive' , 'errorStatusPattern' ]);
201 const status5xx = sumRows (statusRows, ( row ) => / ^ 5 \d\d $ / . test ( String (row?.http_status ?? '' )));
202 if (status5xx > 0 ) confirmed5xx = status5xx;
203 if (confirmed5xx >= broadErrors * ROUTE_ERROR_CONFIRMATION_RATIO ) return null ;
204 return dropWithObservation (candidate, ctx, {
205 reasonCode: 'metric_mismatch' ,
206 reason: `Deep-dive 5xx volume (${ formatInteger ( confirmed5xx ) }) does not confirm the broad route_errors gate (${ formatInteger ( broadErrors ) }).` ,
207 observation: {
208 kind: 'metric_mismatch' ,
209 summary: `${ targetLabel ( candidate ) } was flagged for 5xx errors, but follow-up status data did not confirm the volume.` ,
210 evidence: `${ candidate . o11ySignal ?? 'gate signal unavailable'}; deepDive.confirmed5xx=${ formatInteger ( confirmed5xx ) }` ,
211 suggestedAction: 'Skip code recommendations from this run. Re-run with refreshed status metrics or runtime logs if the route is still suspected.' ,
212 },
213 });
214 }
215
216 function uncachedRouteCacheDecision ( candidate , ctx ) {
217 const rows = arrayAt (candidate, [ 'evidence' , 'deepDive' , 'cacheBreakdown' ]);
218 if (rows. length === 0 ) return null ;
219 const total = sumRows (rows);
220 if (total <= 0 ) return null ;
221 const hits = sumRows (rows, ( row ) => [ 'HIT' , 'STALE' ]. includes ( String (row?.cache_result ?? '' ). toUpperCase ()));
222 const hitRate = hits / total;
223 if (hitRate < UNCACHED_HEALTHY_HIT_RATE ) return null ;
224 return dropWithObservation (candidate, ctx, {
225 reasonCode: 'metric_mismatch' ,
226 reason: `Deep-dive cache hit rate (${ formatPct ( hitRate ) }) is already healthy, so the uncached-route gate did not survive follow-up verification.` ,
227 observation: {
228 kind: 'metric_mismatch' ,
229 summary: `${ targetLabel ( candidate ) } was flagged as low-cache, but follow-up cache data is already healthy.` ,
230 evidence: `${ candidate . o11ySignal ?? 'gate signal unavailable'}; deepDive.cacheHitRate=${ formatPct ( hitRate ) }` ,
231 suggestedAction: 'Skip cache recommendations for this candidate unless a later run shows sustained MISS/BYPASS traffic.' ,
232 },
233 });
234 }
235
236 function uncachedRouteMethodDecision ( candidate , ctx ) {
237 const rows = arrayAt (candidate, [ 'evidence' , 'deepDive' , 'methodDistribution' ]);
238 if (rows. length === 0 ) return null ;
239 const total = sumRows (rows);
240 if (total <= 0 ) return null ;
241 const gets = sumRows (rows, ( row ) => String (row?.request_method ?? '' ). toUpperCase () === 'GET' );
242 const getShare = gets / total;
243 if (getShare >= UNCACHED_MIN_GET_SHARE ) return null ;
244 return dropWithObservation (candidate, ctx, {
245 reasonCode: 'protocol_mismatch' ,
246 reason: `Deep-dive GET share (${ formatPct ( getShare ) }) is below the cacheable-route floor, so this is not a good shared-cache candidate.` ,
247 observation: {
248 kind: 'protocol_mismatch' ,
249 summary: `${ targetLabel ( candidate ) } is not GET-heavy enough for a shared-cache recommendation.` ,
250 evidence: `${ candidate . o11ySignal ?? 'gate signal unavailable'}; deepDive.getShare=${ formatPct ( getShare ) }` ,
251 suggestedAction: 'Do not recommend CDN caching for this route from aggregate traffic alone. Investigate write-path cost only if another metric gate fires.' ,
252 },
253 });
254 }
255
256 function isrOverrevalidationDecision ( candidate , ctx ) {
257 const writeRows = arrayAt (candidate, [ 'evidence' , 'deepDive' , 'writePattern' ]);
258 const readRows = arrayAt (candidate, [ 'evidence' , 'deepDive' , 'readPattern' ]);
259 if (writeRows. length === 0 && readRows. length === 0 ) return null ;
260 const writes = sumRows (writeRows);
261 const reads = sumRows (readRows);
262 const ratio = reads > 0 ? writes / reads : (writes > 0 ? Infinity : 0 );
263 if (reads <= 0 ) {
264 return dropWithObservation (candidate, ctx, {
265 reasonCode: 'metric_mismatch' ,
266 reason: 'Deep-dive ISR read units were not present, so the write/read over-revalidation signal was not confirmed.' ,
267 observation: {
268 kind: 'metric_mismatch' ,
269 summary: `${ targetLabel ( candidate ) } was flagged for ISR over-revalidation, but follow-up ISR read data was empty.` ,
270 evidence: `${ candidate . o11ySignal ?? 'gate signal unavailable'}; deepDive.isrWrites=${ formatInteger ( writes ) }; deepDive.isrReads=${ formatInteger ( reads ) }` ,
271 suggestedAction: 'Skip ISR recommendations for this candidate unless a later run confirms both ISR writes and reads for the same route.' ,
272 },
273 });
274 }
275 if (writes >= ISR_WRITE_FLOOR && ratio > ISR_WRITE_READ_RATIO_THRESHOLD ) return null ;
276 const ratioLabel = ratio === Infinity ? 'Infinity' : ratio. toFixed ( 2 );
277 return dropWithObservation (candidate, ctx, {
278 reasonCode: 'metric_mismatch' ,
279 reason: `Deep-dive ISR writes per read (${ ratioLabel }) no longer crosses the over-revalidation threshold.` ,
280 observation: {
281 kind: 'metric_mismatch' ,
282 summary: `${ targetLabel ( candidate ) } was flagged for ISR over-revalidation, but follow-up ISR data did not confirm it.` ,
283 evidence: `${ candidate . o11ySignal ?? 'gate signal unavailable'}; deepDive.isrWrites=${ formatInteger ( writes ) }; deepDive.isrReads=${ formatInteger ( reads ) }; ratio=${ ratioLabel }` ,
284 suggestedAction: 'Skip ISR recommendations for this candidate unless a later run shows sustained write amplification.' ,
285 },
286 });
287 }
288
289 function dropWithObservation ( candidate , ctx , { reasonCode , reason , observation }) {
290 return {
291 keep: false ,
292 reasonCode,
293 record: {
294 abstain: true ,
295 candidateRef: candidateRefFor (candidate),
296 reason,
297 observation,
298 reconciliation: {
299 droppedBeforeInvestigation: true ,
300 reasonCode,
301 group: ctx.group ?? null ,
302 index: Number. isInteger (ctx.index) ? ctx.index : null ,
303 },
304 },
305 };
306 }
307
308 export function candidateRefFor ( candidate , files = candidate?.files) {
309 if ( ! candidate || typeof candidate !== 'object' ) return 'unknown:<unknown>' ;
310 const target = candidate.route
311 ?? candidate.hostname
312 ?? (Array. isArray (files) && files. length > 0 ? `<account>#${ files [ 0 ] }` : '<account>' );
313 return `${ candidate . kind ?? 'unknown'}:${ target }` ;
314 }
315
316 function targetLabel ( candidate ) {
317 return candidate.route ?? candidate.hostname ?? candidate.files?.[ 0 ] ?? 'account-level target' ;
318 }
319
320 function arrayAt ( obj , path ) {
321 let cur = obj;
322 for ( const p of path) cur = cur?.[p];
323 return Array. isArray (cur) ? cur : [];
324 }
325
326 function numberAt ( obj , path ) {
327 let cur = obj;
328 for ( const p of path) cur = cur?.[p];
329 return numberValue (cur);
330 }
331
332 function numberValue ( value ) {
333 return typeof value === 'number' && Number. isFinite (value) ? value : null ;
334 }
335
336 function sumRows ( rows , predicate = () => true ) {
337 if ( ! Array. isArray (rows)) return 0 ;
338 let total = 0 ;
339 for ( const row of rows) {
340 if ( ! predicate (row)) continue ;
341 const value = numberValue (row?.value);
342 if (value != null ) total += value;
343 }
344 return total;
345 }
346
347 function parseSignalNumber ( signal , key ) {
348 if ( typeof signal !== 'string' ) return null ;
349 const re = new RegExp ( `(?:^|,)${ key }=([ \\ d,.]+)` );
350 const m = signal. match (re);
351 if ( ! m) return null ;
352 const n = Number (m[ 1 ]. replace ( /,/ g , '' ));
353 return Number. isFinite (n) ? n : null ;
354 }
355
356 function formatMs ( value ) {
357 const n = numberValue (value);
358 if (n == null ) return String (value);
359 return `${ Math . round ( n ) }ms` ;
360 }
361
362 function formatPct ( value ) {
363 const n = numberValue (value);
364 if (n == null ) return String (value);
365 return `${ ( n * 100 ). toFixed ( n >= 0.1 ? 1 : 2 ) }%` ;
366 }
367
368 function formatInteger ( value ) {
369 const n = numberValue (value);
370 if (n == null ) return String (value);
371 return Math. round (n). toLocaleString ( 'en-US' );
372 }