Profiling and Verification
Load at PROFILE and VERIFY, and for the selected recipe's gate below. Version/toolchain authority: _common/builder/reference/implementation-policy.md § Language and Toolchain Grounding. Use the target's configured profilers and benchmark harnesses; adding a dependency, changing build settings or exposing a debugger is not implicitly authorized.
Select Evidence, Not an Optimization by Language
| Target / symptom | Capture before choosing the change |
|---|---|
| Browser render / interaction | React DevTools commit trace plus browser Performance trace; verify React Compiler activation. Use real-user CWV data when available and the same interaction/device conditions for the lab comparison. A load-only Lighthouse run is not an INP measurement. |
| App bundle / network | Production-build analyzer totals and per-route chunks; actual response headers and critical-resource waterfall. A removed import is not proof that a library left the emitted bundle. |
| Node.js CPU / memory | A scoped CPU/heap profile from the existing inspector/profiler and representative load; do not expose inspector access to an untrusted network. |
| Rust | Representative optimized-build CPU/allocation profile; benchmark the actual target/features/allocator, retain useful symbols, and compare both the hot operation and end-to-end workload. Never infer an allocator, SIMD, unsafe, PGO or inlining win from a cached percentage. |
| Kotlin/JVM | CPU, allocation, lock and GC evidence with the actual JDK/runtime settings. For JMH, use at least 5 warmup iterations and 2 forks, consume results with Blackhole, and vary realistic inputs with @Param; report variance. Measure cold startup separately from warmed steady state. |
| Kotlin/Native / Swift | Profile the actual device/target, allocation/retention, concurrency and optimized build. JVM benchmark results do not transfer to Native. Instruments/signposts or an existing platform harness should identify the bottleneck before an ARC, collection or concurrency change. UI render/launch/hitch work belongs to Native; DB-internal memory belongs to Tuner. |
Record tool/runtime version, build mode, input/load, machine/device, warmup and sample distribution with both measurements. A microbenchmark win without an end-to-end improvement does not satisfy VERIFY. Allocation/lifetime, bounds, numerical, cancellation and failure semantics remain correctness constraints; never replace safe access with unsafe buffers or unowned merely for a presumed speedup.
For current runtime defaults, profiler options and compiler features, consult the installed tool's help and its version-matched official documentation. Do not keep an allocator/library recommendation or a benchmark ratio as a repository-wide default.
Per-Recipe Behavior + VERIFY Gates
Behavior notes per Recipe:
frontend: Verify React Compiler activation. Measure LCP/INP/CLS → optimize the single largest bottleneck. VERIFY: check waterfalls before memo/render work; after-metric beats baseline AND clears the CWV "Good" gate (LCP ≤2.5s, INP ≤200ms, CLS ≤0.1); no new commit/re-render introduced (React DevTools Profiler).backend: Target N+1/cache/connection pool. Follow Bolt→Tuner handoff criteria (deep SQL analysis). VERIFY: query/span count + p95 captured pre-change; N+1 span count collapses to 1–2 (not N+1); every connection returned via try/finally (no pool leak); any added cache key has a TTL; after-p95 beats baseline; event-loop lag ≤100ms held.render: Specialize in React re-render reduction. Consider manual memo only when React Compiler is not in use. VERIFY: wasted-commit count measured pre/post (React DevTools Profiler) and strictly drops; manualmemo/useMemo/useCallbackadded ONLY when compiler off OR expensive sync compute proven (else it's dead weight under the compiler); identical render output (no behavior change).async: Convert sequential await to Promise.all. VERIFY: parallelize ONLY independent awaits — a dependent chain must stay sequential; total latency captured pre/post and approachesmax(parts)notsum(parts); partial-failure semantics chosen deliberately (Promise.allfail-fast vsallSettledtolerant); no shared-state race introduced by reordering.cache: LRU/Redis/HTTP cache. Always set TTL. Include stampede countermeasures (lock/lease). VERIFY: every key has a TTL (zero unbounded-growth keys); hot keys carry a stampede guard (lock/lease orstale-while-revalidate); hit-rate ↑ and origin load ↓ vs baseline; staleness window is acceptable for the data's correctness contract; cheapest layer tried first (HTTPstale-while-revalidatebefore in-process LRU).bundle: App-wide JS/TS bundle-size audit. Start from analyzer output (rollup-plugin-visualizer / webpack-bundle-analyzer / source-map-explorer) → kill barrel re-exports that break tree-shaking → split by route/feature with dynamicimport()→ swap oversized deps (moment→dayjs, lodash→lodash-es, axios→fetch). Set a per-route kB budget. Scope boundary: Artisanperftunes a single component (memo, virtualization); Boltbundlereduces total shipped bytes across the app. If the hypothesis is "this one list is slow", route to Artisan. VERIFY: analyzer-measured total + per-route kB captured pre/post and falls under the declared budget; the swapped/dead lib is gone from the emitted chunk (not justpackage.json); no barrel re-export reintroduced; dynamicimport()boundaries don't break SSR/hydration; no runtime behavior change.network: Client/server delivery-layer tuning. Enable HTTP/2 and HTTP/3, emit Early Hints (103) orLink:preload headers from the origin, place<link rel="preload|prefetch|preconnect|dns-prefetch">only for verified critical resources, design Service Worker caching strategy (cache-first / stale-while-revalidate / network-first per asset class), tune CDNCache-Control/s-maxage/stale-while-revalidate, enable Brotli for text assets. Scope boundary: Scaffold provisions the CDN/edge; Gear operates and monitors it; Boltnetworkdesigns the delivery-policy headers, cache strategy, and resource-hint placement that the app and CDN emit. VERIFY: TTFB/LCP captured pre/post and beats baseline; resource hints cover ONLY verified-critical resources (no over-preload — unused preloads warn in console and waste bandwidth); SW strategy matches asset class (network-first for HTML, cache-first for hashed static); CDNCache-Controlcannot serve stale mutable data; Brotli confirmed on text responses.memory: App-process memory footprint reduction. Frontend: Chrome DevTools Memory panel heap snapshot diffing (record 3 snapshots across a repeated action → filter "Objects allocated between snapshots"), find detached DOM nodes, closures over large scopes, uncleaned event listeners andIntersectionObserver/ResizeObserverreferences. Backend: Node.js--inspect+--heapsnapshot-signal=SIGUSR2,clinic heapprofiler, rising RSS baseline across load generations. ApplyWeakMap/WeakRefwhere identity caches would otherwise pin GC. Scope boundary: a leak BUG (race, deadlock, resource leak with reproduction steps) is out of scope; Boltmemoryremoves the FAT (measures footprint, cuts retained size, enforces baseline budgets). If no leak is suspected but memory is simply too large, stay in Bolt. Tuner is DB-internal memory (buffer pools, work_mem) — out of scope here. VERIFY: retained size captured pre/post (3-snapshot diff or RSS trend across ≥3 load generations) and strictly drops; zero detached DOM nodes / uncleaned listeners remain in the after-snapshot; baseline does NOT keep rising across generations (rising baseline = unfixed leak bug, out of Bolt scope);WeakMap/WeakRefapplied only where an identity cache was pinning GC.
Measurement Sources
https://web.dev/articles/inp (checked 2026-09-17): the official Good threshold is INP ≤200ms at the 75th percentile, segmented by mobile/desktop. A stricter project budget is possible, but no date-based 150ms SEO guarantee is implied. CWV measurement details remain in reference/core-web-vitals.md.