From 076c26f6fdc4e8097e908dd0c7f2d9d8c1168cd1 Mon Sep 17 00:00:00 2001 From: David Snelling Date: Tue, 9 Jun 2026 12:58:26 -0700 Subject: [PATCH] =?UTF-8?q?refactor(8.0):=20rename=20HnswProvider=20?= =?UTF-8?q?=E2=86=92=20VectorIndexProvider=20(8.0=20scaffold)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- src/hnsw/hnswIndex.ts | 10 ++++---- src/plugin.ts | 58 +++++++++++++++++++++---------------------- 2 files changed, 33 insertions(+), 35 deletions(-) diff --git a/src/hnsw/hnswIndex.ts b/src/hnsw/hnswIndex.ts index ff074daf..10cb69f8 100644 --- a/src/hnsw/hnswIndex.ts +++ b/src/hnsw/hnswIndex.ts @@ -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 = new Map() private entryPointId: string | null = null private maxLevel = 0 diff --git a/src/plugin.ts b/src/plugin.ts index 4145daf3..4efaed8e 100644 --- a/src/plugin.ts +++ b/src/plugin.ts @@ -192,15 +192,20 @@ export interface GraphIndexProvider { } /** - * The object returned by the `'hnsw'` provider factory — a drop-in for - * `HNSWIndex`. Brainy calls this surface via `this.index.*` plus the - * transactional add/remove operations. `enableCOW`, `getItem`, and - * `setPersistMode` are intentionally absent: Brainy guards each with - * feature-detection (`typeof x === 'function'`), so they are optional and not - * part of the required contract (Brainy's own `HNSWIndex` omits - * `setPersistMode`, for instance). + * The object returned by the `'vector'` provider factory — Brainy's vector + * index contract. Implementations include Brainy's own JS HNSW index and any + * native acceleration provider (e.g. cortex's Adaptive DiskANN). + * + * Brainy calls this surface via `this.index.*` plus the transactional add/remove + * operations. `enableCOW`, `getItem`, and `setPersistMode` are intentionally + * absent: Brainy guards each with feature-detection (`typeof x === 'function'`), + * so they are optional and not part of the required contract (Brainy's own JS + * HNSW index omits `setPersistMode`, for instance). + * + * **Provider key:** registered under `'vector'`. The legacy `'hnsw'` key is + * accepted as a compat shim in 8.0 and retired in a future release. */ -export interface HnswProvider { +export interface VectorIndexProvider { addItem(item: VectorDocument): Promise removeItem(id: string): Promise search( @@ -217,29 +222,22 @@ export interface HnswProvider { } /** - * The `'diskann'` provider — a billion-scale alternative to HNSW backed - * by cortex's pure-Rust Vamana + Product Quantization implementation - * (see ADR-002 in the cortex repo). - * - * Structurally a drop-in for [`HnswProvider`]: brainy calls the same - * `addItem` / `search` / `rebuild` surface and never needs to know - * which index is underneath. The differences are operational: - * - * - **Memory footprint**: ~16 GB RAM at 1 B vectors (PQ codes only). - * HNSW would need ~1.5 TB to keep the full vectors resident. - * - **Build model**: build-once, query-many. Dynamic insertions buffer - * to an in-memory delta brute-forced alongside the main index; - * `rebuild()` folds them in. - * - **Storage**: requires a local filesystem path (NVMe SSD for the - * published latency numbers). Cloud-storage adapters continue using - * HNSW. - * - * Engagement is automatic when the cortex provider is registered, the - * storage adapter exposes `getBinaryBlobPath`, and the metadata index - * has a stable `idMapper`. Users force the legacy index via - * `config.index.type = 'hnsw'`. + * @deprecated Renamed to {@link VectorIndexProvider} in Brainy 8.0. The + * interface shape is byte-for-byte identical; only the name changed because + * "vector index" describes the role, while "HNSW" was the name of one + * specific implementation. This alias is provided as a compatibility shim + * for code mid-migration; new code should import `VectorIndexProvider`. */ -export type DiskAnnProvider = HnswProvider +export type HnswProvider = VectorIndexProvider + +/** + * @deprecated The `'diskann'` provider key has been folded into `'vector'` in + * Brainy 8.0. The vector index contract is implementation-neutral: any provider + * registered under `'vector'` may be HNSW, DiskANN, or a future algorithm. The + * type alias is preserved so existing imports compile while consumers migrate + * to `VectorIndexProvider`. + */ +export type DiskAnnProvider = VectorIndexProvider /** * The `'entityIdMapper'` provider — a drop-in for `EntityIdMapper`. Injected