diff --git a/src/brainy.ts b/src/brainy.ts index f998336a..344a4d86 100644 --- a/src/brainy.ts +++ b/src/brainy.ts @@ -6269,11 +6269,18 @@ export class Brainy implements BrainyInterface { relationCount, relationsByType, fieldRegistry, - indexHealth: { - hnsw: this.index.size() > 0 || entityCount === 0, - metadata: metadataStats.totalEntries > 0 || entityCount === 0, - graph: (await this.graphIndex.size()) > 0 || relationCount === 0 - }, + indexHealth: await (async () => { + // 8.0 rename: `vector` is the canonical name; `hnsw` is a compat + // alias that's removed in the final 8.0 cleanup commit. + const vectorHealthy = this.index.size() > 0 || entityCount === 0 + const graphSize = await this.graphIndex.size() + return { + hnsw: vectorHealthy, + vector: vectorHealthy, + metadata: metadataStats.totalEntries > 0 || entityCount === 0, + graph: graphSize > 0 || relationCount === 0 + } + })(), storage: { backend: storageBackend, rootDir: typeof rootDir === 'string' ? rootDir : undefined @@ -9304,6 +9311,9 @@ export class Brainy implements BrainyInterface { // { except: [...] }: strict, but listed types may omit subtype. // Becomes the default in 8.0.0. requireSubtype: config?.requireSubtype ?? false, + // Provider-knob mismatch strictness (8.0). Default is 'warn' (one-shot + // teaching message). See BRAINY-8.0-RENAME-COORDINATION § B.6. + strictConfig: config?.strictConfig ?? 'warn', // Multi-process safety mode: config?.mode ?? 'writer', force: config?.force ?? false @@ -9464,6 +9474,13 @@ export class Brainy implements BrainyInterface { const idMapper = this.metadataIndex.getIdMapper?.() if (!idMapper) return + // Feature-detect: only the JS HNSW path uses per-node connection lists. + // Native vector-index providers (DiskANN-style) persist the graph as a + // single mmap'd file and have no analogue, so skip the wiring there. + // Pre-8.0 the wire was unconditional and relied on the native wrapper + // exposing a no-op setConnectionsCodec(); 8.0 makes it feature-detected. + if (typeof (this.index as { setConnectionsCodec?: unknown }).setConnectionsCodec !== 'function') return + const codec = new ConnectionsCodec(provider, idMapper) this.index.setConnectionsCodec(codec) if (!this.config.silent) { diff --git a/src/types/brainy.types.ts b/src/types/brainy.types.ts index 2a792a87..b8249070 100644 --- a/src/types/brainy.types.ts +++ b/src/types/brainy.types.ts @@ -1031,7 +1031,10 @@ export interface BrainyStats { fieldRegistry: string[] /** Per-index health flags. `true` = index has entries OR no entities exist yet. */ indexHealth: { + /** @deprecated 8.0 — renamed to `vector`. Same boolean; kept as a compat alias until the final 8.0 cleanup. */ hnsw: boolean + /** Vector index health (8.0 name — open-core JS HNSW path or a native acceleration provider). */ + vector: boolean metadata: boolean graph: boolean } @@ -1246,6 +1249,30 @@ export interface BrainyConfig { */ requireSubtype?: boolean | { except: Array } + /** + * Validation strictness for provider-knob mismatches (Brainy 8.0). + * + * When a registered provider silently ignores a configuration knob the + * user passed (e.g. `config.vector.advanced.diskann.*` on the open-core JS + * HNSW path, or `config.vector.advanced.hnsw.*` on a native DiskANN-style + * path), the user otherwise gets no feedback that their override has no + * effect. This option controls the response: + * + * - `false` — no enforcement. Mismatched knobs are silently accepted. + * - `'warn'` — (default in 8.0) one-shot warning per call site via + * `prodLog.warn`, listing the ignored knobs and the docs link to the + * appropriate `advanced.*` escape hatch. + * - `true` — hard error at `init()`. Refuses to start until the config + * is consistent with the resolved provider impl. + * + * The warning / error format matches the 7.30.1 teaching-error pattern: + * problem → escape valves → caller location → docs link. + * + * **Contract** locked in handoff thread BRAINY-8.0-RENAME-COORDINATION + * § B.6 (cortex-confirmed 2026-06-09). + */ + strictConfig?: boolean | 'warn' + /** * Process role for multi-process safety on filesystem storage. *