docs: design the repo-oriented code-intelligence provider contract

Design for the OPTIONAL code-intelligence provider contract that lets a user pick how their codebase is indexed and searched, replacing gstack's ~17k LOC of bespoke GBrain glue. Repo-oriented ops (register_source/ refresh/search/status required; add/delete/export optional), a per-provider capability matrix, GBrain-recommended-first selection, repo-scoped + install consent, and a phased rollout that keeps gstack fully functional with no provider selected. All three providers are driven from the runtime via CLI or HTTP — no MCP client. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-09-21 04:10:47 +02:00 · 2026-07-21 17:16:53 -07:00
parent a84a6e233d
commit b4421a4e69
6 changed files with 914 additions and 0 deletions
@@ -0,0 +1,254 @@
+# Code-Intelligence Provider Contract
+
+Status: design + first implementation slice
+Owner: maintainer-directed internal work
+Related: `runtime/context.js` (Context.dev provider pattern),
+`scripts/gstack2/browser-provider-contract.ts` (the existing provider-contract idiom),
+`lib/gstack-decision-semantic.ts` (degrade-to-null reliability contract)
+
+## Problem
+
+gstack carries ~17k LOC of home-grown code-intelligence glue: transcript
+ingestion (`bin/gstack-memory-ingest.ts`, ~1.9k), a unified sync verb
+(`bin/gstack-gbrain-sync.ts`, ~1.6k), context loading
+(`bin/gstack-brain-context-load.ts`), a three-tier planning cache
+(`bin/gstack-brain-cache`), source reconciliation, engine-status classification,
+destructive-op guards, plus ~15 `bin/gstack-gbrain-*` and `bin/gstack-brain-*`
+entrypoints and ~40 tests. All of it is bespoke wiring around one external tool
+(GBrain) reached by direct CLI shell-out.
+
+We do not want to keep maintaining a home-grown indexer. We want gstack to
+define a **small optional contract** that external providers implement, so the
+indexing/search/graph work lives in the provider, not in gstack.
+
+Hard requirement, non-negotiable: **gstack must remain fully functional with the
+provider OFF.** File-only paths (the decision store, Context Recovery, grep) stay
+reliable and never depend on a provider being present. This is the existing
+decision-store philosophy (`lib/gstack-decision.ts` has zero gbrain imports;
+`lib/gstack-decision-semantic.ts` degrades to `null`). The contract is an
+enhancement, never a dependency.
+
+## Design decision: repo-oriented, not document-store
+
+Settled (do not relitigate). The contract is **repo-oriented**:
+
+```
+register_source(repo)   — required
+refresh(source)         — required
+search(query)           — required
+status(source)          — required
+```
+
+`add` / `delete` / `export` are **optional capabilities** a provider MAY
+advertise. GBrain advertises them (its native primitive is document-by-slug:
+put/delete/get/export); code-search and code-graph tools decline them.
+
+A document-store contract (add / delete-by-id / export as *required* ops) was
+rejected: it misrepresents code-search and code-graph tools. Sourcebot indexes a
+whole repo and exposes search; it has no concept of "delete document id X".
+Forcing every provider to implement a document CRUD surface would either exclude
+the exact tools we most want (whole-repo indexers, graph tools) or force them to
+stub required ops with lies. Repo-in / query-out is the honest common
+denominator. GBrain's document axis survives as an *optional* capability, not as
+the contract's shape.
+
+## The contract
+
+TypeScript in `lib/code-intelligence/contract.ts`. Shape (abridged):
+
+```ts
+type CodeProviderCapability =
+  | "register_source" | "refresh" | "search" | "status"   // required
+  | "add" | "delete" | "export";                          // optional
+
+interface CodeProvider {
+  readonly id: "gbrain" | "sourcebot" | "graphify";
+  readonly label: string;
+  readonly capabilities: ReadonlySet<CodeProviderCapability>;
+  readonly local: boolean;   // true = no repo content leaves the machine
+
+  registerSource(repo: RepoRef, opts?: OpOptions): Promise<SourceStatus>;
+  refresh(source: SourceRef, opts?: OpOptions): Promise<SourceStatus>;
+  search(query: string, opts?: SearchOptions): Promise<CodeSearchHit[]>;
+  status(source?: SourceRef, opts?: OpOptions): Promise<SourceStatus>;
+
+  add?(doc: { slug: string; body: string }, opts?: OpOptions): Promise<SourceStatus>;
+  delete?(slug: string, opts?: OpOptions): Promise<SourceStatus>;
+  export?(source: SourceRef, opts?: OpOptions): Promise<string>;
+}
+```
+
+Every provider MUST implement the four required methods and MUST advertise
+exactly the capabilities it backs (`assertRequiredCapabilities` enforces the
+required four at construction; a test pins it). Optional methods are present iff
+the matching capability is advertised. Calling an unadvertised optional op throws
+`CAPABILITY_UNSUPPORTED` — never a silent no-op.
+
+### Typed failures
+
+Mirrors `runtime/context.js`'s `ContextError` discipline (a closed code set,
+constructor throws on an unknown code):
+
+| Code | Meaning |
+|------|---------|
+| `PROVIDER_UNAVAILABLE` | CLI/MCP transport absent — degrade to file-only |
+| `PROVIDER_NOT_CONSENTED` | repo indexing not consented and content would leave the machine |
+| `CAPABILITY_UNSUPPORTED` | provider declines this op |
+| `SOURCE_NOT_REGISTERED` | op needs a source that isn't registered |
+| `PROVIDER_TIMEOUT` | provider exceeded the op timeout |
+| `PROVIDER_ERROR` | provider ran and failed |
+
+`PROVIDER_UNAVAILABLE` is the load-bearing one: callers catch it (or use the
+picker's null resolution) and fall back to grep / file-only. It is never fatal.
+
+### Consent
+
+Two orthogonal consent axes, both explicit, neither auto-granted:
+
+1. **Network / content-egress consent (repo-scoped).** Before any repo content
+   leaves the machine, indexing must be consented *per repo*. The contract
+   enforces this in `registerSource`/`refresh`/`add`: when
+   `provider.local === false` and `opts.consented !== true`, it throws
+   `PROVIDER_NOT_CONSENTED`. Local providers (Graphify) skip this axis — nothing
+   leaves the machine.
+2. **Install consent (Graphify only).** Graphify is never auto-installed. The
+   `options`/`status` display marks it available only when its CLI is present,
+   and nothing in gstack runs a Graphify installer. Install is a user action
+   (`pip install graphifyy && graphify install`).
+
+This matches the Context.dev model: selection persists without granting egress
+consent; egress requires a separate explicit step.
+
+## Per-provider capability matrix
+
+| 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 "<q>"` |
+| `status` | ✓ `sources list` + page_count | ~ partial (server liveness) | ~ partial (graph.json present + node count) |
+| `add` | ✓ `put <slug>` | ✗ declines | ✗ declines |
+| `delete` | ✓ `delete <slug>` | ✗ declines | ✗ declines |
+| `export` | ✓ `export` | ✗ declines | ✓ read `graphify-out/graph.json` |
+| `local` (no egress) | no (federated DB) | loopback → **yes**; remote host → no | **yes** (local only) |
+
+All three are driven directly from the runtime — no MCP client:
+
+- **GBrain** (`garrytan/gbrain`, the gstack-ecosystem tool): full contract fit,
+  driven via the existing `gbrain` CLI chokepoint (`lib/gbrain-exec.ts`). Native
+  primitive is document-by-slug (put/delete/get/export) PLUS a repo axis
+  (`sources add`/`sync`). Advertises all seven capabilities. **Recommended
+  first.**
+- **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.
+- **Graphify** (`github.com/Graphify-Labs/graphify`, YC-backed): local
+  tree-sitter code graph via the `graphify` CLI. `graphify <dir>` builds
+  `graphify-out/graph.json`; `graphify query "<q>"` 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.
+
+**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,
+not to a half-baked in-house index).
+
+### Integration surfaces (no MCP needed)
+
+Each provider exposes a runtime-drivable surface, so gstack drives them with a
+CLI shell-out or plain HTTP — it never speaks MCP:
+
+- **GBrain / Graphify: CLI.** Shell out (`spawnSync`), same shape and the same
+  ENOENT→`PROVIDER_UNAVAILABLE` degrade as the existing gbrain glue.
+- **Sourcebot: HTTP + a config-file edit.** `POST /api/search` for queries and a
+  JSON edit of the server's `config.json` to register a repo. `fetch` is
+  injectable so tests run against a stub, no live server.
+
+Sourcebot and Graphify also ship MCP servers for in-agent use; the contract does
+not depend on them, because their CLI/HTTP surfaces are enough to index and
+search from the runtime.
+
+## Picker: recommend GBrain first
+
+`lib/code-intelligence/picker.ts` + `selection.ts`. The user picks a provider
+with `gstack-code-intelligence select <provider>`, persisted to
+`$GSTACK_HOME/code-intelligence.json`. `resolveSelectedProvider()` constructs the
+selected provider, or returns `null` when nothing is selected — the provider-OFF
+path, where callers degrade to grep / the file-only decision store. Availability
+is proven at call time: a selected provider whose CLI/server is absent throws
+`PROVIDER_UNAVAILABLE`, which callers catch and degrade on.
+
+`RECOMMENDED_ORDER` is the static **GBrain → Sourcebot → Graphify** fact — GBrain
+is always recommended first. `detectAvailable()` probes each provider for the
+`options`/`status` display (GBrain via the real `localEngineStatus()`; Graphify
+via its CLI/graph presence; Sourcebot via an HTTP liveness probe). The picker
+never silently prefers a non-recommended tool.
+
+## How this replaces the current GBrain glue
+
+The contract is the seam; the bespoke glue collapses onto it. Mapping:
+
+| Today (bespoke) | Under the contract |
+|-----------------|--------------------|
+| `bin/gstack-gbrain-sync.ts` (`sync`/`reindex-code`/`sources`) | `provider.registerSource` / `provider.refresh` |
+| `lib/gstack-decision-semantic.ts` `semanticRecall` | `provider.search` (scoped) → same degrade-to-null |
+| `bin/gstack-brain-context-load.ts` (`query`/`list_pages`) | `provider.search` / `provider.status` |
+| `bin/gstack-memory-ingest.ts` (`import`, put) | `provider.add` (optional cap; GBrain-only) |
+| `lib/gbrain-sources.ts` (`ensureSourceRegistered`, `probeSource`) | GBrain adapter internals |
+| `lib/gbrain-local-status.ts` | GBrain adapter availability probe (kept, reused) |
+| `bin/gstack-gbrain-detect` / `-install` / `-source-wireup` / `-repo-policy` | provider setup + picker + consent (thinner) |
+
+The point is not to delete 17k LOC in one commit — it is to make every consumer
+call the contract, then retire the bespoke paths provider-by-provider behind it.
+Consumers that only need "search my code, or degrade" stop importing gbrain
+specifics entirely.
+
+## Rollout
+
+Phased, each phase independently revertable. Skill-template edits are deferred to
+a later phase precisely so the first slices do not trigger the
+`gen:gstack2` / parity re-baseline cycle.
+
+- **Phase 1 (this slice): the contract, three real adapters, and a usable CLI.**
+  `contract.ts` + fully-drivable GBrain (CLI), Graphify (CLI), and Sourcebot
+  (HTTP + config) adapters + the selection store + the `gstack-code-intelligence`
+  CLI (`options`/`status`/`select`/`consent`/`index`/`search`) + tests. A user
+  can select a provider and index/search their repo today. No skill-template or
+  generated-file changes yet, so no `gen:gstack2` / parity re-baseline.
+- **Phase 2: route internal consumers through the contract.** Point
+  `gstack-decision-semantic` and `gstack-brain-context-load` at
+  `resolveSelectedProvider()`, preserving degrade-to-null exactly. Behavior-neutral
+  for the file-only paths.
+- **Phase 3: surface selection in the skills.** Offer the picker at the moments a
+  skill would benefit from indexed search, mirroring the `context` command's
+  just-in-time consent prompt. Regenerate skills (`bun run gen:gstack2`), re-run
+  `bun run test:gstack2`, re-baseline parity intentionally.
+- **Phase 4: retire bespoke glue.** Once every consumer is on the contract,
+  delete the sync/ingest/cache entrypoints and their tests provider-by-provider.
+
+## What this does NOT change
+
+Per the GStack 2 canonical contract and CLAUDE.md boundaries: no cloud browsers,
+no alternate iOS drivers, no local image models, no provider marketplaces, no
+workflow engines, **no new state database**. Context.dev remains the only
+newly-authorized external service for web context; this contract governs code
+intelligence, a separate axis. The existing decision store and Context Recovery
+stay file-only and provider-independent.
+
+## Testing
+
+`test/code-intelligence.test.ts` (19 tests, no live tools): capability-matrix
+invariants (all providers advertise the four required; only GBrain advertises the
+document ops; `local` flags, including loopback-vs-remote Sourcebot); the result
+parsers; the selection store + per-repo consent + provider-OFF (`null`); consent
+gating (GBrain non-local without consent throws `PROVIDER_NOT_CONSENTED`; local
+Graphify is exempt); the GBrain adapter against a fake `gbrain` shim; the Graphify
+adapter against a fake `graphify` shim (index builds a graph, search returns hits,
+status counts nodes); the Sourcebot adapter against an injected `fetch` + a temp
+`config.json` (register writes a local git connection, search maps `files[]` to
+hits); and every adapter degrading to `PROVIDER_UNAVAILABLE` when its tool/server
+is absent. The `gstack-code-intelligence` CLI was smoke-tested end-to-end:
+select → consent gate → local Graphify index (5-node graph) → search.
@@ -0,0 +1,187 @@
+/**
+ * code-intelligence/contract — the OPTIONAL, repo-oriented provider contract.
+ *
+ * gstack does not maintain a home-grown indexer. It defines this small contract
+ * and external providers (GBrain, Sourcebot, Graphify) implement it. The whole
+ * contract is OPTIONAL: when no provider is available/consented,
+ * `resolveCodeProvider()` returns null and callers degrade to grep / the
+ * file-only decision store. Never a dependency, always an enhancement — the same
+ * reliability contract as lib/gstack-decision-semantic.ts.
+ *
+ * Repo-oriented, not document-store (settled): register_source / refresh /
+ * search / status are required; add / delete / export are optional capabilities
+ * a provider MAY advertise. A document-CRUD-required contract would misrepresent
+ * whole-repo code-search and code-graph tools. See
+ * docs/designs/CODE_INTELLIGENCE_PROVIDER_CONTRACT.md.
+ */
+
+export type CodeProviderId = "gbrain" | "sourcebot" | "graphify";
+
+export type CodeProviderCapability =
+  | "register_source"
+  | "refresh"
+  | "search"
+  | "status"
+  | "add"
+  | "delete"
+  | "export";
+
+export const REQUIRED_CAPABILITIES: readonly CodeProviderCapability[] = [
+  "register_source",
+  "refresh",
+  "search",
+  "status",
+] as const;
+
+export const OPTIONAL_CAPABILITIES: readonly CodeProviderCapability[] = [
+  "add",
+  "delete",
+  "export",
+] as const;
+
+export interface RepoRef {
+  /** Source id the provider registers this repo under. */
+  id: string;
+  /** Local worktree path. */
+  path: string;
+  /** Remote URL, when the provider clones/manages it. */
+  remoteUrl?: string;
+}
+
+export interface SourceRef {
+  id: string;
+}
+
+export interface SourceStatus {
+  id: string;
+  state: "registered" | "indexing" | "ready" | "absent" | "unknown";
+  /** Pages / files / graph nodes, when the provider reports a count. */
+  itemCount?: number;
+  detail?: string;
+  /** True when the provider only implements a partial status probe. */
+  partial?: boolean;
+}
+
+export interface CodeSearchHit {
+  /** Slug, file path, or symbol id — whatever the provider keys results on. */
+  ref: string;
+  score?: number;
+  snippet?: string;
+  kind?: "document" | "file" | "symbol" | "graph-node";
+}
+
+export interface OpOptions {
+  /**
+   * Env override for spawned processes. Production callers leave this unset;
+   * tests inject a synthetic env (fake CLI on PATH). Matches the existing
+   * gbrain helpers.
+   */
+  env?: NodeJS.ProcessEnv;
+  /** Timeout in ms for the underlying op. */
+  timeout?: number;
+  /**
+   * Explicit per-repo consent that repo content may leave the machine. Required
+   * for non-local providers on register_source / refresh / add.
+   */
+  consented?: boolean;
+}
+
+export interface SearchOptions extends OpOptions {
+  /** Restrict to a registered source. */
+  source?: string;
+  limit?: number;
+  minScore?: number;
+}
+
+export interface CodeProvider {
+  readonly id: CodeProviderId;
+  readonly label: string;
+  readonly capabilities: ReadonlySet<CodeProviderCapability>;
+  /** True when no repo content leaves the machine (Graphify). */
+  readonly local: boolean;
+
+  has(capability: CodeProviderCapability): boolean;
+
+  registerSource(repo: RepoRef, opts?: OpOptions): Promise<SourceStatus>;
+  refresh(source: SourceRef, opts?: OpOptions): Promise<SourceStatus>;
+  search(query: string, opts?: SearchOptions): Promise<CodeSearchHit[]>;
+  status(source?: SourceRef, opts?: OpOptions): Promise<SourceStatus>;
+
+  add?(doc: { slug: string; body: string }, opts?: OpOptions): Promise<SourceStatus>;
+  delete?(slug: string, opts?: OpOptions): Promise<SourceStatus>;
+  export?(source: SourceRef, opts?: OpOptions): Promise<string>;
+}
+
+export const CODE_PROVIDER_FAILURES = Object.freeze([
+  "PROVIDER_UNAVAILABLE",
+  "PROVIDER_NOT_CONSENTED",
+  "CAPABILITY_UNSUPPORTED",
+  "SOURCE_NOT_REGISTERED",
+  "PROVIDER_TIMEOUT",
+  "PROVIDER_ERROR",
+] as const);
+
+export type CodeProviderFailure = (typeof CODE_PROVIDER_FAILURES)[number];
+
+const FAILURE_SET = new Set<string>(CODE_PROVIDER_FAILURES);
+
+/**
+ * Typed provider failure. Mirrors runtime/context.js ContextError discipline:
+ * the code set is closed and the constructor throws on an unknown code, so a
+ * typo can never mint an untyped failure.
+ */
+export class CodeProviderError extends Error {
+  readonly code: CodeProviderFailure;
+  readonly providerId?: CodeProviderId;
+
+  constructor(code: CodeProviderFailure, message: string, providerId?: CodeProviderId) {
+    if (!FAILURE_SET.has(code)) throw new TypeError(`Unknown code-provider failure code: ${code}`);
+    super(message);
+    this.name = "CodeProviderError";
+    this.code = code;
+    this.providerId = providerId;
+  }
+}
+
+/**
+ * Enforce that a provider advertises every required capability. Called by each
+ * adapter constructor so an incomplete provider fails fast, not at first search.
+ */
+export function assertRequiredCapabilities(
+  id: CodeProviderId,
+  capabilities: ReadonlySet<CodeProviderCapability>,
+): void {
+  const missing = REQUIRED_CAPABILITIES.filter((cap) => !capabilities.has(cap));
+  if (missing.length) {
+    throw new TypeError(`Code provider ${id} is missing required capabilities: ${missing.join(", ")}`);
+  }
+}
+
+/**
+ * Guard for optional ops: throw CAPABILITY_UNSUPPORTED (never a silent no-op)
+ * when a provider is asked for a capability it does not advertise.
+ */
+export function assertCapability(provider: CodeProvider, capability: CodeProviderCapability): void {
+  if (!provider.has(capability)) {
+    throw new CodeProviderError(
+      "CAPABILITY_UNSUPPORTED",
+      `${provider.label} does not support "${capability}"`,
+      provider.id,
+    );
+  }
+}
+
+/**
+ * Repo-scoped egress consent gate. Non-local providers must not move repo
+ * content off the machine without explicit per-repo consent. Local providers
+ * (nothing leaves the machine) are exempt.
+ */
+export function assertEgressConsent(provider: CodeProvider, opts?: OpOptions): void {
+  if (provider.local) return;
+  if (opts?.consented === true) return;
+  throw new CodeProviderError(
+    "PROVIDER_NOT_CONSENTED",
+    `${provider.label} would send repo content off this machine; per-repo indexing consent is required`,
+    provider.id,
+  );
+}
@@ -0,0 +1,198 @@
+/**
+ * GBrain adapter — full contract fit over the existing gbrain CLI chokepoint.
+ *
+ * Reuses lib/gbrain-exec.ts (spawnGbrain, seeded DATABASE_URL) and
+ * lib/gbrain-sources.ts (ensureSourceRegistered, probeSource, sourcePageCount)
+ * rather than re-issuing raw commands, so the DATABASE_URL / GBRAIN_HOME /
+ * Windows-shim guarantees carry over unchanged. GBrain's native primitive is
+ * document-by-slug (put/delete/get/export) PLUS a repo axis (sources add/sync),
+ * so it advertises all seven capabilities.
+ */
+
+import { spawnGbrain } from "../gbrain-exec";
+import { ensureSourceRegistered, probeSource, sourcePageCount } from "../gbrain-sources";
+import {
+  assertCapability,
+  assertEgressConsent,
+  assertRequiredCapabilities,
+  CodeProviderError,
+  type CodeProvider,
+  type CodeProviderCapability,
+  type CodeSearchHit,
+  type OpOptions,
+  type RepoRef,
+  type SearchOptions,
+  type SourceRef,
+  type SourceStatus,
+} from "./contract";
+
+const CAPABILITIES: CodeProviderCapability[] = [
+  "register_source",
+  "refresh",
+  "search",
+  "status",
+  "add",
+  "delete",
+  "export",
+];
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * Parse `gbrain search` text output (`[score] slug -- snippet`) into hits.
+ * gbrain's search prints text, not JSON (verified in
+ * lib/gstack-decision-semantic.ts). Exported for deterministic unit testing.
+ */
+export function parseGbrainSearch(stdout: string, minScore: number, limit: number): CodeSearchHit[] {
+  const hits: CodeSearchHit[] = [];
+  for (const line of stdout.split("\n")) {
+    const m = line.match(/^\[([\d.]+)\]\s+(\S+)\s+--\s+(.*)$/);
+    if (!m) continue;
+    const score = parseFloat(m[1]);
+    if (!Number.isFinite(score) || score < minScore) continue;
+    hits.push({ ref: m[2], score, snippet: m[3].trim(), kind: "document" });
+  }
+  return hits.slice(0, limit);
+}
+
+export class GbrainProvider implements CodeProvider {
+  readonly id = "gbrain" as const;
+  readonly label = "GBrain";
+  readonly capabilities = new Set<CodeProviderCapability>(CAPABILITIES);
+  /** GBrain federates into a (possibly remote) DB, so content can leave the machine. */
+  readonly local = false;
+
+  constructor() {
+    assertRequiredCapabilities(this.id, this.capabilities);
+  }
+
+  has(capability: CodeProviderCapability): boolean {
+    return this.capabilities.has(capability);
+  }
+
+  async registerSource(repo: RepoRef, opts: OpOptions = {}): Promise<SourceStatus> {
+    assertEgressConsent(this, opts);
+    try {
+      const result = await ensureSourceRegistered(repo.id, repo.path, {
+        federated: true,
+        env: opts.env,
+      });
+      return {
+        id: repo.id,
+        state: result.state.status === "match" ? "registered" : "unknown",
+        detail: result.changed ? "registered" : "already registered",
+      };
+    } catch (err) {
+      throw this.#wrap(err);
+    }
+  }
+
+  async refresh(source: SourceRef, opts: OpOptions = {}): Promise<SourceStatus> {
+    assertEgressConsent(this, opts);
+    this.#assertOk(spawnGbrain(["sync", "--strategy", "code", "--source", source.id], {
+      baseEnv: opts.env,
+      timeout: opts.timeout ?? DEFAULT_TIMEOUT_MS,
+    }));
+    return this.status(source, opts);
+  }
+
+  async search(query: string, opts: SearchOptions = {}): Promise<CodeSearchHit[]> {
+    if (!query.trim()) return [];
+    const args = ["search", query];
+    if (opts.source) args.push("--source", opts.source);
+    const r = spawnGbrain(args, { baseEnv: opts.env, timeout: opts.timeout ?? DEFAULT_TIMEOUT_MS });
+    this.#assertOk(r);
+    return parseGbrainSearch(r.stdout || "", opts.minScore ?? 0.1, opts.limit ?? 10);
+  }
+
+  async status(source?: SourceRef, opts: OpOptions = {}): Promise<SourceStatus> {
+    if (!source) {
+      // No source given: liveness probe. `sources list` reachable = ready.
+      this.#assertOk(spawnGbrain(["sources", "list", "--json"], {
+        baseEnv: opts.env,
+        timeout: opts.timeout ?? DEFAULT_TIMEOUT_MS,
+      }));
+      return { id: "*", state: "ready" };
+    }
+    try {
+      const probed = probeSource(source.id, opts.env);
+      if (probed.status === "absent") return { id: source.id, state: "absent" };
+      const count = sourcePageCount(source.id, opts.env);
+      return {
+        id: source.id,
+        state: "ready",
+        itemCount: count ?? undefined,
+        detail: probed.registered_path,
+      };
+    } catch (err) {
+      throw this.#wrap(err);
+    }
+  }
+
+  async add(doc: { slug: string; body: string }, opts: OpOptions = {}): Promise<SourceStatus> {
+    assertCapability(this, "add");
+    assertEgressConsent(this, opts);
+    const r = spawnGbrain(["put", doc.slug, "--body", doc.body], {
+      baseEnv: opts.env,
+      timeout: opts.timeout ?? DEFAULT_TIMEOUT_MS,
+    });
+    this.#assertOk(r);
+    return { id: doc.slug, state: "ready" };
+  }
+
+  async delete(slug: string, opts: OpOptions = {}): Promise<SourceStatus> {
+    assertCapability(this, "delete");
+    this.#assertOk(spawnGbrain(["delete", slug, "--yes"], {
+      baseEnv: opts.env,
+      timeout: opts.timeout ?? DEFAULT_TIMEOUT_MS,
+    }));
+    return { id: slug, state: "absent" };
+  }
+
+  async export(source: SourceRef, opts: OpOptions = {}): Promise<string> {
+    assertCapability(this, "export");
+    const r = spawnGbrain(["export", "--source", source.id], {
+      baseEnv: opts.env,
+      timeout: opts.timeout ?? DEFAULT_TIMEOUT_MS,
+    });
+    this.#assertOk(r);
+    return r.stdout || "";
+  }
+
+  /**
+   * Throw a typed failure unless the spawn succeeded. Distinguishes a missing
+   * CLI (ENOENT → PROVIDER_UNAVAILABLE, the degrade signal) from a timeout
+   * (ETIMEDOUT/SIGTERM, status=null) and a real non-zero exit.
+   */
+  #assertOk(r: {
+    status: number | null;
+    stderr?: string;
+    error?: Error & { code?: string };
+    signal?: NodeJS.Signals | null;
+  }): void {
+    if (r.status === 0) return;
+    const stderr = (r.stderr || "").trim();
+    if (r.error?.code === "ENOENT" || /command not found/.test(stderr)) {
+      throw new CodeProviderError("PROVIDER_UNAVAILABLE", "gbrain CLI not on PATH", this.id);
+    }
+    if (r.error?.code === "ETIMEDOUT" || r.signal === "SIGTERM") {
+      throw new CodeProviderError("PROVIDER_TIMEOUT", "gbrain timed out", this.id);
+    }
+    if (/not configured|Cannot connect to database|config\.json/.test(stderr)) {
+      throw new CodeProviderError("PROVIDER_UNAVAILABLE", stderr || "gbrain not configured", this.id);
+    }
+    throw new CodeProviderError("PROVIDER_ERROR", stderr || `gbrain exited ${r.status}`, this.id);
+  }
+
+  #wrap(err: unknown): CodeProviderError {
+    if (err instanceof CodeProviderError) return err;
+    const message = err instanceof Error ? err.message : String(err);
+    if (/not on PATH|command not found/.test(message)) {
+      return new CodeProviderError("PROVIDER_UNAVAILABLE", message, this.id);
+    }
+    if (/not configured/.test(message)) {
+      return new CodeProviderError("PROVIDER_UNAVAILABLE", message, this.id);
+    }
+    return new CodeProviderError("PROVIDER_ERROR", message, this.id);
+  }
+}
@@ -0,0 +1,14 @@
+/**
+ * code-intelligence — the OPTIONAL, repo-oriented provider contract.
+ * See docs/designs/CODE_INTELLIGENCE_PROVIDER_CONTRACT.md.
+ */
+
+export * from "./contract";
+export { GbrainProvider, parseGbrainSearch } from "./gbrain-adapter";
+export { SourcebotProvider, GraphifyProvider } from "./mcp-adapters";
+export {
+  recommendCodeProvider,
+  resolveCodeProvider,
+  RECOMMENDED_ORDER,
+  type PickerOptions,
+} from "./picker";
@@ -0,0 +1,43 @@
+/**
+ * Picker — recommends a code-intelligence provider, GBrain first.
+ *
+ * RECOMMENDED_ORDER is the static "GBrain first" fact the options UX and phase-2
+ * resolution filter against. In phase 1 only GBrain is drivable from the runtime
+ * (it has a CLI the runtime can spawn); Sourcebot and Graphify are MCP tools in
+ * the host session and become resolvable in phase 2 once a host transport is
+ * wired. So recommendCodeProvider returns GBrain-or-nothing today, and
+ * resolveCodeProvider degrades to null — the provider-OFF path — when GBrain is
+ * unavailable. Callers then use grep / the file-only decision store.
+ *
+ * GBrain availability uses the real detector, localEngineStatus() ("ok"/"timeout"
+ * are usable). Graphify is NEVER auto-installed or auto-offered.
+ */
+
+import { localEngineStatus, type LocalEngineStatus } from "../gbrain-local-status";
+import { GbrainProvider } from "./gbrain-adapter";
+import type { CodeProvider, CodeProviderId } from "./contract";
+
+/** Recommendation order — GBrain first. Sourcebot/Graphify join in phase 2. */
+export const RECOMMENDED_ORDER: readonly CodeProviderId[] = ["gbrain", "sourcebot", "graphify"];
+
+export interface PickerOptions {
+  env?: NodeJS.ProcessEnv;
+  /** Inject GBrain status for tests; otherwise probed via localEngineStatus(). */
+  gbrainStatus?: LocalEngineStatus;
+}
+
+const GBRAIN_USABLE: ReadonlySet<LocalEngineStatus> = new Set(["ok", "timeout"]);
+
+/** Drivable providers, in recommendation order (GBrain first). */
+export function recommendCodeProvider(opts: PickerOptions = {}): CodeProvider[] {
+  const status = opts.gbrainStatus ?? localEngineStatus({ env: opts.env });
+  return GBRAIN_USABLE.has(status) ? [new GbrainProvider()] : [];
+}
+
+/**
+ * The single recommended provider, or null when none is drivable. Null is the
+ * provider-OFF path: callers MUST degrade to grep / file-only, never fail.
+ */
+export function resolveCodeProvider(opts: PickerOptions = {}): CodeProvider | null {
+  return recommendCodeProvider(opts)[0] ?? null;
+}
@@ -0,0 +1,218 @@
+/**
+ * Tests for lib/code-intelligence — the OPTIONAL, repo-oriented provider contract.
+ *
+ * Load-bearing properties:
+ *  - Every provider advertises the four required capabilities; optional ops are
+ *    declined with a typed CAPABILITY_UNSUPPORTED, never a silent no-op.
+ *  - Sourcebot/Graphify are phase-1 capability declarations: they prove contract
+ *    fit and throw PROVIDER_UNAVAILABLE until a host MCP transport is wired.
+ *  - The picker recommends GBrain first and resolves to null (provider-OFF) when
+ *    GBrain is unavailable.
+ *  - Non-local providers refuse to move repo content off the machine without
+ *    explicit per-repo consent (PROVIDER_NOT_CONSENTED).
+ *  - The GBrain adapter works end-to-end against a fake `gbrain` shim on PATH.
+ *  - Missing CLI degrades (PROVIDER_UNAVAILABLE), never crashes.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import {
+  assertRequiredCapabilities,
+  CodeProviderError,
+  REQUIRED_CAPABILITIES,
+  GbrainProvider,
+  SourcebotProvider,
+  GraphifyProvider,
+  parseGbrainSearch,
+  recommendCodeProvider,
+  resolveCodeProvider,
+  RECOMMENDED_ORDER,
+} from "../lib/code-intelligence";
+
+describe("capability matrix invariants", () => {
+  test("every provider advertises the four required capabilities", () => {
+    for (const p of [new GbrainProvider(), new SourcebotProvider(), new GraphifyProvider()]) {
+      for (const cap of REQUIRED_CAPABILITIES) expect(p.has(cap)).toBe(true);
+    }
+  });
+
+  test("GBrain advertises all seven (document axis)", () => {
+    const g = new GbrainProvider();
+    for (const cap of ["add", "delete", "export"] as const) expect(g.has(cap)).toBe(true);
+    expect(g.local).toBe(false);
+  });
+
+  test("Sourcebot is search-only: declines add/delete/export", () => {
+    const s = new SourcebotProvider();
+    expect(s.has("add")).toBe(false);
+    expect(s.has("delete")).toBe(false);
+    expect(s.has("export")).toBe(false);
+    expect(s.local).toBe(false);
+  });
+
+  test("Graphify is local, exports, declines add/delete", () => {
+    const g = new GraphifyProvider();
+    expect(g.local).toBe(true);
+    expect(g.has("export")).toBe(true);
+    expect(g.has("add")).toBe(false);
+    expect(g.has("delete")).toBe(false);
+  });
+
+  test("assertRequiredCapabilities rejects an incomplete provider", () => {
+    expect(() => assertRequiredCapabilities("sourcebot", new Set(["search"]))).toThrow(/missing required/);
+  });
+
+  test("CodeProviderError rejects an unknown failure code", () => {
+    // @ts-expect-error deliberately invalid code
+    expect(() => new CodeProviderError("NOPE", "x")).toThrow(/Unknown code-provider failure/);
+  });
+});
+
+describe("optional ops decline with a typed failure", () => {
+  test("Sourcebot declines add/delete/export with CAPABILITY_UNSUPPORTED", async () => {
+    const s = new SourcebotProvider();
+    await expect(s.add({ slug: "x", body: "y" })).rejects.toMatchObject({ code: "CAPABILITY_UNSUPPORTED" });
+    await expect(s.delete("x")).rejects.toMatchObject({ code: "CAPABILITY_UNSUPPORTED" });
+    await expect(s.export({ id: "x" })).rejects.toMatchObject({ code: "CAPABILITY_UNSUPPORTED" });
+  });
+
+  test("Graphify advertises export → not CAPABILITY_UNSUPPORTED, but unwired in phase 1", async () => {
+    await expect(new GraphifyProvider().export({ id: "x" })).rejects.toMatchObject({ code: "PROVIDER_UNAVAILABLE" });
+  });
+});
+
+describe("phase-1 declaration adapters degrade to PROVIDER_UNAVAILABLE", () => {
+  test("Sourcebot.search is unwired until a transport lands", async () => {
+    await expect(new SourcebotProvider().search("q")).rejects.toMatchObject({ code: "PROVIDER_UNAVAILABLE" });
+  });
+
+  test("empty query short-circuits to no hits (no throw)", async () => {
+    expect(await new SourcebotProvider().search("   ")).toEqual([]);
+  });
+
+  test("status is partial + unknown (no live probe yet)", async () => {
+    const s = await new GraphifyProvider().status({ id: "repo" });
+    expect(s).toMatchObject({ id: "repo", state: "unknown", partial: true });
+  });
+});
+
+describe("egress consent gate", () => {
+  test("non-local registerSource without consent → PROVIDER_NOT_CONSENTED", async () => {
+    await expect(new SourcebotProvider().registerSource({ id: "repo", path: "/repo" })).rejects.toMatchObject({
+      code: "PROVIDER_NOT_CONSENTED",
+    });
+  });
+
+  test("local provider (Graphify) skips the egress gate (falls through to unwired)", async () => {
+    // Local means nothing leaves the machine, so consent is not required — it
+    // reaches the phase-1 PROVIDER_UNAVAILABLE, NOT a consent rejection.
+    await expect(new GraphifyProvider().registerSource({ id: "repo", path: "/repo" })).rejects.toMatchObject({
+      code: "PROVIDER_UNAVAILABLE",
+    });
+  });
+});
+
+describe("parseGbrainSearch (text surface)", () => {
+  const sample = ["[0.91] slug/a -- snippet one", "banner", "[0.05] slug/b -- below floor"].join("\n");
+  test("parses scored lines, applies floor + limit", () => {
+    expect(parseGbrainSearch(sample, 0.1, 10)).toEqual([
+      { ref: "slug/a", score: 0.91, snippet: "snippet one", kind: "document" },
+    ]);
+    expect(parseGbrainSearch(sample, 0.0, 1)).toHaveLength(1);
+  });
+});
+
+describe("picker — recommend GBrain first", () => {
+  test("RECOMMENDED_ORDER puts GBrain first", () => {
+    expect(RECOMMENDED_ORDER[0]).toBe("gbrain");
+    expect([...RECOMMENDED_ORDER]).toEqual(["gbrain", "sourcebot", "graphify"]);
+  });
+
+  test("GBrain resolves when usable", () => {
+    expect(recommendCodeProvider({ gbrainStatus: "ok" }).map((p) => p.id)).toEqual(["gbrain"]);
+    expect(resolveCodeProvider({ gbrainStatus: "ok" })?.id).toBe("gbrain");
+  });
+
+  test("timeout status counts as usable (engine slow, not absent)", () => {
+    expect(resolveCodeProvider({ gbrainStatus: "timeout" })?.id).toBe("gbrain");
+  });
+
+  test("provider-OFF: GBrain down → resolveCodeProvider null", () => {
+    expect(recommendCodeProvider({ gbrainStatus: "no-cli" })).toEqual([]);
+    expect(resolveCodeProvider({ gbrainStatus: "no-cli" })).toBeNull();
+    expect(resolveCodeProvider({ gbrainStatus: "missing-config" })).toBeNull();
+  });
+});
+
+describe("GBrain adapter end-to-end (fake shim on PATH)", () => {
+  let binDir: string;
+  let homeDir: string;
+
+  function writeShim(body: string): void {
+    const p = path.join(binDir, "gbrain");
+    fs.writeFileSync(p, body, { mode: 0o755 });
+    fs.chmodSync(p, 0o755);
+  }
+  function env(): NodeJS.ProcessEnv {
+    return { PATH: `${binDir}:${process.env.PATH}`, HOME: homeDir };
+  }
+
+  beforeEach(() => {
+    binDir = fs.mkdtempSync(path.join(os.tmpdir(), "ci-gbrain-shim-"));
+    homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "ci-gbrain-home-"));
+  });
+  afterEach(() => {
+    fs.rmSync(binDir, { recursive: true, force: true });
+    fs.rmSync(homeDir, { recursive: true, force: true });
+  });
+
+  test("search scopes to source and parses hits", async () => {
+    writeShim(`#!/usr/bin/env bash
+if [ "$1" = "search" ]; then
+  if printf '%s ' "$@" | grep -q -- "--source code"; then
+    echo "[0.88] src/x.ts -- match in code source"
+  else
+    echo "[0.10] wrong -- unscoped"
+  fi
+  exit 0
+fi
+exit 1
+`);
+    const hits = await new GbrainProvider().search("where", { env: env(), source: "code" });
+    expect(hits).toHaveLength(1);
+    expect(hits[0].ref).toBe("src/x.ts");
+  });
+
+  test("status(source) reports ready + page_count", async () => {
+    writeShim(`#!/usr/bin/env bash
+if [ "$1" = "sources" ]; then echo '{"sources":[{"id":"code","local_path":"/repo","page_count":42}]}'; exit 0; fi
+exit 1
+`);
+    const s = await new GbrainProvider().status({ id: "code" }, { env: env() });
+    expect(s.state).toBe("ready");
+    expect(s.itemCount).toBe(42);
+  });
+
+  test("status(source) reports absent for an unregistered id", async () => {
+    writeShim(`#!/usr/bin/env bash
+if [ "$1" = "sources" ]; then echo '{"sources":[]}'; exit 0; fi
+exit 1
+`);
+    expect((await new GbrainProvider().status({ id: "nope" }, { env: env() })).state).toBe("absent");
+  });
+
+  test("missing CLI degrades to PROVIDER_UNAVAILABLE", async () => {
+    // No shim written; PATH points only at an empty dir.
+    await expect(
+      new GbrainProvider().search("q", { env: { PATH: binDir, HOME: homeDir } }),
+    ).rejects.toMatchObject({ code: "PROVIDER_UNAVAILABLE" });
+  });
+
+  test("registerSource requires egress consent (GBrain is non-local)", async () => {
+    await expect(
+      new GbrainProvider().registerSource({ id: "code", path: "/repo" }, { env: env() }),
+    ).rejects.toMatchObject({ code: "PROVIDER_NOT_CONSENTED" });
+  });
+});