@backbencher/brain 0.0.0-stage → 0.1.1

package/docs/indexing/embeddings.md

@@ -0,0 +1,325 @@
+# Configuring embeddings
+
+> Source of truth: the precedence resolver `resolveEmbeddingConfig`
+> (`src/config/config.ts:35-53`), the client `src/brain/semantic/openai-embed.ts`,
+> the local fallback in `src/brain/semantic/local-embed.ts`, the wizard and
+> reporter in `src/setup/`, and `docs/EMBEDDINGS.md` for retrieval semantics.
+>
+> **This document contains no API key and never will.** It references environment
+> variable *names* only. Do not commit a key to `bb.json`, to a docs file, to a
+> test fixture, or to a log.
+
+## What embeddings are for
+
+The brain stores one dense vector per indexed symbol in
+`brain_semantic_embedding`. Those vectors power `bb_ask` — natural-language
+questions. They do **not** power `bb_search`, which has no semantic mode
+(`docs/EMBEDDINGS.md` §6).
+
+Embeddings are generated **in the background after indexing**, in batches. `bb index`
+waits for that whole pipeline (active job + queued jobs + queued items), announces the
+wait, and only then reads the counts it prints — so the summary's embedding count,
+`bb stats` and `bb health` agree with the database. Before 2026-11-01 the run read the
+count first: a demo run printed `0 embeddings` over 12 stored rows and a real run
+printed 568 over 1,117, with the same run printing an error-level "holds no vectors"
+health claim. Coverage is still a per-run measurement, never a fixed product number
+(`docs/EMBEDDINGS.md` §3).
+
+## How a vector is stored
+
+Dense vectors are stored **once**, as a little-endian float32 blob
+(`embedding_blob`: `vector_dimension * 4` bytes). The `embedding_vector` text column
+holds an empty string for those rows. Storing both forms was measured on a real
+343-file repository: 28.9 MB of JSON digits beside 9.15 MB of float32 on an 84.5 MB
+index — 34% of the whole database duplicated, plus a `JSON.stringify`/`parse` pair on
+every write and read. Sparse token lists (`tfidf-v1`) keep their JSON form, and rows
+written before 2026-11-01 keep JSON with a NULL blob until a background promotion
+fills the blob; every read goes through one blob-first reader with that JSON fallback,
+so an existing index keeps answering without being rebuilt. A rebuild
+(`bb index --force`) reclaims the old JSON bytes (SQLite returns them to the file on
+the next vacuum/rebuild, not in place).
+
+## The free/local fallback: you do not need a key
+
+With no configuration at all, semantic search still works. It falls back to
+built-in local word vectors:
+
+| Property | Value |
+| --- | --- |
+| Model label | `local-word-vectors-v3` (`src/brain/semantic/engine.ts:49`) |
+| Dimensions | 50 (`WORD_DIM`, `src/brain/semantic/local-embed.ts:7`) |
+| Dependencies | none — no downloads, no model files |
+| Strength | weaker than a real embedding model; lexical similarity over project vocabulary |
+
+The label is **versioned** and the `-v3` is load-bearing: a tokenizer change makes
+old and new vectors occupy different spaces even though both are 50-dimensional,
+so the label is what lets the model-consistency guard refuse to compare them
+(`src/brain/semantic/engine.ts:38-49`). If you see `local-word-vectors` without a
+suffix anywhere in the docs, that is a bug — the constant is
+`local-word-vectors-v3`. (`describeEmbeddingChain` reports the *provider role* as
+`local word vectors` with model `local-word-vectors`, `src/brain/semantic/openai-embed.ts:514`;
+that is a provider description, not the stored label. Do not confuse the two.)
+
+`bb setup show` says so plainly when nothing is configured:
+
+```
+Winner: none — semantic search will use local vectors (weaker). Setup: bb setup
+```
+
+and `bb doctor` reports it as a warning, not a failure (`src/setup/doctor.ts:191-198`;
+the `!` glyph is the warn severity, `src/setup/doctor.ts:213`):
+
+```
+! Semantic search will use local-word-vectors-v3 (weaker).
+  Fix: bb setup
+```
+
+**This is a supported configuration, not a broken one.** It is also what CI and
+MCP hosts get by default, because they have no TTY to prompt on
+(`src/setup/setup-wizard.ts:355-370`). If you never configure anything, indexing
+still runs, `bb_ask` still answers, and it reports its own degradation rather
+than pretending.
+
+## Configure a provider
+
+### Option A — the wizard (recommended)
+
+```
+bb setup
+```
+
+It validates the endpoint with a real request before saving, maps failures to
+actionable messages (a 401 means the key was rejected, a 429 means the key is
+fine and you are rate-limited, a 404 means the model name is wrong), and writes
+`~/.bb/config.json` with mode **0600** via a temp file and an atomic rename
+(`src/setup/setup-wizard.ts:181-182`), and re-checks the mode afterwards
+(`:191-192`).
+
+`bb setup` requires an interactive terminal and exits with
+`✗ bb setup requires an interactive terminal.` otherwise
+(`src/cli/index.ts:783-786`). In a non-TTY, `bb index` never blocks: it prints a
+one-line notice instead (`src/setup/setup-wizard.ts:363-368`).
+
+### Option B — environment variables
+
+```bash
+export BB_EMBEDDING_BASE_URL="https://<your-endpoint>/v1"
+export BB_EMBEDDING_MODEL="<your-embedding-model>"
+export BB_EMBEDDING_API_KEY="<your-key>"
+```
+
+Read the key from your secret store, your shell profile, or your CI secret
+manager. Do not hardcode it.
+
+### Option C — a config file
+
+`bb.json` in the project root, or `~/.bb/config.json` globally:
+
+```json
+{
+  "embedding_base_url": "https://<your-endpoint>/v1",
+  "embedding_model": "<your-embedding-model>",
+  "embedding_api_key": "<your-key>"
+}
+```
+
+Prefer environment variables over `bb.json` for the key if the file is ever
+going to be committed. `bb.json` at the project root is the tier most likely to
+be shared with other people or checked into git.
+
+## Precedence
+
+Highest tier wins, per field, independently (`src/config/config.ts:17-24`,
+`:35-53`, `:70-81`):
+
+1. **Environment** — `BB_EMBEDDING_BASE_URL` / `BB_EMBEDDING_API_KEY` /
+   `BB_EMBEDDING_MODEL`
+2. **Config files** — explicit `BB_CONFIG_FILE` > `./bb.json` >
+   `<data-dir>/config.json` (`~/.bb/config.json` by default)
+3. **Built-in default** — `https://api.openai.com/v1` and
+   `text-embedding-3-small`
+
+Two things that surprise people:
+
+- The built-in defaults are **not** treated as "configured". A tier only counts
+  as configured when both a base URL and a model were set by env or file
+  (`configured: baseURLSrc !== "default" && modelSrc !== "default"`,
+  `src/config/config.ts:50`). Without that, an untouched install would look
+  remotely configured and would fail every request. An API key alone is not
+  enough either.
+- **`BB_CONFIG_FILE` exists** so an MCP host can point at a workspace `bb.json`
+  regardless of the process's working directory
+  (`src/config/config.ts:77`).
+
+Verify what is actually winning:
+
+```
+bb setup show
+```
+
+```
+bb — embedding configuration
+Precedence: env > ~/.bb/config.json > bb.json
+
+env:     ✓ https://<endpoint>/v1 · <model> · key: ••••<last-4>
+global:  — (not set)
+project: ✓ https://<other>/v1 · <other-model> · key: none · mode: 600
+
+Winner: env
+```
+
+Notes on that output:
+
+- The key is printed as a **fingerprint only** — the last four characters. The
+  full key is structurally absent from the rendered output
+  (`src/setup/setup-show.ts:133-168`).
+- An incomplete tier is shown with what's missing and can never win, even if it
+  appears first: the winner is the first *complete* tier in env → global →
+  project order (`src/setup/setup-show.ts:121-127`).
+- A file mode other than `600` is flagged, because the file holds a key
+  (`src/setup/setup-show.ts:153-158`).
+- `bb setup show` exits non-zero if nothing is configured
+  (`src/cli/index.ts:796`).
+
+## What is required
+
+| Field | Required? | Notes |
+| --- | --- | --- |
+| base URL | **Yes**, together with the model | Must be a `/v1`-style OpenAI-compatible base; the client posts to `<baseURL>/embeddings` (`src/brain/semantic/openai-embed.ts:207`). Trailing slashes are stripped (`src/config/config.ts:47`). A base URL that is not a usable http(s) endpoint makes `getEmbeddingConfig()` return null, so remote embeddings turn off with a debug log rather than failing every batch (`src/brain/semantic/openai-embed.ts:60-64`). |
+| model | **Yes** | Its name becomes the stored `embedding_model` label. |
+| API key | Not for the tier to be *configured*; yes for most hosted providers | The `Authorization: Bearer` header is only sent when a key is present (`src/brain/semantic/openai-embed.ts:239`). Self-hosted servers that do not authenticate can omit it. |
+| dimension | No | `embedding_dimension` in the config file, when your provider returns a fixed width (`src/brain/semantic/openai-embed.ts:56`). |
+
+Any OpenAI-compatible `/embeddings` endpoint works — OpenAI, Google, NVIDIA
+NIM, or a self-hosted vLLM / llama.cpp server. Loopback endpoints get
+`NO_PROXY`/`no_proxy` handling so a local server behind a proxy configuration is
+not unreachable: the loopback hosts `127.0.0.1`, `localhost` and `::1` are
+appended to the no-proxy set (`src/brain/semantic/openai-embed.ts:215-226`).
+
+## Diagnose with `bb doctor`
+
+```
+bb doctor
+```
+
+Read-only by default. It checks configuration presence, tier completeness, file
+permissions, model consistency against the vectors actually stored in the
+project index, and semantic degradation (`src/setup/doctor.ts:104-202`):
+
+| Finding | Severity | Glyph | Fix it prints |
+| --- | --- | --- | --- |
+| `no-config` | fail | `✗` | `bb setup` |
+| `incomplete-{env,global,project}` | fail | `✗` | `bb setup` |
+| `mode-{env,global,project}` | warn | `!` | `bb doctor --fix` |
+| `model-mismatch` | fail | `✗` | `bb index --force` |
+| `model-mixed` | warn | `!` | `bb index --force` |
+| `no-index` | info | `·` | `bb index .` |
+| `semantic-degraded` | warn | `!` | `bb setup` |
+
+That is **seven** findings, not the "four things" an earlier draft of this page
+claimed. `no-index` is informational, not a problem: it just means there are no
+stored vectors to compare against yet. `bb doctor` exits 1 when a **fail**
+finding exists (`src/setup/doctor.ts:200`, `src/cli/index.ts:815`).
+
+`bb doctor --fix` applies exactly one repair: file permissions back to `0600`,
+for at most 8 files per run (`MAX_FIX_ACTIONS`, `src/setup/doctor.ts:250`); a
+file that changed between diagnosis and `chmod` becomes a printed refusal, never
+a silent no-op (`:299-316`). It is read-only without the flag
+(`src/cli/index.ts:804-816`).
+
+## When you change the model, you must re-embed
+
+Vectors from different models occupy different vector spaces and are **never**
+compared with each other, even at the same dimension
+(`docs/EMBEDDINGS.md` §2). Changing `BB_EMBEDDING_MODEL` therefore does not
+re-embed anything; it makes every previously stored vector unusable for search.
+
+The symptom is that `bb doctor` reports (`src/setup/doctor.ts:163-168`; the
+message is one line in the source — the counts are illustrative, not measured):
+
+```
+✗ Model mismatch: config has <new-model>, index has <old-model> (412 rows). Vectors from different models cannot be compared — the stored vectors are unusable.
+  Fix: bb index --force
+```
+
+Note the `✗` glyph and the trailing `Fix:` line: the message text itself does not
+contain the fix. A doc that quotes a doctor finding without the `Fix:` line is
+quoting half of what you will see.
+
+The fix is the one it names:
+
+```
+bb index --force
+```
+
+This is the correct and only fix — a full re-index is what re-embeds. The
+storage query is what enforces the invariant: only rows whose `embedding_model`
+equals the query model **and** whose `vector_dimension` equals the query vector
+length are ever candidates.
+
+## Environment variables that control embedding behaviour
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `BB_EMBEDDING_BASE_URL` | — | OpenAI-compatible base URL. |
+| `BB_EMBEDDING_MODEL` | — | Embedding model name; becomes the stored label. |
+| `BB_EMBEDDING_API_KEY` | — | Sent as `Authorization: Bearer`. Read it from your secret store. |
+| `BB_EMBEDDING_QUEUE_LIMIT` | `25000` | Cap on queued items for the background embedder (`src/ast/parallel-indexer.ts:1821`). Beyond it, work is dropped rather than queued forever. |
+| `BB_EMBEDDING_CALL_TIMEOUT_MS` | `60000` | Bounds a single provider call, so a wedged or hanging server cannot permanently stall the drainer (`src/ast/parallel-indexer.ts:1832`). A timeout is treated as a provider failure and routed to the fallback. |
+| `BB_EMBEDDING_BATCH_LIMIT` | `50000` | A batch at or above this size is not queued for embedding at all (`src/ast/parallel-indexer.ts:1897`). |
+| `BB_EMBEDDING_CACHE_MAX` | `128` | LRU entry cap on the in-process embedding cache (`src/brain/semantic/engine.ts:157`). The cache key includes the effective model *and* endpoint, so a config change can never serve a vector from a different space. |
+| `BB_VECTOR_SCAN_CAP` | `20000` | Cap on candidate rows loaded by a semantic query (`src/intelligence/search/semantic-search.ts:15`). When hit, `provenance.truncated` is `true` and `metadata.scannedRows` reports exactly how many were read. |
+| `BB_DATA_DIR` | `~/.bb` | Where `config.json`, `status/`, `projects/` and `logs/` live (`src/util/bb-data-dir.ts:11-13`). |
+| `BB_EMBEDDING_DISABLED` | unset | Kill switch. `1`/`true`/`yes`/`on` forces local word vectors with **zero** HTTP requests (`src/brain/semantic/embedding-config.ts:91-95`). An unrecognised value counts as OFF, so a typo cannot silently disable a paid provider. |
+| `BB_EMBEDDING_TIMEOUT_MS` | `30000` | Bounds a single provider HTTP call (clamped 1 000–600 000) — `src/brain/semantic/embedding-config.ts:103`. Distinct from `BB_EMBEDDING_CALL_TIMEOUT_MS`, which bounds the indexer's drainer. |
+| `BB_EMBEDDING_MAX_INPUTS` | `256` | Ceiling on inputs per `/embeddings` request (clamped 1–2048) — `src/brain/semantic/embedding-config.ts:117`. The default is load-bearing: the indexer already chunks to 100 snippets per call, so 256 keeps every real indexing request a **single** request. |
+| `BB_EMBEDDING_DIMENSION` | unset | Declares the vector width you expect the provider to return. `src/brain/semantic/openai-embed.ts:452` REFUSES to store vectors whose width disagrees with this, because mixing widths in one index is the same defect as mixing models: search compares only one. Leave it unset unless you know the provider's real output width; if you set it wrongly, reindex with `bb index --force`. |
+| `BB_EMBEDDING_FALLBACK_BASE_URL` | unset | Second provider used when the primary fails. Must be set together with `BB_EMBEDDING_FALLBACK_MODEL` — the fallback object is built only when both are non-empty (`src/brain/semantic/embedding-config.ts:126`), and setting one without the other is reported as an error by `describeEmbeddingSetup` (`:263-270`). |
+| `BB_EMBEDDING_FALLBACK_MODEL` | unset | The fallback provider's model. See above. |
+| `BB_EMBEDDING_FALLBACK_API_KEY` | unset | The fallback provider's key. |
+| `BB_EMBEDDING_FALLBACK_RETRIES` | `2` | Retries **for the fallback provider only** (clamped 0–5) — `src/brain/semantic/embedding-config.ts:123`. See the retry-ownership note below before assuming your primary provider retries. |
+| `BB_EMBEDDING_RETRY_BASE_MS` | `250` | Exponential backoff base for those retries (clamped 10–10 000) — `:124`. |
+| `BB_EMBEDDING_RETRY_CAP_MS` | `4000` | Cap on that backoff (clamped 100–60 000) — `:125`. |
+
+### Who retries, precisely
+
+This is worth stating because getting it wrong produces a confident, false
+assurance about a provider outage:
+
+| Provider | Retries? | Where |
+| --- | --- | --- |
+| **Primary** | **No client-side retry.** One attempt per call (`src/brain/semantic/openai-embed.ts:395` passes `maxAttempts = 1`). Its resilience is the *per-batch* path in `engine.ts` (`_apiRetryAt`): the failing batch degrades to local vectors, and **later batches** try the API again. On 429 specifically there is a bounded backoff honouring `Retry-After` (`src/brain/semantic/engine.ts:315-322`). | `src/brain/semantic/openai-embed.ts:361-379` states the ownership rule |
+| **Fallback** | Yes, bounded exponential backoff, default 2 attempts. | `src/brain/semantic/openai-embed.ts:373-375`, `:441-483` |
+| **401/403/404** | Never, on either. Latched per `(baseURL, model)` for the rest of the process — one 401 is enough to know retrying will not help (`src/brain/semantic/openai-embed.ts:391-392`, `:398-409`). | — |
+
+So "indexing retries automatically" is true of a 429 and of later batches after
+a transient 5xx. It is **not** true of the failed call itself, which is not
+reissued — it degrades to local vectors, and the stored `embedding_model` for
+those rows records the local label. That is why `bb index` prints the
+`embeddings incomplete:` and multi-model warnings when it happens
+(`src/cli/index.ts:318-340`), and why `bb doctor` reports `model-mixed`.
+
+## Honest limits
+
+- **A key in a config file is a key on disk.** `bb setup` writes `0600` and
+  `bb doctor --fix` repairs the mode, but nothing stops you from committing a
+  `bb.json` to git. Use environment variables for anything shared.
+- **Coverage is volatile.** The embedding API batches and rate-limits, so one
+  run may embed a different fraction of the same corpus than the next
+  (`docs/EMBEDDINGS.md` §3). `bb health` reports what was actually measured.
+- **The query vector may not be the configured model.** The API layer can fall
+  back to local word vectors; the model that *actually produced* the last
+  vector is authoritative (`docs/EMBEDDINGS.md` §2). This is why the stored
+  label is written from the real producer.
+- **`bb_search` does not use embeddings at all.** No semantic mode exists. Any
+  documentation or UI implying otherwise is wrong.
+- **Embedding time as a share of index time is not measured.**
+  `docs/m20/PERFORMANCE-DIAGNOSTIC.md:24` explicitly declines to attribute a
+  slow run to embeddings for lack of evidence.
+
+## Related
+
+- [`../EMBEDDINGS.md`](../EMBEDDINGS.md) — vector semantics, coverage, retrieval
+  measurements, fallback reasons
+- [`README.md`](README.md) — flag semantics
+- [`performance.md`](performance.md) — where index time actually goes

