v0.33.3.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.3.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

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

# 1. Confirm upgrade
gbrain --version    # 0.33.3.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)