refactor(8.0): simplify config.vector to 3 knobs + fold persistMode (scaffold step 8)

Per user direction and BRAINY-8.0-RENAME-COORDINATION § G.2: the
`config.vector.advanced.{hnsw, diskann}` escape-hatch surface was
over-engineered. The 8.0 config surface collapses to **three knobs**:

```
config.vector = {
  recall?: 'fast' | 'balanced' | 'accurate'
  quantization?: { enabled?, bits?: 8 | 4 }
  persistMode?: 'immediate' | 'deferred'
}
```

The algorithm-internal HNSW knobs (`M`, `efConstruction`, `efSearch`,
`ml`) and DiskANN knobs (`pqM`, `searchListSize`, `alpha`, …) are no
longer exposed at the public surface. The `recall` preset covers the
legitimate quality/latency tradeoff; algorithm-internal tuning is
intentionally hidden. If users need it later, we can add it back —
shipping with too few knobs is easier to evolve than shipping with too
many.

CHANGES

src/types/brainy.types.ts
- BrainyConfig.hnswPersistMode (7.x top-level) → BrainyConfig.vector.persistMode.
- BrainyConfig.vector — dropped `advanced.{hnsw, diskann}` sub-block.
- BrainyConfig.vector.quantization — dropped `rerankMultiplier` (hardcoded to 3).
- BrainyConfig.vector — dropped `vectorStorage: 'memory' | 'lazy'`. Brainy
  always keeps vectors resident in 8.0; the lazy-eviction path was a
  cloud-storage optimisation that's no longer needed (cloud adapters are gone).
- JSDoc tightened to reflect the closed-form contract.

src/utils/recallPreset.ts
- resolveJsHnswConfig() signature narrowed: accepts `{ recall? }` only
  (no more `advanced` parameter).

src/brainy.ts
- normalizeConfig() — no longer carries `hnswPersistMode` on the resolved
  config. Dropped the deprecated 'gcs-native' warning, the gcsStorage
  HMAC-key warning, and the lenient storage-pairing block (dead code now
  that cloud adapters are gone).
- resolveHNSWPersistMode() — collapsed to a one-liner:
  `return this.config.vector?.persistMode ?? 'immediate'`. The cloud-vs-local
  smart-default branching is no longer relevant (filesystem is the only
  persistent backend in 8.0).
- setupIndex() — reads quantization fields from config.vector directly;
  rerankMultiplier hardcoded to 3.

NO-OP scope

The recall preset's 'balanced' = brainy 7.x DEFAULT_CONFIG byte-for-byte,
so users who don't set recall get the same behavior. Users who set
config.hnsw.* in 7.x will need to migrate to config.vector.* per the
8.0 release notes; pure 7.x defaults users see no change.

VERIFICATION

- npx tsc --noEmit: clean
- npm test: 1408 / 1409 (same pre-existing test-isolation race condition
  from step 7, not related to step 8)
This commit is contained in:
David Snelling 2026-06-09 14:20:57 -07:00
parent 0e6263a1bd
commit 8e767408d9
3 changed files with 68 additions and 105 deletions

View file

@ -32,9 +32,10 @@ export type RecallPreset = 'fast' | 'balanced' | 'accurate'
export const DEFAULT_RECALL: RecallPreset = 'balanced'
/**
* The set of HNSW knobs that the `recall` preset controls. Power users may
* override any of these via `config.vector.advanced.hnsw` the preset is the
* floor, explicit overrides win.
* The set of HNSW knobs that the `recall` preset controls. Brainy 8.0 does
* not expose these directly the preset is the only quality/latency knob
* surfaced on the public config. Algorithm-internal tuning is intentionally
* hidden behind the preset.
*/
export interface RecallHnswKnobs {
M: number
@ -66,8 +67,7 @@ export function resolveRecallHnswKnobs(preset: RecallPreset | undefined): Recall
/**
* Resolve a Brainy 8.0 `VectorIndexConfig` into a concrete `HNSWConfig` for
* the open-core JS HNSW path. Applies the recall preset first, then layers
* the optional `advanced.hnsw` overrides so explicit knobs always win.
* the open-core JS HNSW path. Applies the recall preset.
*
* Native acceleration providers do NOT use this function they read
* `config.vector.recall` directly and apply their own preset table. This
@ -75,17 +75,16 @@ export function resolveRecallHnswKnobs(preset: RecallPreset | undefined): Recall
*
* @param vectorConfig - The user-supplied `config.vector` block. May be omitted.
* @returns A complete `HNSWConfig` with `M`, `efConstruction`, `efSearch`, `ml`
* populated from preset + overrides.
* populated from the preset.
*/
export function resolveJsHnswConfig(
vectorConfig?: { recall?: RecallPreset; advanced?: { hnsw?: Partial<HNSWConfig> } }
vectorConfig?: { recall?: RecallPreset }
): Pick<HNSWConfig, 'M' | 'efConstruction' | 'efSearch' | 'ml'> {
const preset = resolveRecallHnswKnobs(vectorConfig?.recall)
const overrides = vectorConfig?.advanced?.hnsw ?? {}
return {
M: overrides.M ?? preset.M,
efConstruction: overrides.efConstruction ?? preset.efConstruction,
efSearch: overrides.efSearch ?? preset.efSearch,
ml: overrides.ml ?? 16,
M: preset.M,
efConstruction: preset.efConstruction,
efSearch: preset.efSearch,
ml: 16,
}
}