@backbencher/brain 0.0.0-stage → 0.1.0

package/docs/tools/bb_health.md

@@ -0,0 +1,156 @@
+<!--
+Author: Muhammad Ishaq Khan
+
+WHAT THIS DOCUMENT IS — the generated reference for bb_health: contract, input schema, returns, examples, errors, limitations, performance, safety and evidence semantics.
+WHO IT IS FOR — callers of bb_health through any MCP host, the CLI (`bb tool bb_health`), or a library.
+EDIT TOGETHER WHEN THIS CHANGES — src/mcp/tools/bb_health/descriptor.ts, src/mcp/tools/bb_health/handler.ts, script/tool-docs/curation/bb_health.ts; regenerate with `npx tsx script/verify-tool-docs.ts --only bb_health --write`.
+-->
+# `bb_health`
+
+Unified index health: file/symbol/relationship/imports counts, embedding model + coverage, schema version, runtime, file freshness, what this call cost, and (when asked) the integrity battery, analysis-history totals and index completeness. There is no `mode` parameter: a call reports status, and `refresh`/`force` select the one behaviour that mutates the index. The default output names WHY each file was classified: `freshness why` separates fresh-verified-by-content-hash from fresh-verified-by-mtime+size-only (the file was not read), and names content-changed, deleted-from-disk, unreadable and unindexed separately, because those need different fixes and a single 'N stale' number is not actionable. Every report carries a top-level `healthy` boolean on the tool result (and inside the JSON payload when history=true): false exactly when the report contains an error-severity finding; a broken index is a successful REPORT, not a tool error (isError stays false), while wrong input is refused with isError. Options the chosen call cannot honour are refused: `limit` needs history=true; `wait` needs refresh/force; `sampleSize` belongs to sampled freshness only. Use verbose=true for a per-language breakdown, PER-LANGUAGE SEARCHABILITY (the share of each language's symbols a semantic query can reach — a language at 0% is invisible to bb_ask), the embedded/unembedded symbol kinds and stale-file names; verbose=true is also the only call that runs the per-symbol embedding aggregates, so a default call is bounded by the file count, not the symbol count. integrity=true runs the index integrity check battery, which NAMES each non-ok check with its remediation; with the default sampled freshness the battery falls back to a COMPLETE disk pass over the indexed files (it content-hashes files whose metadata changed), so it is materially more expensive than a status call. freshness="complete" (not a `complete` option) checks every indexed file instead of a sample; includeAnalysisRuns=true adds persisted run/finding totals; history=true answers with a JSON object { health, history, healthy } instead of the text report and is the only caller of `limit` (minimum 1, default 20). checkUnindexed=true walks the project and reports files the indexer would index but the index does not contain — a stat per eligible file, opt-in because a default call must not silently acquire a walk. refresh=true reindexes before reporting (`wait` defaults true; wait=false detaches it and the NEXT call reports the outcome once, success or failure); force=true wipes and rebuilds first and is DESTRUCTIVE. Freshness defaults to a DETERMINISTIC sample spread across the whole index: `stale` is then a lower bound on the project, not a total, and the report says so — pass freshness="complete" when you need the exact count.
+
+## Contract
+
+- Category: `lifecycle`
+- Mutability: `read`
+- Requires index: `false`
+- Modes: `status`, `refresh`
+- Planned modes (roadmap, not executable): (none)
+- Defaults: `{"verbose":false,"history":false,"limit":20,"refresh":false,"force":false,"wait":true,"freshness":"sampled","sampleSize":200,"integrity":false,"includeAnalysisRuns":false}`
+
+## Input Schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "verbose": {
+      "type": "boolean",
+      "description": "include the per-language breakdown, per-language searchability, embedded/unembedded symbol kinds, embedding config/chain and stale/missing file names (default false). This is the only value that runs the per-symbol embedding aggregates; a default call skips them so it stays bounded by the file count"
+    },
+    "history": {
+      "type": "boolean",
+      "description": "return persisted analysis history (default false). CHANGES THE OUTPUT SHAPE: this mode answers with a JSON object { health, history, healthy } instead of the text report, so a caller must not parse the text form when asking for it; the result also carries the same top-level `healthy` boolean as the text form"
+    },
+    "limit": {
+      "type": "number",
+      "description": "analysis-history page size (default 20); must be a whole number >= 1 and is only read when history=true — supplying it without history is REFUSED"
+    },
+    "refresh": {
+      "type": "boolean",
+      "description": "reindex the project before reporting"
+    },
+    "force": {
+      "type": "boolean",
+      "description": "force a full in-place reindex before reporting — DESTRUCTIVE: the index is wiped before it is rebuilt, so a failure leaves it empty"
+    },
+    "wait": {
+      "type": "boolean",
+      "description": "applies to refresh/force only (default true; supplying it without refresh/force is REFUSED). wait=false detaches the rebuild and returns the current snapshot; the NEXT call reports the detached outcome once — completion as well as failure"
+    },
+    "freshness": {
+      "type": "string",
+      "enum": [
+        "sampled",
+        "complete"
+      ],
+      "description": "freshness mode (default sampled — a deterministic, unbiased sample spread over every indexed file, NOT the first N; freshness=\"complete\" checks every indexed file and makes the stale count exact)"
+    },
+    "sampleSize": {
+      "type": "number",
+      "description": "freshness sample count (default 200); must be a whole number >= 1 and applies to freshness=\"sampled\" only — supplying it together with freshness=\"complete\" is REFUSED"
+    },
+    "integrity": {
+      "type": "boolean",
+      "description": "run the index integrity check battery (14 checks, each named with its remediation when not ok). Cost: with the default sampled freshness the battery performs a COMPLETE disk pass over the indexed files (content-hashing those whose metadata changed), so this is the most expensive opt-in"
+    },
+    "includeAnalysisRuns": {
+      "type": "boolean",
+      "description": "add persisted analysis run/finding totals (full-table counts, not a page length)"
+    },
+    "paths": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "report the state of these project-relative files INSTEAD of a project-wide freshness answer — for the question an agent actually has after an edit, at O(files named) rather than O(project). At most 50, no duplicates, no blank entries. The answer is a SEPARATE self-describing block, so every other number in the report stays project-wide and the two can never be read as one. Each path is FIVE-state, not a boolean: fresh (indexed, on disk, unchanged), stale (content changed), gone (indexed, no longer readable on disk — `reason` distinguishes file-gone from unreadable), NOT-INDEXED (on disk, the indexer has not run since it appeared — a freshness verdict here would be meaningless), or absent (no such path). Paths that resolve outside the project, or through a symlink out of it, are REFUSED and reported as unchecked rather than answered"
+    },
+    "checkUnindexed": {
+      "type": "boolean",
+      "description": "WALK the project and report files on disk that the indexer would index but the index does NOT contain — the direction freshness cannot see (freshness reports files IN the index and gone from disk). Costs a stat per eligible file, i.e. the discovery phase of an index run, so it is opt-in. Uses the INDEXER'S OWN discovery rules, so gitignored files, node_modules, unsupported extensions and >5MB files are correctly NOT counted, and the output names that population. Without this option, index completeness is not asserted at all"
+    }
+  }
+}
+```
+
+## Returns
+
+- Counts (files, symbols, relationships, imports, syntax-error files), schema version, runtime, embedding model/coverage and a `freshness` block that states whether it checked a SAMPLE or the whole index
+- The freshness reason mix per file (content-changed, deleted, unreadable, unindexed) and, on verbose, the bounded stale/missing file names
+- When `paths` is given: a separate five-state block (fresh / stale / gone / not-indexed / absent) for exactly those files, while every other number stays project-wide
+- When `checkUnindexed` is given: files on disk the indexer would index but the index does not contain, with the population named
+- When `integrity` is given: the integrity checks with their status and remediation, naming each non-ok check rather than only a score
+- When `includeAnalysisRuns` is given: persisted run/finding totals as full-table counts; `history` instead answers with JSON `{ health, history, healthy }`
+- A `healthy` boolean on the result (and inside the history JSON): false exactly when the report contains an error-severity finding
+
+## Examples
+
+`{"verbose":true}`
+
+`{"history":true,"limit":5}`
+
+`{"refresh":true,"wait":false}`
+
+`{"force":true}`
+
+`{"integrity":true}`
+
+`{"freshness":"complete"}`
+
+`{"includeAnalysisRuns":true}`
+
+`{"paths":["src/mcp/server.ts"]}`
+
+`{"checkUnindexed":true}`
+
+## Errors
+
+- An option the selected behaviour cannot honour: `limit` without `history=true`, `wait` without `refresh`/`force`, `sampleSize` with `freshness="complete"` — each refused with the accepted form named
+- Invalid values: unknown `freshness`, `sampleSize` below 1, a non-integer `limit` (and `limit: 0` with `history=true`)
+- `paths` problems: an empty list, more than 50 entries, duplicate entries, blank entries, or a path that escapes the project (directly or through a symlink)
+- An index that cannot be opened read-only is reported as an EMPTY_INDEX error finding, not as a tool failure: a broken index is a successful report
+
+## Limitations
+
+- Sampled freshness (the default) is a deterministic sample, so `stale` is a LOWER BOUND on the project, not a total; `freshness="complete"` is the exact census
+- A `fresh` verdict reached through the mtime+size fast path never read the file: a same-size edit that preserves the mtime reads fresh (the same trade-off as git's stat-cache)
+- Embedding coverage reports stored vectors, not semantic quality or retrieval accuracy; verbose=true is what joins it to per-language searchability
+- `integrity: true` with the default sampled freshness performs a COMPLETE disk pass over the indexed files, and `checkUnindexed: true` walks the project — both are opt-in precisely because a default call must not acquire them
+- The default call does not run the per-symbol embedding aggregates (per-language symbol counts, searchable-by-language, embedded/unembedded kinds, provider chain); those run only for verbose=true, which is what keeps a default answer bounded by file count rather than symbol count
+- No `mode` parameter exists: a call reports status, and `refresh`/`force` are the only behaviours selected by flags
+
+## Performance
+
+Measured warm through the MCP door on the campaign checkout: a default call answers in about 0.8 s p50 / 0.9 s p95 on the workspace index (6,452 files / 310,423 symbols / 3.6 GB), and about 2.6 s p50 / 3.3 s p95 on a 1,283,638-symbol copy of that index; the first call after a cold start measured 8.3 s and 25.3 s respectively on those two indexes. The 5-file polyglot fixture measures ~53 ms p50 and the 100-file synthetic fixture ~35 ms p50 through the same code path. `verbose=true` adds the per-symbol embedding aggregates, `integrity=true` adds a complete disk pass, `freshness="complete"` hashes/indexes every file, and `checkUnindexed=true` adds a project walk — all opt-in and declared for that reason.
+
+## Safety
+
+A status call is read-only: the index is opened through the driver's read-only mode, so no migrations, healers or WAL writes run. refresh=true and force=true are the only index mutations and are explicit: refresh reindexes, force WIPES the index before rebuilding and is destructive; wait=false detaches a rebuild and the next call reports its outcome once. `healthy:false` never means the tool failed — the report is the answer.
+
+## Evidence Semantics
+
+Counts, schema version and embedding rows are measured from the brain database; freshness compares indexed metadata with the filesystem and names the reason per file, separating content-verified fresh verdicts from mtime+size fast-path ones; integrity results are computed from stored rows and disk state; sampled answers declare that they are samples. `brain_index_status` counters are labelled when they describe the last index RUN rather than the index itself.
+
+## Relationship to other tools
+
+For index size/counts use `bb index status` (CLI) or the stats surface; this tool reports index health, freshness, completeness and integrity.
+
+## Deep guides
+
+- [Index health and freshness](../BB_HEALTH.md)
+
+## Staleness
+
+Freshness applies to the tool's read output (no registered per-mode split). Staleness surfaces as: a top-level `freshness` block on every report (`{ mode, requestedMode, checked, total, fresh, stale, missing, staleFiles, missingFiles, unresolved, isComplete, reasons }`) — `mode` is what was actually CHECKED, `isComplete` is the boolean to branch on before reading `stale` as a project total, `unresolved` is counted as neither fresh nor stale, and `reasons` carries the verdict mix (`{ byKind, freshVerifiedByContent, freshVerifiedByMetadata, isSample }`) so a consumer can tell a content-hash-verified file from an `mtime+size` fast-path one without reading the prose. `paths` answers per-path state for named files; `verbose` adds the stale/missing file NAMES. It does not auto-refresh on a read: the report DESCRIBES the index and a reindex happens only when asked for (`refresh: true` reindexes before reporting, `force: true` wipes and rebuilds first and is destructive, `wait: false` detaches it), so a stale report is a measurement, not a repair. When the report names stale or missing files, repair them with the manual interface: run: `bb index --changed` (or the `bb_index` tool with the project path — incremental, changed files only), or pass `paths` to check named files instead of scanning the project. Detection uses a mtime+size fast path with a content-hash fallback: an edit that leaves both size and mtime unchanged is reported fresh without hashing (same trade-off as git's index stat-cache; accepted, documented in `src/brain/freshness.ts`).
+
+This page is generated from the executable registry and curated documentation. Run `npm run docs:generate` to update it, or `npx tsx script/verify-tool-docs.ts --only <tool> --write` for a single page.

package/docs/tools/bb_impact.md

@@ -0,0 +1,117 @@
+<!--
+Author: Muhammad Ishaq Khan
+
+WHAT THIS DOCUMENT IS — the generated reference for bb_impact: contract, input schema, returns, examples, errors, limitations, performance, safety and evidence semantics.
+WHO IT IS FOR — callers of bb_impact through any MCP host, the CLI (`bb tool bb_impact`), or a library.
+EDIT TOGETHER WHEN THIS CHANGES — src/mcp/tools/bb_impact/descriptor.ts, src/mcp/tools/bb_impact/handler.ts, script/tool-docs/curation/bb_impact.ts; regenerate with `npx tsx script/verify-tool-docs.ts --only bb_impact --write`.
+-->
+# `bb_impact`
+
+Bounded reverse-dependency impact for one symbol via the same component the editor graph panel uses: declared node budget (200) and depth (5), truncation as a first-class field with reason, and a declared total that is the size of the set the answer is a prefix of — measured, not inferred, so an answer that is short of the whole set says so even when no bound fired. Unknown symbols are loud declared errors — an empty impact set is never invented. Owner-cascade applies: impact includes dependents attributed at class level, not only exact-symbol rows. The relationship kinds that count are named in every answer's `rule.relationshipTypes` and can be overridden; a dependent carries its evidence tier, cross-language flag, bridge and position.
+
+## Contract
+
+- Category: `graph`
+- Mutability: `read`
+- Requires index: `true`
+- Modes: `impact`
+- Planned modes (roadmap, not executable): (none)
+- Defaults: `{}`
+
+## Input Schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "symbol": {
+      "type": "string",
+      "description": "symbol name to compute impact for (`target`/`symbolName`/`query` are accepted as aliases)"
+    },
+    "relationshipTypes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "stored relationship kinds to count as dependencies. Default: calls, instantiates, extends, implements. A kind that is not listed is never reported, and the applied list is echoed in `rule.relationshipTypes` on every answer. This is the same control bb_graph has, so a caller who wants the type-level `uses`/`references` rows can ask for them on either door."
+    },
+    "file": {
+      "type": "string",
+      "description": "optional defining-file hint for a symbol NAME that several stored symbols carry — the same server-resolved identity the editor's hover sends as `file`. Accept the stored project-relative path, or an absolute path ending in it. It must identify the symbol: a hint that does not is REFUSED with a named error, never silently ignored and never silently relabelled to another same-named copy. Ambiguous MEMBER names (constructors, members outside the graph's root types) resolve through their owning declaration at the hinted file; for a traversable name the walk roots where the graph engine resolves it, and a hint naming another copy is refused rather than answered. Omit it for unique names."
+    },
+    "refresh": {
+      "type": "boolean",
+      "description": "set false to skip the bounded staleness repair and answer from the existing index. When omitted, stale files inside the answer are repaired and the walk is re-run so the answer is not built from the rows the refresh replaced."
+    }
+  },
+  "required": [
+    "symbol"
+  ]
+}
+```
+
+## Returns
+
+- The rule the answer was MEASURED under, in `rule`: which relationship kinds count as dependencies (the applied list is echoed here on every answer), the owner-cascade, the noise policy, and the depth cap. The set and the declared total are measurements of this same list
+- The declared limits, from the component that owns them: `budget` (node budget 200, depth cap 5, the three work ceilings the declared total is computed under, and the two WALL-CLOCK deadlines — `walkTimeCeilingMs` for the engine walk and `callDeadlineMs` for the component's own work) and `traversal` (depth actually reached, the engine's own truncation state and reason, its per-query site limit, its capped-query count, its returned caller rows, and the root's uncapped caller count when computable). `maxDepth` is an EXPANSION cap: direct dependents are `depth: 0`, so the deepest dependent the engine can report is `maxDepth - 1` (4), and the depth cap is shared by the completeness measurement, so a declared total is the total UNDER that cap
+- Whether the set is the WHOLE truth or a prefix of a larger one, and how that was established: whenever truncation was declared or the walk reached the last expandable depth, the returned set is measured against an unbounded walk of the same rule, and a prefix is declared when the two disagree. `countVerification` carries `ran`, `skipped`, `timedOut`, `boundarySuspect` and `complete` — `complete: true` means the measurement proved the returned set IS the whole truth (an ENGINE row cap may still have fired on the way; it is then published in `traversal.engineTruncated`, because a row cap that dropped only duplicate call sites of an already-counted dependent hides no dependent), `false` means a prefix or a declared unknown, and `null` means no measurement was bought because the set is complete by construction (shallow walk, no bound fired)
+- Downstream dependents of the symbol with per-edge evidence tiers and confidence, cross-language flags, bridge mechanism, and each dependent's own position. Every one of those describes ONE stored row, and `evidenceAtDepth` says which path that row is on: `depth` is the MEASURED shortest path, while the graph engine walks depth-first and stamps the first trace, so the two can name different rows (measured across nine repositories before this was fixed: 340 of 4 258 rows, 7.98%). The evidence is re-read at the reported depth, and where no row can be attributed every evidence field is null rather than quoted from a longer path
+- How the requested name became the root it walked: `rootMatch` carries the name asked for, whether the match was exact, an `exact-exempt-kind` hit (the name matched EXACTLY and unambiguously but the kind — an enum variant, a constant, a plain field — is outside the graph whitelist, so the walk is the one every other root gets and nothing was substituted), a containment match, or the member→owner substitution, and how many stored symbols carry that exact name. An ambiguous traversable name is ANSWERED about the copy the engine resolves, with `rootMatch.nameMatches` disclosing the ambiguity; an ambiguous member name is refused unless a `file` hint identifies its owning declaration
+- How each dependent is a dependent, per row, in `via`: `exact` (the stored row names the symbol asked about), `member` (it names one of its members — the owner cascade working as declared, with the member named in `viaMember`), or `range-folded` (it names neither, and the row is in the answer only because the cascade RANGE widened). `cascade` is the composition of the returned set by those three, or `null` when the index refused the member lookups it needs to establish it
+- `directCount` — the number of DIRECT dependents (depth 0), or `null` when the completeness measurement hit a declared ceiling, was refused, stopped on its clock, or was skipped because the walk had already spent the call's wall-clock deadline. `totalCountIfKnown` is the transitive total under the same rule, or `null` for the same declared unknowns. Neither is ever smaller than `shownCount`; when the measurement proves the set complete they equal it
+- `file` — an optional defining-file hint for a name several stored symbols carry. For a member name (a constructor, or a member the graph cannot root) it resolves the walk through the MEMBER'S OWNING DECLARATION at that file and the result says so in `resolution`. For a traversable name the walk roots where the graph engine resolves the name, and the hint is a REFUSAL input: it either identifies that copy or the answer is a named error, never a silent relabel to another copy
+- Freshness: a per-dependent `stale` flag (`true`/`false`, or `null` when the file is not in the index at all) and a summary `freshness` envelope; `rootStale` declares the root's own file separately, since a stale root with fresh dependents is still a stale answer. Stale files inside the answer are repaired within budget and the walk is re-run, declared in `autoRefresh`; `refresh=false` opts out
+- Loud declared errors instead of fabricated empty sets: an unknown symbol, an ambiguous member name with no usable hint, a hint that does not identify the symbol, an empty `relationshipTypes` list, and the option refusals the shared validator raises are all named errors with `isError` set
+
+## Examples
+
+`{"symbol":"handleRequest"}`
+
+## Errors
+
+- Missing symbol
+- Symbol not found in the index — a declared error, never an empty impact set that would read as "nothing depends on this"
+- The requested NAME is an ambiguous MEMBER name (a constructor or a kind outside the graph's root types) and no usable `file` hint was given. The error lists the candidate copies with file and line (bounded to 8, plus a count of the rest) and names the `file` option as the remediation
+- A `file` hint that does not identify the symbol — an unknown path, or a path naming a different copy than the symbol the walk would root at — is refused with a named error instead of being ignored or answered about another copy
+- `relationshipTypes` given as an empty list: refused rather than silently re-read as the engine's default kind set (an empty rule matches nothing, and the engine would substitute its default)
+- The root resolves to a non-traversable kind AND is not the symbol that was asked for — a gravity pick, a containment match, or a re-root through an owner. The graph whitelist exists so a request is never answered about a DIFFERENT symbol, and that is the only case left where it applies
+- An option this tool does not accept, or a value of the wrong type, is rejected by the shared tool validator with the accepted options named
+
+## Limitations
+
+- Static impact analysis cannot establish runtime behavior: it reads stored relationship rows, not executed calls
+- The depth cap is an EXPANSION cap. Direct dependents are `depth: 0`, the deepest reported dependent is `maxDepth - 1` (4), and the completeness measurement shares that cap — so a declared total is the total under the declared depth, and a chain deeper than the cap keeps a declared `caller-depth-cap-reached` truncation rather than claiming a bounded set is the whole truth
+- The engine's row bounds are not truncations of the DEPENDENT SET: a per-query call-site limit, a per-traversal caller budget and a total-edge cap drop ROWS. When the measurement proves the returned set complete, those bounds stay visible in `traversal.engineTruncated` / `engineTruncationReason` and `truncated` stays false — the set is whole even though the engine stopped emitting rows
+- When the completeness measurement cannot finish — 50 000 scanned rows, 2 000 expansions, its own circuit breaker, or the call deadline — `totalCountIfKnown` and `directCount` are BOTH `null` (a declared unknown), `countVerification` says whether it timed out or was skipped for the deadline, `reproducible: false` is published, and the truncation reason names it. The clock is the one bound that is a property of the machine rather than the index, so it is always declared rather than inferred
+- The walk is bounded in WALL TIME by a declared deadline (`budget.walkTimeCeilingMs`): the graph engine applies no clock of its own, so this tool asks for one, and a walk that reaches it is a SAMPLE — declared with `truncated`, a truncation reason naming `walk-time-budget-exhausted`, the engine's returned/uncapped counts in `traversal`, and `reproducible: false`. It is the honest response to a hub whose answer would otherwise run past the tool's 5 s budget, not a hidden cut
+- Latency depends on the index's planner state as well as on its size. Two index shapes were measured and fixed: the owner-range index made the walk's owner-cascade lookup cheap, and the counting walk's level query is now a FLAT target-id list rather than `IN(subquery over ids OR owner ranges)` — the old form could not use the target index and took 4 349 ms for ONE level-1 batch where the flat form returns the same rows in 4.1 ms. With both fixes plus the declared deadlines, a real hub (`getRawInstance`, the case that breached 5 s) answers in p50 2 424–2 805 ms / p95 2 450–3 148 ms across two baseline-protocol series (3 measured runs after one warm-up) and p95 3 029 ms over eight warm runs — measured byte-read-only, index files byte-identical after. The fixture tiers are the regression baselines (see Performance)
+- Owner-cascade attribution applies: dependents through class-member relationships are attributed to the owner class. The cascade RANGE is a strict SUPERSET of the owner relation — it never loses a dependent the owner relation has, but it folds in siblings of a member: ripgrep `RegexMatcher` answered 21 dependents of which 7 were `range-folded` and 0 were real members. `cascade.rangeFolded` counts those rows, so the over-count is visible instead of silent
+- A `file` hint cannot select a DIFFERENT copy of a traversable name: the graph engine roots by name (gravity-ordered), and the hint can only confirm that copy or refuse. Member names are the case the hint resolves, through their owning declaration
+- `relationshipTypes` is not validated against the index's stored-kind vocabulary: a misspelled kind is measured as an empty set with `truncated: false`, and `rule.relationshipTypes` echoes the misspelling so the mistake is auditable rather than disguised as "no dependents"
+- Reflects the index as of the last index run; the freshness envelope and the per-dependent `stale` flags state how far that is from the files on disk
+
+## Performance
+
+Warm, five-run measurements on the three declared tiers, with the exact commands and raw runs in validation/tools/bb_impact/LATENCY.json. All three tiers are inside budget on the current index. Fixture tiers: p50 83.8 ms / p95 100.8 ms on test/fixtures/polyglot/ts-js and p50 176.5 ms / p95 243.5 ms on the 100-file synthetic scale fixture, both default-argument calls. Reference large index (.bb-data, 11,440 files, ~3.4 GB, measured through the tool's byte-read-only open with the index's own files hashed before and after, `dbUnchanged: true`): per-symbol p95 was 327.7 ms for the widest studied hub (`join`), 321.2 ms for `named`, 236.0 ms for `refReachable` and 153.6 ms for `computeImpact` — every measured call stayed inside the 5 s budget, and p50s were 42.9–284.2 ms. The walk's per-symbol caller query is planned through `brain_symbol_project_owner_idx` for the owner range and `brain_rel_proj_type_target_idx` for the relationship filter, so the cost is index-bounded. The HUB case is measured too, because it is the one that breached the budget: default `{symbol:"getRawInstance"}` on the reference index answered p50 2 424–2 805 ms / p95 2 450–3 148 ms across two baseline-protocol series (one warm-up, three measured runs each) and p95 3 029 ms over eight warm runs — all inside the 5 000 ms budget, with the answer declaring its walk clock (`traversal.walkTimeExhausted`), its measured total (`totalCountIfKnown`) and its completeness state. Before the fix the same call measured p50 6 337 / p95 6 539 ms; the cause was ONE counting statement that could not use the target index (4 349 ms), not the walk. One correction belongs on the record: an earlier campaign measurement on THIS index returned 13.7–359.5 s for default calls, and a hand-built comparison attributed it to the engine's owner-cascade JOIN form (10,351 ms against 12.5 ms for a flat target-indexed form). That measurement predates the owner-range index and the planner state now on disk; re-measured byte-read-only on the current index, the same JOIN form answers in 1.1 ms and the walk in 40–63 ms. The absolute millisecond figures belong to the machine, so the fixture-tier numbers are the regression baselines this tool holds.
+
+## Safety
+
+Read-only. It does not modify source files or index data. Staleness repair, when it runs, reindexes changed files through the shared bounded auto-refresh budget and never rewrites source.
+
+## Evidence Semantics
+
+Impact derives from brain_relationship rows through the same graph engine the editor impact panel uses. The returned set is the engine's caller traversal under the declared dependency kinds, owner cascade, noise policy and depth; the declared total is an INDEPENDENT bounded walk under exactly that rule, so it is the size of the set the answer is a prefix of. Completeness is PROVED rather than inferred: whenever truncation was declared or the walk reached the last expandable depth, the set is measured against an unbounded walk of the same rule, so an answer that is short of the whole truth says so even when no bound fired (measured: cobra `HasAvailableFlags` answers 28 with `truncated: true` instead of 27 with `truncated: false`), and an engine row cap that hides no dependent no longer masquerades as a truncation. Evidence lives in validation/tools/bb_impact/ (AUDIT.md, LATENCY.json, probes, latency-t2-query-cost.json) and in the gate evidence of the three verifiers named below.
+
+## Relationship to other tools
+
+This is the bounded-impact specialist; `bb_analyze` mode `impact` aggregates the same canonical walk with file-level risk — the numbers are identical by gate.
+
+## Deep guides
+
+- [Impact: budgets, completeness and the wall clock](../BB_IMPACT.md)
+
+## Staleness
+
+Freshness modes (registered as `freshnessModes`): `impact`. Staleness surfaces as: per-dependent `stale` flag (three states: `true`/`false`, or `null` when the file is not in the index at all), the root's own `rootStale`, and a `freshness` envelope (`{ fresh, stale, missing, staleRatio, mode, remediation }`). Stale files inside the answer are repaired within budget and the walk is re-run, declared in `autoRefresh`; `refresh=false` opts out. When something is stale/missing, the remediation names the registered reindex interfaces: project scope → `reads auto-refresh stale files within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index --changed (or the bb_index tool with the project path — incremental, changed files only)`; file scope → `reads auto-refresh this file within budget when enabled — disable with BB_NO_AUTO_REFRESH=1 or refresh=false; manual repair: run: bb index "<file>" (or the bb_index tool with that file path)`. Nothing is stale → silence (no remediation text). Detection uses a mtime+size fast path with a content-hash fallback: an edit that leaves both size and mtime unchanged is reported fresh without hashing (same trade-off as git's index stat-cache; accepted, documented in `src/brain/freshness.ts`).
+
+This page is generated from the executable registry and curated documentation. Run `npm run docs:generate` to update it, or `npx tsx script/verify-tool-docs.ts --only <tool> --write` for a single page.

package/docs/tools/bb_index.md

@@ -0,0 +1,108 @@
+<!--
+Author: Muhammad Ishaq Khan
+
+WHAT THIS DOCUMENT IS — the generated reference for bb_index: contract, input schema, returns, examples, errors, limitations, performance, safety and evidence semantics.
+WHO IT IS FOR — callers of bb_index through any MCP host, the CLI (`bb tool bb_index`), or a library.
+EDIT TOGETHER WHEN THIS CHANGES — src/mcp/tools/bb_index/descriptor.ts, src/mcp/tools/bb_index/handler.ts, script/tool-docs/curation/bb_index.ts; regenerate with `npx tsx script/verify-tool-docs.ts --only bb_index --write`.
+-->
+# `bb_index`
+
+Reindex a file or directory so the index reflects edits immediately (agent-fresh). Accepts a path (file or dir); a file reindexes only that file, a dir runs an incremental index of that dir (changed files only). mode=post re-runs the heavy derived-data phases (relationships/enrichment/gravity/taints/health) WITHOUT re-parsing — the remediation after edits on incremental paths. Every mode requires `path`, and it MUST resolve inside this project: an absolute path elsewhere, a `../` traversal, a foreign directory and a symlink inside the project pointing out of it are all REFUSED, because an out-of-tree file would be stored with a `relative_path` that is not relative to anything and every scoped query, file name and freshness check for it would then be wrong. For mode=post the path must additionally NOT be a file: the phases are project-wide, so pass the project root (or a directory inside it). The report says what happened rather than only how much: `outcome` is `indexed`, `partial` or `no-op`; a no-op carries a `reason` that distinguishes "nothing changed: the file already matches the index (mtime, size and sha256 agree)" from "this file holds nothing the indexer extracts", and `unchanged`/`declined`/`skipped` say how many files fell into each case. When errors occurred, `errorDetail` names the file and the message beside the `errors` count, and `walCheckpointed` says whether the write WAL was reclaimed after the run. Paths in the report are PROJECT-RELATIVE, so the same request returns the same bytes on any machine. The counts are stable between identical calls; the `ms` fields are measured wall-clock and are expected to vary.
+
+## Contract
+
+- Category: `operations`
+- Mutability: `write`
+- Requires index: `false`
+- Modes: `auto`, `file`, `dir`, `post`
+- Planned modes (roadmap, not executable): (none)
+- Defaults: `{"mode":"auto"}`
+
+## Input Schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "path": {
+      "type": "string",
+      "description": "Project-relative file (reindex only that file) or directory (incremental index of changed files); for mode=post, the project root or a directory inside it whose derived phases should be re-run (a file path is refused). REQUIRED in every mode and checked rather than ignored. Must resolve INSIDE the project: both sides are resolved through realpath, so a symlink inside the project pointing out of it is refused too."
+    },
+    "mode": {
+      "type": "string",
+      "enum": [
+        "auto",
+        "file",
+        "dir",
+        "post"
+      ],
+      "description": "auto (default) infers file vs dir from path; file reindexes one file (unchanged files answer no-op instead of being re-parsed); dir runs an incremental directory index; post re-runs derived phases (relationships/taints/health) without re-parsing"
+    }
+  },
+  "required": [
+    "path"
+  ]
+}
+```
+
+## Returns
+
+- `indexed`, `deleted`, `errors`, `unchanged`, `declined` and `skipped` counts for the refreshed path
+- The mode actually applied (`auto` resolves to `file` or `dir`; `file`/`dir`/`post` are reported as named)
+- `outcome` — `indexed`, `partial`, or `no-op`. A no-op also carries `reason`, and the two reasons are different facts: "nothing changed" (mtime, size and sha256 all still match the stored row) versus "this file holds nothing the indexer extracts" (an extension the indexer does not parse)
+- `errorDetail`: the file and the message for each failure, beside the `errors` count
+- `walCheckpointed`: whether the write-ahead log was reclaimed after the run (a refused checkpoint — another reader holding a snapshot — reports false, never success)
+- For mode=dir, `candidates` (files the walk found changed) beside `processed`, so a partial dir index is visible as a count, and `unchanged: true` when the tree is settled
+- For mode=post, the per-phase report (relationships, enrichment, gravity, taint, health, integrity, planner stats, vector blobs, analysis) with each phase's timing and outcome, `totalMs`, and the post-run `integrityHealth` score
+
+## Examples
+
+`{"path":"src/new-file.ts"}`
+
+`{"path":"src","mode":"dir"}`
+
+`{"path":".","mode":"post"}`
+
+## Errors
+
+- Missing or blank path
+- A path that resolves OUTSIDE the project — an absolute path elsewhere, a `../` traversal, a foreign directory, or a symlink inside the project pointing out of it — for file, dir, auto AND post mode
+- mode=post with a path that does not exist, or with a FILE path: the post pass re-derives project-wide phases, so it takes the project root (or a directory inside it)
+- mode=file on a directory, or mode=dir on a file
+- Unknown mode, or an option this tool does not accept (the refusal names the accepted set)
+- Another LIVE indexer holding the project lock; the refusal names the holder's pid, host and start time, and the remedy. A lock whose holder is dead, a lock naming no process once it is older than the grace window, and a foreign-host lock past its 24h expiry are reclaimed automatically
+
+## Limitations
+
+- A file reindex updates only that file's evidence; cross-file relationships are repaired within the bounded post-pass for the touched files (see `derived.pass`), while callers in unrelated files can lag until the next dir or full index
+- Dir mode reuses the incremental indexer: unchanged files are skipped by design, a settled tree answers `unchanged: true`, and a file the walk's skip rules exclude is left untouched in the index rather than being treated as deleted — an index row is deleted only when the file is genuinely gone from disk
+- File mode's `no-op` is a real no-op: an unchanged file is detected by mtime+size and confirmed by comparing the stored sha256 with the bytes on disk, so a repeated call does not re-parse (and does not pay a parse's latency)
+- The COUNTS in a report are stable between identical calls; the `ms` fields are measured wall-clock and DO vary, so a diff of two reports will show timing drift
+- Dir mode walks with the indexer's own skip rules; a directory that the indexer excludes from DISCOVERY (build output, dependency trees) is not revisited by an incremental dir walk. The walk's skip list matches discovery's for the names that matter here — `vendor` is indexed, because it is first-party source in Go and in repositories that curate code under src/vendor
+- A reindex does not run the full derived pipeline: `derived.pass` is `bounded` for incremental runs, and mode=post is the explicit remedy when derived data looks stale
+
+## Performance
+
+A single-file reindex is bounded by that file's parse cost plus the incremental post-pass; dir mode is bounded by the changed-file set and reports how many candidates it found against how many it processed. A no-op refresh (unchanged file or settled directory) performs no parse at all. Measured on an isolated tiny fixture, a warm file-mode call was 11.8 s when it always re-parsed and 0.0 s–0.1 s as a no-op; the parse path is dominated by worker-pool startup, not the file.
+
+## Safety
+
+Write-capable against INDEX data only — it never modifies source files, and it never deletes an index row for a file that still exists on disk. It will only index paths inside this project: both sides are resolved through realpath, so a symlink inside the project pointing out of it is refused and a symlink to a file inside it is allowed. Concurrent index runs are refused by the project index lock rather than interleaved.
+
+## Evidence Semantics
+
+Counts come from the real parse/store pipeline. The report's own assertions are checked by the m40 A1/A3 gates (post entry, write-path parity including the delete guard and the unchanged-file no-op), m43 P1 (lock), m22 E1/D3 (agent-fresh), and by real MCP stdio door probes under validation/tools/bb_index/.
+
+## Relationship to other tools
+
+The CLI twin is `bb index`. The MCP path is incremental only: `auto`/`file`/`dir` refresh changed files, `post` re-derives the heavy phases; a full rebuild is the CLI's `bb index --force`. Refresh changed files after agent edits with mode `dir`/`file` or the CLI `--changed`.
+
+## Deep guides
+
+- [Indexing guide: flags, resume, performance, troubleshooting](../indexing/README.md)
+
+## Staleness
+
+This tool does not report per-file index staleness and does not auto-refresh. Output reflects the index as of the last index run; when files changed after indexing, refresh first: run: bb index --changed (or the bb_index tool with the project path — incremental, changed files only).
+
+This page is generated from the executable registry and curated documentation. Run `npm run docs:generate` to update it, or `npx tsx script/verify-tool-docs.ts --only <tool> --write` for a single page.

package/docs/tools/bb_migrate.md

@@ -0,0 +1,135 @@
+<!--
+Author: Muhammad Ishaq Khan
+
+WHAT THIS DOCUMENT IS — the generated reference for bb_migrate: contract, input schema, returns, examples, errors, limitations, performance, safety and evidence semantics.
+WHO IT IS FOR — callers of bb_migrate through any MCP host, the CLI (`bb tool bb_migrate`), or a library.
+EDIT TOGETHER WHEN THIS CHANGES — src/mcp/tools/bb_migrate/descriptor.ts, src/mcp/tools/bb_migrate/handler.ts, script/tool-docs/curation/bb_migrate.ts; regenerate with `npx tsx script/verify-tool-docs.ts --only bb_migrate --write`.
+-->
+# `bb_migrate`
+
+Read-only single or batch migration planning with dependency order, explicit effort methodology, library mappings, risks, truncation, and unsupported cases. A request is a list of entries (symbol names, indexed symbol ids, project-relative paths) unioned and capped at 100; every entry resolves to at most one component before any relationship is read, and a component named through more than one entry is planned once. Plans whose source file changed since the last index are flagged stale up front — a plan is a claim about current code; JSON output carries the freshness block.
+
+## Contract
+
+- Category: `analysis`
+- Mutability: `read`
+- Requires index: `true`
+- Modes: `plan`
+- Planned modes (roadmap, not executable): (none)
+- Defaults: `{"format":"text"}`
+
+## Input Schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "symbolName": {
+      "type": "string",
+      "description": "legacy single-symbol alias for symbolNames; when both are supplied the entries are UNIONED, never silently dropped"
+    },
+    "symbolNames": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "one or more component names; a name that matches several symbols in different files is refused with candidate ids to re-run against symbolIds. Blank entries are refused by name"
+    },
+    "paths": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "project-relative file or DIRECTORY paths (absolute paths inside the project are accepted); every indexed symbol in them joins the request, so a whole module can be planned in one call. UNION with symbolNames, not a replacement: naming a symbol AND a path that contains it plans it once. A path that matches no indexed file is refused by name"
+    },
+    "symbolIds": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "indexed symbol ids (shape `<projectId>:<relative file>:<name>:<line>`), the ONLY unambiguous way to name a component. Use this when a refusal reported that a name matches several symbols; a name is not an identity, and ids come from an earlier result's plans or an ambiguity refusal's candidates. An id no symbol carries is refused by name"
+    },
+    "targetLanguage": {
+      "type": "string",
+      "description": "e.g. rust, go, python. An unknown target is refused; a known target with no dictionary rows for the source pair is planned with the missing-data gap declared and no mapping invented. Blank is refused"
+    },
+    "format": {
+      "type": "string",
+      "enum": [
+        "text",
+        "json"
+      ],
+      "description": "output format (default text)"
+    }
+  },
+  "required": [
+    "targetLanguage"
+  ]
+}
+```
+
+## Returns
+
+- Dependency-ordered migration plans, grouped into parallel-workable waves, one plan per component named by the request
+- Scope completeness: how much of the cited integration surface the request actually covers
+- Cohort rollup by source file and by wave, plus the zero-indexed `cohort.wavePlan` keyed by symbol id
+- Effort methodology with its rates published as data, library mappings by provenance, and measured risks
+- Explicit unsupported entries with typed reasons (missing-symbol, ambiguous-symbol with candidate ids, same-language, unsupported-source, unsupported-target)
+- Truncation split into `deduplicated` (entries that resolved to an already-planned component) and `capped` (entries the 100-entry cap dropped, named in `cappedNames`)
+- Freshness of every plan's source file: per-plan `stale` flags, an up-front stale-plan notice in text, and the `freshness` envelope in JSON
+
+## Examples
+
+`{"symbolName":"handleRequest","targetLanguage":"go"}`
+
+`{"symbolNames":["parse","handle"],"targetLanguage":"rust","format":"json"}`
+
+`{"paths":["src/api"],"targetLanguage":"go"}`
+
+`{"symbolIds":["<projectId>:src/api/handler.ts:handleRequest:12"],"targetLanguage":"go"}`
+
+## Errors
+
+- Missing targetLanguage
+- A blank targetLanguage (refused: the tool will not resolve an empty language name)
+- No symbolName, symbolNames, symbolIds or paths
+- A blank entry in symbolNames, symbolIds or paths (refused by name: a blank entry would silently narrow the request)
+- A path that matches no indexed file (the tool says so rather than returning an empty plan set)
+- A symbol id that no indexed symbol carries (the tool names the id, because an id is the only unambiguous selector)
+- No index for the project (the tool is read-only and refuses with the `bb index` remediation rather than creating one)
+- Unknown option (the door names the accepted options)
+
+## Limitations
+
+- Plans are estimates, not translated source; the tool does not generate, replace or compile target-language code
+- Library mappings are advisory and unsupported routes remain explicit; an unmapped third-party library is named at confidence 0 and charged 6h of research, never claimed as supported
+- A library with an observed import but no registered target is reported with `target: null` and `confidence: 0` — declared absence, never an invented equivalence
+- Dependency ordering and mapping depend on the analyzer-extracted symbol and relationship graph; reflection, dynamic dispatch, or relations the grammar does not model limit the completeness of the resulting plan
+- A request names a bounded set of components, and the cited integration surface is usually much larger: measured 98.6-99.8% out of scope on the cobra corpus for requests of 1-16 symbols. The `scope` block reports this on every result
+- The dictionary carries 486 rows across 30 source languages and 21 target languages, covering 126 of the 630 possible source-to-target pairs (20%). Two keys (`flutter/material`, `shadcn/ui` — 4 of 486 rows, 0.8%) cannot be produced by import canonicalization at all; the audit enforces that class in both directions. A further 31 rows carry knowledge an import lookup can only reach through a specifier real source code does not write (API idioms such as `pool.query`, a framework name, 16 Flutter widget or type names, and display names with spaces) — they are kept, and this is their stated limit. Audited by script/m20/verify-migration-dictionary.ts
+
+## Performance
+
+Work is bounded by the request, not by repository size. A request is capped at 100 entries, and each entry resolves to at most one component before any relationship is read, so a common name cannot expand the load: on the 6,452-file / 310,423-symbol reference index a 12-name batch loaded 844 symbols and 46,753 relationships before this rule and stays inside the 5 s read-tool budget after it. `cohort.work` reports what a call actually read, and `truncation.cappedNames` names every dropped entry.
+
+## Safety
+
+Read-only, including the index open: plans are computed from a byte-read-only connection, no migrations run on a read, and the tool never creates an index. It does not generate, replace, or compile target-language source.
+
+## Evidence Semantics
+
+Dependency ordering comes from indexed relationships; effort and library mappings are labelled methodology-driven estimates, with the rates published as data. Relationship line, confidence, cross-language flag, bridge mechanism and both external endpoint names are read from the index; none is synthesized.
+
+## Relationship to other tools
+
+For dependency structure use `bb_graph`; this tool produces migration plans with declared limitations.
+
+## Deep guides
+
+- [Migration plans, ordering and honesty](../BB_MIGRATE.md)
+
+## Staleness
+
+Freshness modes (registered as `freshnessModes`): `plan`. Staleness surfaces as: per-plan `sourceFile` + `stale` flags with an up-front stale-plan notice + `freshness` envelope (`{ fresh, stale, missing, staleRatio, mode, remediation }`) on JSON. This tool does NOT auto-refresh and has no `refresh` option: the flags and the envelope DESCRIBE the index as it stands, and the repair is manual — project scope → run: `bb index --changed` (or the `bb_index` tool with the project path — incremental, changed files only); file scope → run: `bb index "<file>"` for the file the plan belongs to. Nothing is stale → silence (no remediation text). Detection uses a mtime+size fast path with a content-hash fallback: an edit that leaves both size and mtime unchanged is reported fresh without hashing (same trade-off as git's index stat-cache; accepted, documented in `src/brain/freshness.ts`).
+
+This page is generated from the executable registry and curated documentation. Run `npm run docs:generate` to update it, or `npx tsx script/verify-tool-docs.ts --only <tool> --write` for a single page.