From 356f044d2afe79dd225003e5abf9dec77ff91480 Mon Sep 17 00:00:00 2001
From: David Snelling <david@soulcraft.com>
Date: Tue, 9 Jun 2026 13:09:27 -0700
Subject: [PATCH] refactor(8.0): add saveVectorIndexData / getVectorIndexData
 storage contract (scaffold step 4)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Step 4 of the brainy 8.0 rename scaffolding. The storage-adapter contract
gains the new algorithm-neutral method names. Existing concrete adapters
keep their saveHNSWData / getHNSWData implementations untouched; the new
names default to delegating to the old, so no concrete adapter needs to
change in this commit. The final 8.0 cleanup removes the legacy names.

CHANGES

src/storage/adapters/baseStorageAdapter.ts
- New default method `saveVectorIndexData(nounId, data)` that delegates
  to `saveHNSWData` for backward compatibility. Concrete adapters may
  override directly when the legacy name is removed.
- New default method `getVectorIndexData(nounId)` that delegates to
  `getHNSWData`.

Pre-existing abstract methods stay; concrete adapters (FileSystem,
GCS, R2, S3, Azure, OPFS, Memory, Historical) continue to implement
saveHNSWData / getHNSWData unchanged.

PERSISTED FILE PATHS — DEFERRED

The on-disk `_system/hnsw-*.json` → `_system/vector-index-*.json` rename
is NOT in this commit. The new persisted-path layout requires:
- dual-read on boot (accept either spelling — per integration doc lines
  531-539: "Reader accepts either spelling on load; writer emits the new
  spelling only; brains self-migrate on the next persist after upgrade")
- coordinated update across 8 storage adapters

That work is folded into the final cleanup commit so the rename + migration
ship atomically.

NO-OP scope

No behavioural change. New methods delegate to existing ones; no caller
has been migrated yet. Tests + build green.

VERIFICATION

- npx tsc --noEmit: clean
- npm test: 1468 / 1468 unit
---
 src/storage/adapters/baseStorageAdapter.ts | 32 ++++++++++++++++++++--
 1 file changed, 30 insertions(+), 2 deletions(-)

diff --git a/src/storage/adapters/baseStorageAdapter.ts b/src/storage/adapters/baseStorageAdapter.ts
index 328d347f..2102d92d 100644
--- a/src/storage/adapters/baseStorageAdapter.ts
+++ b/src/storage/adapters/baseStorageAdapter.ts
@@ -95,8 +95,10 @@ export abstract class BaseStorageAdapter implements StorageAdapter {
 
   abstract getVerbMetadata(id: string): Promise<any | null>
 
-  // HNSW Index Persistence
-  // These methods enable HNSW index rebuilding after container restarts
+  // Vector Index Persistence (Brainy 8.0 — algorithm-neutral surface)
+  // The legacy `saveHNSWData` / `getHNSWData` names persist as default-method
+  // aliases so existing implementations continue to work mid-migration; the
+  // 8.0 final cleanup commit removes the old names.
 
   abstract getNounVector(id: string): Promise<number[] | null>
 
@@ -110,6 +112,32 @@ export abstract class BaseStorageAdapter implements StorageAdapter {
     connections: Record<string, string[]>
   } | null>
 
+  /**
+   * Persist vector-index graph state for an entity (Brainy 8.0 name).
+   * Default implementation delegates to {@link saveHNSWData}; concrete
+   * adapters may override directly. The final 8.0 cleanup removes the
+   * legacy `saveHNSWData` name.
+   */
+  async saveVectorIndexData(nounId: string, data: {
+    level: number
+    connections: Record<string, string[]>
+  }): Promise<void> {
+    return this.saveHNSWData(nounId, data)
+  }
+
+  /**
+   * Read vector-index graph state for an entity (Brainy 8.0 name).
+   * Default implementation delegates to {@link getHNSWData}; concrete
+   * adapters may override directly. The final 8.0 cleanup removes the
+   * legacy `getHNSWData` name.
+   */
+  async getVectorIndexData(nounId: string): Promise<{
+    level: number
+    connections: Record<string, string[]>
+  } | null> {
+    return this.getHNSWData(nounId)
+  }
+
   abstract saveHNSWSystem(systemData: {
     entryPointId: string | null
     maxLevel: number