# v0.33.0 migration — code intelligence foundation + MCP-exposed code ops

`gbrain upgrade` runs `gbrain apply-migrations` automatically. Most users
won't need to do anything else. If you hit issues or want to verify the
upgrade succeeded, run the steps below.

## What changed

v0.33.0 is the foundation pre-release for v0.34 Cathedral III. It ships the
agent-facing MCP surface for the v0.20+ tree-sitter call graph plus the
foundation fixes needed before recursive blast/flow and Leiden clusters
land in v0.34.

**MCP exposure (NEW for agents):**

Four code-intelligence ops graduated from `CLI_ONLY` to first-class MCP ops:

- `code_callers(symbol, [limit, source_id, all_sources])` — find every
  caller of a symbol. Use BEFORE editing any function.
- `code_callees(symbol, [limit, source_id, all_sources])` — trace what a
  function calls. Use when debugging unexpected behavior.
- `code_def(symbol, [limit, lang])` — find a symbol's definition site(s).
- `code_refs(symbol, [limit, lang])` — find every reference (comments,
  imports, type annotations, call sites).

The MCP tool descriptions are resolver-grade — they tell agents WHEN to
reach for each op so plan-mode subagents route to structural retrieval
instead of falling through to text search.

**Foundation fixes:**

- **Source-routing fix** (Codex finding #2): `query` op now threads
  `ctx.sourceId` to `hybridSearch`. Two-pass retrieval honors `sourceId`
  at both the `nearSymbol` lookup and unresolved-edge resolution sites.
  Multi-source brains stop cross-contaminating structural retrieval.
- **CLI source-scoping default flipped** (Codex finding #7): `gbrain
  code-callers <symbol>` without `--source` now resolves to your brain's
  default source (the only source on single-source brains; explicit
  error listing valid ids on multi-source brains). Pre-v0.33 the
  default silently was global — multi-repo brains cross-resolved every
  same-named symbol.

**Within-file two-pass symbol resolution:**

A new cycle phase `resolve_symbol_edges` runs after `extract` on every
autopilot tick. It walks `content_chunks.edges_backfilled_at IS NULL`
chunks in 200-row batches, matching each `to_symbol_qualified` against
the same-file `symbol_name_qualified`, and writes the outcome to
`code_edges_symbol.edge_metadata`:

- `{resolved_chunk_id: N}` — one unambiguous match
- `{ambiguous: true, candidates: [...]}` — 2+ matches in the same file
- (no metadata change) — zero matches; caller's two-pass walk handles
  cross-file resolution

## Schema migration v51 — what it adds

```sql
ALTER TABLE content_chunks ADD COLUMN IF NOT EXISTS edges_backfilled_at TIMESTAMPTZ;

CREATE INDEX IF NOT EXISTS idx_code_edges_symbol_resolver
  ON code_edges_symbol (source_id, to_symbol_qualified);
CREATE INDEX IF NOT EXISTS idx_content_chunks_symbol_lookup
  ON content_chunks (page_id, symbol_name_qualified)
  WHERE symbol_name_qualified IS NOT NULL;
CREATE INDEX IF NOT EXISTS idx_content_chunks_edges_backfill
  ON content_chunks (edges_backfilled_at)
  WHERE edges_backfilled_at IS NULL;
```

All idempotent. Existing brains see the column + indexes added; the resolver
walks the corpus lazily over the next several autopilot cycles.

**First-run cost:** ~5-15 minutes of background resolver work on a 10K-chunk
brain spread across cycles (~2000 chunks/tick). No user-visible interruption
unless you watch `gbrain doctor`'s autopilot stats.

## What the agent should do

If you're an agent (Claude Code, OpenClaw, Cursor) running through MCP:

1. **Before editing any function**, reach for `code_callers` to surface
   every caller. The MCP tool description tells you this — follow it.
2. **When tracing execution**, reach for `code_callees` from the entry
   point.
3. **When looking up a definition**, reach for `code_def` not `search`.
   It returns line numbers + snippet directly.
4. **When planning a rename**, reach for `code_refs` to find every
   literal mention.
5. **Honor source scoping**: multi-source brains require explicit
   `source_id` or `all_sources: true`. Single-source brains auto-resolve.

The previously available CLI commands (`gbrain code-callers <symbol>`)
still work but now default to source-scoped on multi-source brains.
Pass `--all-sources` to get the pre-v0.33 cross-source default.

## Verification

```bash
# 1. Confirm upgrade
gbrain --version    # 0.33.0

# 2. Confirm migration v51 ran
gbrain apply-migrations --status | grep edges_backfilled_at_v0_34

# 3. Confirm the new MCP ops are exposed
gbrain --tools-json | jq '.[] | select(.name | startswith("code_")) | .name'
# Should show: code_callers, code_callees, code_def, code_refs

# 4. Try one end-to-end (replace `parseMarkdown` with any symbol you index)
gbrain code-callers parseMarkdown --json | jq '.count'

# 5. (Optional) inspect the resolver's per-source progress
gbrain doctor --json | jq '.checks | to_entries[] | select(.key | contains("code"))'
```

## Rollback

If you need to roll back: `git checkout` an older binary and run
`gbrain doctor`. The v51 column + indexes stay in your DB (no-op for
older binaries; idempotent re-add on upgrade). No data is destroyed.

## What v0.34 will add on top

Per the v0.34 design doc (`/Users/garrytan/.gstack/projects/garrytan-gbrain/garrytan-garrytan-miami-design-20260510-194145.md`):

- Recursive `code_blast` / `code_flow` MCP ops on top of the resolved graph
- Leiden community detection (`code_clusters_list`, `code_cluster_get`) +
  inline mermaid diagrams
- `gbrain wiki` zero-LLM aggregator CLI
- Per-op graph-traversal eval metrics extending v0.25.0's eval-capture
- `imports` and `references` edge types for JS/TS/TSX + Python
- Receiver-type scope walkers (e.g. `obj.method()` → `Class.method`)
