From 89e4d810ed95047130f0d2c6d3a155be9225b64f Mon Sep 17 00:00:00 2001
From: David Snelling <david@soulcraft.com>
Date: Tue, 9 Jun 2026 12:53:34 -0700
Subject: [PATCH] docs: correct misleading SQ4 quantization comment in type
 definitions

Two type-definition comments (src/coreTypes.ts:472 +
src/types/brainy.types.ts:1123) stated:

  bits?: 8 | 4   // default: 8 (SQ8). SQ4 requires cortex native.

This was factually wrong. src/utils/vectorQuantization.ts:412 ships
distanceSQ4Js, a pure-JS SQ4 implementation that's been part of the
open-core path the whole time. The native SIMD acceleration is a drop-in
via setSQ4DistanceImplementation, NOT a hard requirement.

The misleading comment risked pushing open-core users to assume they
needed a paid native provider for SQ4 quantization when they did not.

Corrected to:

  bits?: 8 | 4   // default: 8 (SQ8). SQ4 has a pure-JS implementation;
                 // cortex's distance:sq4 SIMD provider accelerates it.

Pure documentation; no behaviour change. Caught during an upstream
open-core-boundary audit (handoff thread BRAINY-8.0-RENAME-COORDINATION,
section E.1).

Verification

- npx tsc --noEmit: clean
- npm test: 1468 / 1468 unit
- npm run build: clean
---
 RELEASES.md               | 37 +++++++++++++++++++++++++++++++++++++
 src/coreTypes.ts          |  2 +-
 src/types/brainy.types.ts |  2 +-
 3 files changed, 39 insertions(+), 2 deletions(-)

diff --git a/RELEASES.md b/RELEASES.md
index f5f08571..58b20bd2 100644
--- a/RELEASES.md
+++ b/RELEASES.md
@@ -10,6 +10,43 @@ Full auto-generated changelog: `CHANGELOG.md` · Releases: https://github.com/so
 
 ---
 
+## v7.31.2 — 2026-06-09
+
+**Affected products:** none in behaviour; affects anyone reading Brainy's TypeScript
+type definitions or coreTypes for the `hnsw.quantization.bits` option. Drop-in from 7.31.1.
+
+### Fix: stale comment claimed SQ4 vector quantization required a paid native provider
+
+Brainy ships a pure-JS SQ4 distance implementation (`distanceSQ4Js` in
+`src/utils/vectorQuantization.ts`) that's been part of the open-core path the whole
+time. Two type-definition comments incorrectly stated SQ4 required a native (paid)
+provider:
+
+```ts
+// coreTypes.ts:472 + types/brainy.types.ts:1123 — before
+bits?: 8 | 4   // default: 8 (SQ8). SQ4 requires cortex native.
+```
+
+The comment was simply wrong — open-core users can use SQ4 today, and the native SIMD
+acceleration is a drop-in via `setSQ4DistanceImplementation`, not a hard requirement.
+Corrected to:
+
+```ts
+bits?: 8 | 4   // default: 8 (SQ8). SQ4 has a pure-JS implementation;
+               // cortex's distance:sq4 SIMD provider accelerates it.
+```
+
+Both locations updated. Pure documentation; no behaviour change. Caught during an
+upstream open-core-boundary audit — thanks to whoever read the types carefully enough
+to spot the misleading comment.
+
+### Cortex compatibility
+
+Zero changes required. The fix is documentation only; runtime behaviour was already
+correct (`vectorQuantization.ts:412` ships `distanceSQ4Js`).
+
+---
+
 ## v7.31.1 — 2026-06-09
 
 **Affected products:** any consumer running `@soulcraft/brainy` against `FileSystemStorage`
diff --git a/src/coreTypes.ts b/src/coreTypes.ts
index 7bcceed6..5d55ec1f 100644
--- a/src/coreTypes.ts
+++ b/src/coreTypes.ts
@@ -469,7 +469,7 @@ export interface HNSWConfig {
   // SQ8 vector quantization (4x memory reduction, ~0.4% accuracy loss)
   quantization?: {
     enabled: boolean        // default: false — preserves current behavior exactly
-    bits?: 8 | 4            // default: 8 (SQ8). SQ4 requires cortex native.
+    bits?: 8 | 4            // default: 8 (SQ8). SQ4 has a pure-JS implementation; cortex's distance:sq4 SIMD provider accelerates it.
     rerankMultiplier?: number // default: 3 — over-retrieve 3x, rerank with float32
   }
   // Vector storage mode
diff --git a/src/types/brainy.types.ts b/src/types/brainy.types.ts
index 9d5746f9..70055caa 100644
--- a/src/types/brainy.types.ts
+++ b/src/types/brainy.types.ts
@@ -1120,7 +1120,7 @@ export interface BrainyConfig {
   hnsw?: {
     quantization?: {
       enabled?: boolean        // default: false — current behavior exactly
-      bits?: 8 | 4             // default: 8 (SQ8). SQ4 requires cortex native.
+      bits?: 8 | 4             // default: 8 (SQ8). SQ4 has a pure-JS implementation; cortex's distance:sq4 SIMD provider accelerates it.
       rerankMultiplier?: number // default: 3 — over-retrieve 3x, rerank with float32
     }
     vectorStorage?: 'memory' | 'lazy'  // default: 'memory' — 'lazy' evicts vectors after insert