refactor(8.0): rename HnswProvider → VectorIndexProvider (8.0 scaffold)

Brainy 8.0 collapses the vector-index contract to algorithm-neutral names.
"Vector index" describes the role; "HNSW" was the name of one specific
implementation. The role name is what the public contract should carry;
the algorithm name belongs to the concrete class.

This is step 1 of the brainy 8.0 rename scaffolding tracked in handoff
thread BRAINY-8.0-RENAME-COORDINATION § A.1 (cortex shipped the matching
VectorIndexProvider in commit 0e4d637).

CHANGES

src/plugin.ts
- Primary interface name flipped: HnswProvider → VectorIndexProvider.
  Same byte-for-byte shape (8 methods, no signatures changed).
- HnswProvider kept as a deprecated type alias so call sites compile
  mid-migration. Removed in a later 8.0 commit.
- DiskAnnProvider was already a type alias of HnswProvider; redeclared
  as alias of VectorIndexProvider with a deprecation note explaining
  the 'diskann' provider key folds into 'vector' in 8.0.
- JSDoc updated to describe the implementation-neutral surface:
  Brainy's own JS HNSW + any native acceleration provider both
  satisfy it.

src/hnsw/hnswIndex.ts
- Internal class HNSWIndex now declares `implements VectorIndexProvider`
  instead of `implements HnswProvider`. Import + class comment updated.

NO-OP scope

No behavioural change. Every existing call site continues to work
because HnswProvider remains as a temporary alias. Tests + build green.

VERIFICATION

- npx tsc --noEmit: clean
- npm test: 1468 / 1468 unit
- npm run build: clean (verified at parent commit 89e4d81; this commit
  is type-only so doesn't change dist)

NEXT IN SCAFFOLDING

- Add 'vector' provider key registration alongside 'hnsw' (cache + cortex)
- Add config.vector top-level path alongside config.hnsw with recall preset
- Migrate brainy.ts call sites to the new names
- Rename HNSWIndex class → JsHnswVectorIndex (per planning § 2.3)
- Final cleanup commit: remove HnswProvider alias + config.hnsw + 'hnsw' key
This commit is contained in:
David Snelling 2026-06-09 12:58:26 -07:00
parent d6daafb426
commit 076c26f6fd
2 changed files with 33 additions and 35 deletions

View file

@ -17,7 +17,7 @@ import { getGlobalCache, UnifiedCache } from '../utils/unifiedCache.js'
import { prodLog } from '../utils/logger.js'
import { quantizeSQ8, distanceSQ8 } from '../utils/vectorQuantization.js'
import type { SQ8QuantizedVector } from '../utils/vectorQuantization.js'
import type { HnswProvider } from '../plugin.js'
import type { VectorIndexProvider } from '../plugin.js'
import { MmapVectorBackend } from './mmapVectorBackend.js'
import { ConnectionsCodec, compressedConnectionsKey } from './connectionsCodec.js'
@ -30,11 +30,11 @@ const DEFAULT_CONFIG: HNSWConfig = {
}
/**
* Implements {@link HnswProvider}: the vector-index surface Brainy calls on
* whatever the `'hnsw'` factory returns (its own `HNSWIndex`, or Cortex's
* native engine).
* Implements {@link VectorIndexProvider}: the vector-index surface Brainy calls
* on whatever the `'vector'` factory returns (its own `HNSWIndex`, or a native
* acceleration provider).
*/
export class HNSWIndex implements HnswProvider {
export class HNSWIndex implements VectorIndexProvider {
private nouns: Map<string, HNSWNoun> = new Map()
private entryPointId: string | null = null
private maxLevel = 0