soulcraftlabs/open-brainy
Archived
2
0
Fork 0
Code Issues 1 Pull requests Projects Releases 345 Packages Wiki Activity

feat(plugin): every provider write surface carries the real committed generation

Browse source 
The provider contract (metadata addToIndex/removeFromIndex, vector
addItem/removeItem, id-mapper getOrAssign/remove) gains an optional
trailing generation — evaluated lazily at operation execute time (the
graph surface's thunk pattern, generalized), threaded from all 17
construction sites: undefined during generation-0 bootstrap, the real
committed generation everywhere else. Optional = additive: no existing
provider or caller breaks; native delta logs that stamped literal zero
start hearing truth. JS twins accept the parameter with parity notes.
Pins: provider doubles capture and assert nonzero monotonic generations
across add/update/remove on both surfaces.
This commit is contained in:
David Snelling 2026-08-10 09:29:06 -07:00
parent 3484107462
commit 2d532684b4
7 changed files with 583 additions and 63 deletions
Download patch file Download diff file Expand all files Collapse all files

24
src/hnsw/hnswIndex.ts
View file

@ -405,8 +405,15 @@ export class JsHnswVectorIndex implements VectorIndexProvider {
/**
* Add a vector to the index
*
* @param generation - Brainy's commit generation for this write (contract
* parity with `VectorIndexProvider.addItem`). This JS index serves "now"
* only — no per-record delta log, no natural slot — so the value is
* accepted and ignored; a native provider stamps its durable records
* with it. The JS twin adopts stamping with the watermark train.
*/
public async addItem(item: VectorDocument): Promise<string> {
public async addItem(item: VectorDocument, generation?: bigint): Promise<string> {
void generation // Contract parity — the JS index keeps no per-write log.
// Check if item is defined
if (!item) {
throw new Error('Item is undefined or null')
@ -771,8 +778,13 @@ export class JsHnswVectorIndex implements VectorIndexProvider {
* `'immediate'` persists their connections now; `'deferred'` marks them
* dirty for the next flush. The system record (entry point + maxLevel) is
* NOT rewritten — an in-place update changes neither.
*
* @param generation - Brainy's commit generation for this write (contract
* parity with the feature-detected `updateItem` provider capability).
* Accepted and ignored — the JS index keeps no per-write log.
*/
public async updateItem(item: VectorDocument): Promise<void> {
public async updateItem(item: VectorDocument, generation?: bigint): Promise<void> {
void generation // Contract parity — the JS index keeps no per-write log.
if (!item) {
throw new Error('Item is undefined or null')
}
@ -1212,8 +1224,14 @@ export class JsHnswVectorIndex implements VectorIndexProvider {
/**
* Remove an item from the index
*
* @param generation - Brainy's commit generation for this removal (contract
* parity with `VectorIndexProvider.removeItem`). Accepted and ignored —
* this JS index removes immediately; a native provider records the
* tombstone at this generation.
*/
public async removeItem(id: string): Promise<boolean> {
public async removeItem(id: string, generation?: bigint): Promise<boolean> {
void generation // Contract parity — the JS index keeps no per-write log.
if (!this.nouns.has(id)) {
return false
}