fix: preserve hand-written notes in benchmark report regeneration (#128)

Add NOTES_START/NOTES_END sentinel preservation to the benchmark
updater so CI-triggered regenerations no longer clobber hand-written
analysis sections. Also adds WASM regression notes to the benchmark
report.

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: carlos-alm

generated/BUILD-BENCHMARKS.md

@@ -62,6 +62,26 @@ Extrapolated linearly from per-file metrics above.
 |---------|--------|------------:|--------------:|----------:|----------:|
 | 2.4.0 | wasm | 1.8 | 1.4 | 0.8 | 0.8 |
 
+<!-- NOTES_START -->
+### Notes
+
+**WASM regression (v2.0.0 → v2.1.0, ↑32% — persists in v2.3.0):** The
+"v2.1.0" entry was measured after the v2.1.0 tag on main, when `package.json`
+still read "2.1.0" but the codebase already included post-release features:
+receiver field extraction (`b08c2b2`) and Commander/Express callback extraction
+(`2ac24ef`). Both added WASM-to-JS boundary crossings on every
+`call_expression` AST node. The native engine was unaffected because its Rust
+extractors have zero boundary overhead — and it gained a net 24% speedup from
+the ~45% edge reduction introduced by scoped call-resolution fallback
+(`3a11191`). For WASM the extra crossings outweighed the edge savings. A
+targeted fix in `d4ef6da` gated `extractCallbackDefinition` behind a
+`member_expression` type check and eliminated redundant `childForFieldName`
+calls, but the v2.3.0 CI benchmark confirms this was **insufficient** — WASM
+remains at 6.6 ms/file (vs 5.0 in v2.0.0). The WASM/Native ratio widened from
+2.0x to 3.5x. Further optimization of WASM boundary crossings in the JS
+extractor is needed to recover the regression.
+<!-- NOTES_END -->
+
 <!-- BENCHMARK_DATA
 [
   {

scripts/update-benchmark-report.js

@@ -200,6 +200,19 @@ if (hasQueries) {
 	md += '\n';
 }
 
+// ── Preserve hand-written notes from existing file ────────────────────
+let notes = '';
+if (fs.existsSync(benchmarkPath)) {
+	const existing = fs.readFileSync(benchmarkPath, 'utf8');
+	const notesMatch = existing.match(/<!-- NOTES_START -->\n([\s\S]*?)<!-- NOTES_END -->/);
+	if (notesMatch) {
+		notes = notesMatch[1];
+	}
+}
+if (notes) {
+	md += `<!-- NOTES_START -->\n${notes}<!-- NOTES_END -->\n\n`;
+}
+
 md += `<!-- BENCHMARK_DATA\n${JSON.stringify(history, null, 2)}\n-->\n`;
 
 fs.mkdirSync(path.dirname(benchmarkPath), { recursive: true });