refactor(8.0): add saveVectorIndexData / getVectorIndexData storage contract (scaffold step 4)

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
This commit is contained in:
David Snelling 2026-06-09 13:09:27 -07:00
parent f39d420cb4
commit 356f044d2a

View file

@ -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