Setting the file. One moment.
Observation Safety · Vercel Optimize · vercel-labs/agent-skills · Skills Docs
Back to the top of the page — line 129
This file
Number 7.112
Position 112 of 155
Type JavaScript
Size 9 KB
Lines 174 lib/ observation-safety.mjs
JavaScript · 174 lines · 9 KB
(observation, abstentions, signals);
6 if (unsafeReason) {
7 heldBack. push ({
8 candidateRef: observation?.candidateRef ?? null ,
9 reason: unsafeReason,
10 needsEvidence: true ,
11 });
12 } else {
13 safe. push (observation);
14 }
15 }
16 return { observations: safe, heldBackObservations: heldBack };
17 }
18
19 function unsupportedObservationReason ( observation , abstentions = [], signals = {}) {
20 if ( contradictsNoChangeReason (observation, abstentions)) {
21 return 'This observation repeated an action that another investigation rejected. Re-run with a single scoped candidate before applying it.' ;
22 }
23 if ( hasUnsupportedWafBotCategoryClaim (observation)) {
24 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.' ;
25 }
26 if ( hasUnsafeBotProtectionObservation (observation)) {
27 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.' ;
28 }
29 if ( hasStaleNextCacheApiObservation (observation, signals)) {
30 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.' ;
31 }
32 if ( hasUnsupportedFrameworkCausalClaim (observation)) {
33 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.' ;
34 }
35 if ( hasUnsupportedStaticGenerationClaim (observation)) {
36 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.' ;
37 }
38 if ( hasUnsupportedSourceAbsenceClaim (observation)) {
39 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.' ;
40 }
41 if ( hasUnsupportedCacheLifeCdnClaim (observation)) {
42 return 'This observation depended on an unsupported cacheLife-to-CDN claim. Re-run with production header evidence before applying it.' ;
43 }
44 if ( hasUnsupportedRuntimeRootCauseClaim (observation)) {
45 return 'This observation made a runtime root-cause claim that needs log, stack, or upstream response evidence before it can ship.' ;
46 }
47 if ( hasImplementationGradeObservationAction (observation)) {
48 return 'This observation described an implementation change that needs the ready-to-apply recommendation evidence bar before it can ship.' ;
49 }
50 return null ;
51 }
52
53 function observationText ( observation ) {
54 return [
55 observation?.summary,
56 observation?.evidence,
57 observation?.suggestedAction,
58 ]. filter (Boolean). join ( ' ' );
59 }
60
61 function evidenceText ( observation ) {
62 return [
63 observation?.summary,
64 observation?.evidence,
65 ]. filter (Boolean). join ( ' ' );
66 }
67
68 function hasUnsupportedWafBotCategoryClaim ( observation ) {
69 const text = observationText (observation);
70 if ( ! / \b WAF \b / i . test (text)) return false ;
71 return / \b bot_category \s * =/ i . test (text) ||
72 / \b target(?:ing) ? \s + (?:browser_impersonation | automated_browser | ecommerce | monitor) \b / i . test (text);
73 }
74
75 function hasUnsafeBotProtectionObservation ( observation ) {
76 const text = observationText (observation);
77 if ( ! / \b (?:Bot Protection | BotID | bot_filter | WAF | managed bot rules ? ) \b / i . test (text)) return false ;
78 const recommendsAction = / \b (?:enable | add | create | configure | challenge | deny | block | rate-limit | target) \b / i . test ( String (observation?.suggestedAction ?? '' ));
79 if ( ! recommendsAction) return false ;
80 const hasSafeRollout = / \b (?:staged | log mode | log action | dry run) \b / i . test (text);
81 const hasAllowlist = / \b allowlist | exclusions ?\b / i . test (text);
82 return ! (hasSafeRollout && hasAllowlist);
83 }
84
85 function hasStaleNextCacheApiObservation ( observation , signals = {}) {
86 const text = observationText (observation);
87 if ( ! / \b unstable_cache \b / . test (text)) return false ;
88 if (signals?.stack?.framework !== 'next' ) return false ;
89 const major = parseInt ( String (signals?.stack?.frameworkVersion ?? '' ). match ( / \d + / )?.[ 0 ] ?? '' , 10 );
90 return Number. isFinite (major) && major >= 16 ;
91 }
92
93 function hasImplementationGradeObservationAction ( observation ) {
94 const action = String (observation?.suggestedAction ?? '' );
95 if (action. trim () === '' ) return false ;
96 if ( / \b (?:use cache: \s * remote | unstable_cache | Cache-Control | s-maxage | cacheLife | export const revalidate | checkBotId | BotID) \b / i . test (action)) return true ;
97 return / \b (?:enable | add | wrap | apply | move | parallelize | set | create | configure | deny | challenge | block | fix | replace | refactor | rewrite | upgrade | downgrade) \b / i . test (action) ||
98 / \b cache \s + (?:the | this | that | shared | public | origin | response | route | data | lookup | fetch | helper) \b / i . test (action) ||
99 / \b turn \s + (?:on | off) \b / i . test (action) ||
100 / \b switch \s + (?:to | from | the | this) \b / i . test (action) ||
101 / \b use \s + Promise \. all \b / i . test (action) ||
102 / \b (?:raise | lower | increase | decrease) \s + (?:the \s + ) ? (?:TTL | timeout | memory | CPU | cache | cache lifetime | duration) \b / i . test (action);
103 }
104
105 function contradictsNoChangeReason ( observation , abstentions ) {
106 const target = candidateTarget (observation?.candidateRef);
107 if ( ! target) return false ;
108 const lowerObservationText = observationText (observation). toLowerCase ();
109 const relevantReasons = abstentions
110 . filter (( a ) => candidateTarget (a?.candidateRef) === target)
111 . map (( a ) => String (a?.reason ?? '' ). toLowerCase ());
112 if (relevantReasons. length === 0 ) return false ;
113
114 if ( / \b paralleliz(?:e | ing) \b / . test (lowerObservationText) &&
115 / \b getsession \b / . test (lowerObservationText) &&
116 relevantReasons. some (( reason ) => / \b getsession \b / . test (reason) && / \b (?:gates ?| redirect | auth-preserving | blocked) \b / . test (reason))) {
117 return true ;
118 }
119 return false ;
120 }
121
122 function candidateTarget ( ref ) {
123 if ( typeof ref !== 'string' ) return null ;
124 const idx = ref. indexOf ( ':' );
125 if (idx === - 1 ) return null ;
126 return ref. slice (idx + 1 );
127 }
128
129 function hasUnsupportedFrameworkCausalClaim ( observation ) {
130 const text = observationText (observation). toLowerCase ();
131 if ( ! text. includes ( 'notfound' ) || ! text. includes ( 'use cache' )) return false ;
132 return (
133 /known next \. js cache components edge case/ . test (text) ||
134 /next \. js \s + \d + (?: \. \d + ) ? [ ^ .] {0,120} treats [ ^ .] {0,120} dynamic api/ . test (text) ||
135 /can surface as 5xx/ . test (text) ||
136 /surface as 500/ . test (text) ||
137 /instead of throwing inside (?:the ) ? cache/ . test (text) ||
138 /cache boundary/ . test (text)
139 );
140 }
141
142 function hasUnsupportedStaticGenerationClaim ( observation ) {
143 const text = observationText (observation). toLowerCase ();
144 if ( ! / \b generatestaticparams \b / . test (text)) return false ;
145 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) ||
146 / \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) ||
147 / \b dynamic \s * = \s * ['"`] error ['"`] \b [ ^ .\n] {0,240}\b (?:generatestaticparams | dynamicparams | every request | on [- ] demand) \b / i . test (text);
148 }
149
150 function hasUnsupportedSourceAbsenceClaim ( observation ) {
151 const ref = String (observation?.candidateRef ?? '' );
152 if ( ! ref. startsWith ( 'route_errors:' )) return false ;
153 const text = observationText (observation). toLowerCase ();
154 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);
155 }
156
157 function hasUnsupportedCacheLifeCdnClaim ( observation ) {
158 return hasUnsupportedCacheLifeCdnText ( observationText (observation));
159 }
160
161 export function hasUnsupportedCacheLifeCdnText ( text ) {
162 if ( typeof text !== 'string' || ! / \b cacheLife \b / i . test (text)) return false ;
163 if ( / \b toLaunch- \d +\b / i . test (text)) return true ;
164 return / \b cacheLife \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) ||
165 / \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}\b cacheLife \b / i . test (text) ||
166 / \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);
167 }
168
169 function hasUnsupportedRuntimeRootCauseClaim ( observation ) {
170 const text = observationText (observation);
171 if ( ! / \b (?:caused by | root cause | responsible for failures | would produce) \b / i . test (text)) return false ;
172 if ( ! / \b (?:5xx | 500 | error | failures ? ) \b / i . test (text)) return false ;
173 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));
174 }