Optimize Kuzu watch refresh performance - #791

Summary

• serialize and batch watcher refreshes per repository instead of allowing overlapping full refreshes
• update imports incrementally for changed files and batch changed-file graph updates into a single DB session
• keep relink work scoped to changed files plus affected callers and inheritors
• add regression tests for watcher incremental cache updates and batched graph updates

Related Issues

• Closes Watch mode on large repos schedules overlapping full refreshes and delays MCP visibility #792
• Related to Add incremental indexing to avoid full re-scans of large codebases #310
• Benchmark context for Performance / scale benchmarks #122

Large Repo Measurements

Observed on a large monorepo of roughly 2,190 files / 8,764 functions / 1,147 classes.

Before this patch:

• a watched single-file edit took about 20-26s before the new symbol became queryable through MCP
• instrumentation showed the old relink path still at 100 / 1691 files after 103.7s

After this patch:

• the same watched single-file edit became queryable by the <= 10s poll on the same repo
• the scoped relink path for a one-file refresh completed in 0.0s for both function-call and inheritance relinking in the instrumented run

These are local measurements on a large real-world repo, not a controlled benchmark.

Testing

• PYTHONPATH=$(pwd)/src ~/.local/pipx/venvs/codegraphcontext/bin/python -m pytest tests/unit/core/test_watcher_incremental_refresh.py tests/unit/tools/test_graph_builder_batch_updates.py -v
• ORIG_HOME="$HOME"; TMP_HOME=$(mktemp -d /tmp/cgc-fast-home.XXXXXX); CLEANUP_FILE=.env.codex-fast-temp; printf 'DEFAULT_DATABASE=kuzudb\nENABLE_AUTO_WATCH=false\n' > "$CLEANUP_FILE"; rm -f .env; ln -s "$CLEANUP_FILE" .env; trap 'rm -f .env "$CLEANUP_FILE"' EXIT; HOME="$TMP_HOME" PATH="$ORIG_HOME/.local/pipx/venvs/codegraphcontext/bin:$ORIG_HOME/.local/bin:$PATH" PYTHONPATH=$(pwd)/src ./tests/run_tests.sh fast
• standalone MCP smoke test against the editable install: start cgc mcp start, attach watch_directory, mutate provider and consumer files, then verify the new symbol and caller edge are queryable through MCP