From a524d860a88932723046cc3a0715e55d794f52d9 Mon Sep 17 00:00:00 2001 From: Sinabina Date: Tue, 21 Jul 2026 17:40:50 -0700 Subject: [PATCH] docs: record real-environment verification and the fixes it drove Update the capability matrix and provider notes to the verified real interfaces (graphify update, Sourcebot v5 Bearer auth) and add a "Verified against real environments" section documenting what the live tests found and fixed. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../CODE_INTELLIGENCE_PROVIDER_CONTRACT.md | 54 +++++++++++++++---- 1 file changed, 43 insertions(+), 11 deletions(-) diff --git a/docs/designs/CODE_INTELLIGENCE_PROVIDER_CONTRACT.md b/docs/designs/CODE_INTELLIGENCE_PROVIDER_CONTRACT.md index c5a01cbb0..9cc962cc4 100644 --- a/docs/designs/CODE_INTELLIGENCE_PROVIDER_CONTRACT.md +++ b/docs/designs/CODE_INTELLIGENCE_PROVIDER_CONTRACT.md @@ -123,9 +123,9 @@ consent; egress requires a separate explicit step. | Op | GBrain (recommend first) | Sourcebot | Graphify | |----|--------------------------|-----------|----------| -| `register_source` | ✓ `sources add` | ✓ repo added to index config | ✓ index a local dir | -| `refresh` | ✓ `sync --strategy code` | ✓ reindex | ✓ re-parse tree-sitter graph | -| `search` | ✓ `gbrain search` (federated corpora) | ✓ `POST /api/search` (regex, zoekt) | ✓ `graphify query ""` | +| `register_source` | ✓ `sources add` | ✓ local `git` connection in config.json | ✓ `graphify update ` (local, no LLM) | +| `refresh` | ✓ `sync --source` | ✓ auto (config change + reindexIntervalMs) | ✓ `graphify update ` | +| `search` | ✓ `gbrain search` (federated corpora) | ✓ `POST /api/search` + Bearer key (v5) | ✓ `graphify query "" --graph ` | | `status` | ✓ `sources list` + page_count | ~ partial (server liveness) | ~ partial (graph.json present + node count) | | `add` | ✓ `put ` | ✗ declines | ✗ declines | | `delete` | ✓ `delete ` | ✗ declines | ✗ declines | @@ -142,15 +142,20 @@ All three are driven directly from the runtime — no MCP client: - **Sourcebot** (`github.com/sourcebot-dev/sourcebot`, YC Fall 2025): self-hosted whole-repo regex search. `register_source` adds a local `{ "type": "git", "url": "file:///path" }` connection to the server's `config.json` (it re-indexes on - config change); `search` is `POST {baseUrl}/api/search`; `status` is a liveness - probe. Declines `add`/`delete`/`export`. A loopback `baseUrl` keeps content on - the machine (local); a remote one requires egress consent. + config change); `search` is `POST {baseUrl}/api/search`; `status` probes that + endpoint. Declines `add`/`delete`/`export`. **Sourcebot v5 gates `/api/search` + behind auth**, so the adapter sends `Authorization: Bearer `. + A loopback `baseUrl` keeps content on the machine (local); a remote one requires + egress consent. - **Graphify** (`github.com/Graphify-Labs/graphify`, YC-backed): local - tree-sitter code graph via the `graphify` CLI. `graphify ` builds - `graphify-out/graph.json`; `graphify query ""` searches it; `export` reads - the graph JSON. Fully local — nothing leaves the machine. Optional, **install - only with explicit user action** (`pip install graphifyy && graphify install`); - never auto-installed. + tree-sitter code graph via the `graphify` CLI. The adapter uses **`graphify + update `** — the local, no-LLM build (writes `graphify-out/graph.json`); + it deliberately avoids the bare `graphify ` build, which runs an LLM + extraction backend needing an API key + network. `graphify query "" --graph + ` searches it (its `NODE ...`/`EDGE ...` output carries the file at + `src=`/`at=`); `export` reads the graph JSON. Fully local — nothing leaves the + machine. Optional, **install only with explicit user action** (`pip install + graphifyy && graphify install`, needs Python >= 3.10); never auto-installed. **No local-index option is offered** (deliberately excluded — a naive local index degrades result quality; we route to a real provider or to file-only grep, @@ -229,6 +234,33 @@ a later phase precisely so the first slices do not trigger the - **Phase 4: retire bespoke glue.** Once every consumer is on the contract, delete the sync/ingest/cache entrypoints and their tests provider-by-provider. +## Verified against real environments + +The three adapters were tested against the real tools in isolated environments +(parallel agents, one worktree each), not just unit fakes. What that surfaced and +fixed: + +- **Graphify (real install, graphify 0.9.23).** The first cut ran `graphify ` + — which invokes an LLM extraction backend (needs a key + network), breaking the + "local, no egress" promise — and parsed a made-up output format. Fixed to the + real local `graphify update` build and a parser written against the real + `NODE`/`EDGE` output (file at `src=`/`at=`). Also fixed `search` ignoring the + indexed repo (now persists the indexed root) and `options` mislabeling an + installed-but-unindexed provider as unavailable. +- **Sourcebot (live v5 in Docker).** Endpoint, request body, and response parsing + were correct against the real server. But v5 gates `/api/search` behind auth, so + the adapter got HTTP 401; added `Authorization: Bearer` support and made `status` + stop following the login redirect (it was falsely reporting "ready"). +- **GBrain (real gbrain 0.42.56, pglite engine).** The engine was broken on the + host (upstream macOS WASM bug), which exposed two bugs: engine-down failures were + reported as hard `PROVIDER_ERROR` with a raw stack dump instead of a clean + `PROVIDER_UNAVAILABLE` degrade (fixed), and the adapter sent flags the real + `gbrain` CLI does not define (`sync --strategy`, `search --source`) — corrected + to the real surface. + +Live end-to-end index+search-with-results was proven for Graphify and Sourcebot; +GBrain's was blocked only by the host's broken engine, not by adapter code. + ## What this does NOT change Per the GStack 2 canonical contract and CLAUDE.md boundaries: no cloud browsers,