feat(index): callback dispatch synthesis (#164)

* feat(index): callback dispatch synthesis tracer (SCHEMA 37)

Add calls.provenance and optional JSX parent→child heuristic edges via
synthesis.heuristicCalls (default off). Filter call-path to ast-only;
ship calls-including-heuristic recipe.

* fix(index): Moat-A provenance filters and resolve ordering

Purge heuristic calls before resolveCalls; filter ast-only rows in resolver,
impact/trace, and default recipes. Golden coverage for calls-including-heuristic.

* fix(index): extend Moat-A to deletions-only and verdict recipes

Shared runCallResolveAndSynthesis for index + run-index deletions path;
filter heuristic calls in untested-and-dead and components-touching-deprecated.

* fix(pr-164): close review gaps — import-aware synthesis, docs, tests

Tie JSX child edges to same-file or import resolved_path; global heuristic
purge when synthesis off; minimal jsx-synthesis bench + integration tests;
consumer docs, example config, golden refresh.

* docs: fix last PR-164 review nits (MCP refs, plan default, calls-consumer SQL)

* docs: retire callback-dispatch-synthesis plan after JSX tracer

Delete shipped plan; roadmap marks #164 done. EventEmitter/setState heuristics
explicitly out of scope for now. PR title lesson in .agents/lessons.md.

Author: SutuSebastian

.agents/lessons.md

@@ -23,4 +23,5 @@ Persistent log of corrections and insights from past sessions. Read when relevan
 - **`process.exitCode` is NOT a safe success oracle inside CLI verbs** — when a CLI handler in `runQueryCmd` (or any sibling that supports `--ci`) needs to know "did the work succeed?" for a side-effect decision (recency tracking, telemetry, follow-up writes), do NOT key off `process.exitCode !== 1`. Two failure modes: (1) `--ci` deliberately sets `exitCode = 1` on findings as the CI gating signal even though the recipe ran cleanly — keying off exitCode then treats success as failure (PR #76 audit Finding 1: `--ci + --recipe X --format sarif` exits 1 → recency NOT recorded → undercounts every CI run). (2) The exit code is process-global and survives across calls when an exported helper is invoked multiple times in one process (tests, programmatic use); a prior failure poisons later success. **Pattern:** track an explicit `recipeQuerySucceeded` (or domain-named) local flag, set true at each successful exit point inside the try block; check it in the finally. For helpers that conflate "ran cleanly" with "exit 1 because findings" (like `printFormattedQuery`), refactor to a discriminated-union return shape (`{ ok: true, exitCode: 0 | 1 } | { ok: false }`) so callers can disambiguate. Hit on PR #76 — caught by 2/3 PR-review agents (Codex + gpt-5.5) with concrete repros.
 - **Read-side substrate must be pure even when "lazy on read" looks cheap** — when a write-side cleanup (DELETE-on-prune, GC sweep, cache invalidation) seems cheaper to run lazily on the read path, weigh that against the documented contract of the read site. If the read surface promises "no side effects" / "no DB required" / "read resource" semantics (per CLI help text, README, MCP resource conventions), an in-place DELETE breaks the contract — even under WAL where the write doesn't block readers. **Pattern:** filter at SELECT time (`WHERE last_run_at >= cutoff`) for read paths, do eager prune on the write path (typically cheap on tiny domain tables — index-bounded scan is microseconds). The "hot path" cost concern that motivates lazy-on-read usually doesn't hold for tiny tables, but the read-purity invariant is durable across N agents reading the resource. Hit on PR #76 — Q3 of the recipe-recency plan locked lazy-on-read with reasoning that didn't model the "No DB required" `--recipes-json` contract; gpt-5.5 audit caught it.
 - **Never fabricate quantitative explanations to rationalize surprising data** — when a CI / perf / benchmark number is unexpected (e.g. went up after a "performance" PR), the failure mode is to invent a plausible-sounding cause without verification ("+8 doc files were added since the baseline"). This is intellectual dishonesty that compounds: the fabricated cause gets baked into PR bodies, commit messages, follow-up reasoning, and other agents inherit it as fact. **Pattern:** when a number surprises you, say "I don't know yet" and either (a) instrument / re-run to find the real cause, or (b) accept the unknown and surface it explicitly to the user. Verifiable claim formats: `git diff --name-status A..B | grep '^A'` for file-add counts, `gh run view <id> --log` for CI numbers, repeated CI runs on the same commit for variance characterisation. **Never** invent a numeric explanation that "sounds right". Hit on PR #104 (perf-baseline refresh) — claimed "8 new doc files indexed since cc8daed" explaining a +71ms CI regression; actual delta was 1 file. User caught it; PR was closed.
+- **PR titles: no `SCHEMA N` / `SCHEMA_VERSION` suffix** — schema bumps belong in the PR body, changeset, and `db.ts`; putting `(SCHEMA 37)` in the title adds noise and duplicates what reviewers see in the diff. Title = what shipped (`feat(index): callback dispatch synthesis`), not the integer.
 - **Perf-baseline flakes are often GHA runner tiers, not code regressions** — `ubuntu-latest` jobs on the same commit can land on fast (~630 ms total) or slow (~1117 ms) runners; cross-job spread dwarfs the +25% gate. **Pattern:** compare pass vs fail CI logs on the same SHA before re-baselining or blaming a PR; capture baseline medians from slow-tier CI logs, use `CODEMAP_PERF_RUNS=5` in CI, and honour `CODEMAP_PERF_REGRESSION_PCT` env during compare (not just `--update`). Hit on main CI May 2026 — #136 merge blocked by `index_create_ms` +31.7% while `total_ms` was only +15%.

.changeset/callback-dispatch-synthesis.md

@@ -0,0 +1,5 @@
+---
+"@stainless-code/codemap": minor
+---
+
+Add optional heuristic call edges (`calls.provenance`) for JSX parent→child composition. Schema rebuild to v37. Enable via `.codemap/config` `synthesis.heuristicCalls: true` (default off). Bundled recipe `calls-including-heuristic`; `call-path` excludes heuristics by default.

codemap.config.example.json

@@ -1,6 +1,9 @@
 {
   "include": ["src/**/*.{ts,tsx,js,jsx}", "src/**/*.css", "**/*.{md,json}"],
   "excludeDirNames": ["node_modules", ".git", "dist", "build", ".output"],
+  "synthesis": {
+    "heuristicCalls": false
+  },
   "boundaries": [
     {
       "name": "ui-cant-touch-server",