package/docs/indexing/environment-variables.md

@@ -0,0 +1,77 @@
+<!--
+Author: Muhammad Ishaq Khan
+
+WHAT THIS DOCUMENT IS — the environment variables that change query-index behaviour: operational knobs, test-only injection, and per-analyzer claim flags.
+WHO IT IS FOR — an operator indexing a real project (or running the gates) who needs to know which knob is safe, which is diagnostics-only, and what each one changes.
+EDIT TOGETHER WHEN THIS CHANGES — the `process.env.BB_*` reads in src/ast/index-lock.ts, src/ast/auto-refresh.ts, src/ast/index-status.ts, src/ast/parallel-indexer.ts and their gates (script/m43/verify-a3-flag-semantics.ts, script/m40/verify-a9-purge.ts).
+-->
+
+# Environment variables that change indexing
+
+This page documents the `BB_*` knobs read by the indexer and by the language analyzers that the other
+indexing pages do not cover. Precedence, defaults and the embedding resolver are documented in
+`docs/indexing/embeddings.md`; worker/queue variables are in `docs/indexing/troubleshooting.md`; the
+resume/checkpoint variables are in `docs/indexing/resume.md`. Everything here is read by `src/`.
+
+There are three classes, and the class matters more than the name:
+
+1. **Operational knobs** — safe to set; they change cost/latency, not what the index claims.
+2. **Test-only injection** — only a gate sets these; they deliberately corrupt or freeze a run to prove
+   the failure path. Never export them in a shell that indexes a real project.
+3. **Analyzer claim flags** — default OFF and **byte-identical when off**. Each flag enables one
+   metadata claim inside one language analyzer; its lane's gate verifies the claim. Turning a flag on
+   without that gate's evidence is how a claim ships unverified.
+
+## Operational knobs
+
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `BB_DB_FLUSH_CHUNK` | `20` | Files per store-batch flush during indexing. Lowering it (e.g. `4`) bounds how long one store block can hold the event loop, at the cost of more commits; raising it amortizes commit overhead. This is a throughput/latency knob, not a correctness one. |
+| `BB_EMBEDDING_DRAIN_WAIT_MS` | `300000` | How long `bb index` waits for the background embedding queue after the index itself is complete. The wait is announced before it starts; on timeout the remaining queue count is reported and semantic search is declared partial for those symbols. Raise it for slow providers, lower it for CI. |
+| `BB_INDEX_VACUUM` | unset | `=0` disables the post-wipe `VACUUM` that `reclaimSpace` runs after a `--force` reindex. The index is correct either way; the file keeps the pages the wipe freed. Useful when a very large `--force` must finish quickly on a disk with room to spare. |
+| `BB_DEBUG_DOTTED` | unset | `=1` prints the error when `resolveDottedTargets` (dotted import-path resolution) fails. Off by design: a dotted import that cannot be resolved is a data limitation, not a crash, and must not spam every run. |
+| `BB_SQLITE_TEMP_STORE` | unset | Optional SQLite tuning: `MEMORY`/`FILE`/`DEFAULT` (or 0–2) sets the connection's `temp_store`. Off by default so a small install pays no extra memory. Measured on the apollo-server derived pass: temp_store=MEMORY + a 128 MB page cache reduced the pass 2.57 s → 2.46 s (relationships 1,449 → 1,287 ms, −11%); no full-index win was demonstrated at that corpus size, so the default is unchanged and the knob is for large databases. |
+| `BB_SQLITE_CACHE_MB` | unset | Optional per-connection page cache in MiB (1–4096), applied as `cache_size = -<n*1024>` KiB. Same experiment as above; invalid/out-of-range values are ignored rather than guessed (`script/verify-sqlite-tuning.ts`). |
+| `BB_INDEX_LOCK_GRACE_MS` | `10000` | How long an unreadable `.index.lock` (a 0-byte file from a kill between create and write, a corrupt payload, a full disk) is left alone before it is reclaimed. Inside the window nothing can prove a creator finished, so the acquire is refused; after it, no live creator can still be mid-write. |
+| `BB_INDEX_LOCK_CROSS_HOST_TTL_MS` | `86400000` (24 h) | How long a lock written by ANOTHER host is honoured before it is reclaimed. A pid from another machine means nothing locally, so it is judged by age only; lower it only on a shared data directory whose writers are known to be short-lived. |
+| `BB_STATUS_FSYNC` | unset | `=1` makes the live index-status checkpoint durable (fsync before rename) at the cost of a possible blocking fsync on every progress tick. The atomic rename already makes `kill -9` survivable; this is power-loss durability only. |
+| `BB_NO_AUTO_REFRESH` | unset | `=1` disables the inline auto-refresh that a READ path runs when it finds stale files within budget. A measurement must set this so a read never takes the index lock or writes. |
+| `BB_AUTO_REFRESH_MAX_FILES` | `25` | File-count budget for that inline repair; above it the read declines with the reason and answers from existing data with the staleness envelope. |
+| `BB_AUTO_REFRESH_MAX_BYTES` | `2097152` (2 MiB) | Byte budget for the modified files of an inline repair; above it the read declines the repair rather than stalling. |
+| `BB_INDEX_CONCURRENCY` | unset | Worker count for the parse pool, overriding the built-in plateau `max(2, min(cpus - 1, 12))`. Bounded 1–64; the CLI's `bb index --concurrency <n>` sets the same number for one run. Lower it to keep a machine responsive, raise it only when the index is truly CPU-bound. |
+
+## Test-only injection (gates only)
+
+These exist so the failure paths are exercised on purpose. They are not production features.
+
+| Variable | Used by | What it does |
+| --- | --- | --- |
+| `BB_TEST_FAIL_STORE_ONCE` | `script/perf/verify-store-failure-honesty.ts` | Makes the FIRST store batch throw. Proves a rolled-back batch is recovered, counted, and reported as an incomplete index rather than as a clean run. |
+| `BB_TEST_FAIL_STORE_ALWAYS` | `script/perf/verify-store-failure-honesty.ts` | Makes EVERY store batch throw — the full-disk case. Proves the run exits non-zero and never claims `complete`. |
+| `BB_TEST_FORCE_EDGE_RESOLVE` | edge-resolution A/B probes | Forces the legacy per-edge resolution arm of the bounded derived pass, for comparison against the current decider path. Changes derived rows by design; measurement only. |
+| `BB_TEST_SKIP_EDGE_RESOLVE` | edge-resolution A/B probes | Skips the bounded edge-resolution pass entirely, for measurement. The index is left with unresolved edges it would otherwise re-point; never use it for an index you intend to query. |
+
+Test-only variables are often read alongside `BB_TEST_HOOKS=1` (the umbrella switch documented in
+`docs/indexing/troubleshooting.md`); a run with `BB_TEST_HOOKS=1` exported can take diagnostic
+short-circuits inside MCP tool handlers and the worker fixtures.
+
+## Analyzer claim flags (default OFF, byte-identical when off)
+
+Each of these enables one **metadata claim** in one language analyzer. The analyzer's accepted output
+(the lane's D1–D6 verdict) was measured with the flag off, so off means "no change of any kind". With
+the flag on, the analyzer attaches declaration facts it can verify — never a new or suppressed row —
+and the lane's gate is responsible for checking the claim.
+
+| Variable | Analyzer | Claim it enables |
+| --- | --- | --- |
+| `BB_CPP_CITATION` | C++ | `metadata.languageNamespace` (+ strict-absent policy) on calls whose bare target is an exact committed standard-library root. |
+| `BB_CPP_PACKAGE_SCOPE` | C++ | Package-scope claims for qualified spellings, but ONLY when the caller supplies the governing manifest's package names in `context.cppPackageScopePackages`; with no package list it emits nothing. |
+| `BB_CPP_INDEX_CONSUME` | C++ | Consumes the project index's declaration facts (call provenance, heritage kind, inheritance-closed declaring base for overrides) onto rows the analyzer already emits. Requires an index whose `complete` flag is strictly true; metadata only, never a row change. |
+| `BB_DART_CITATION` | Dart | Namespace citation claims on rows whose bare target is an exact committed Dart SDK core-vocabulary name (`languageNamespace` + `"strict-absent"` policy on annotation rows and capitalized type-shaped targets). |
+| `BB_KOTLIN_IMPORT_CLAIM` | Kotlin | Imported-binding claims derived from Kotlin import declarations. |
+| `BB_PY_OWNER_MEMBER_ABSENT` | Python | Owner-member absence claims; fail-closed — without a COMPLETE project index it returns immediately, so the no-index arm is byte-identical. |
+| `BB_RUBY_INDEX_CONSUME` | Ruby | Project-index consumption (overrides verification, declared constant paths for instantiates/extends/mixes_in). Fail-closed on an absent or incomplete index; calls are deliberately not touched. |
+| `BB_JULIA_BIND_SHOW` | Julia (diagnostic) | An integer N: prints up to N one-binding key representatives while collapsing Julia bindings. This is read-only diagnostics; it does not change analyzer output. |
+
+If you are not that analyzer's gate, leave these flags alone. A claim emitted without its gate's
+evidence is exactly the failure mode these pages exist to prevent.