soulcraft/brainy
2
0
Fork 0
Code Issues 1 Pull requests Projects Releases 335 Packages Wiki Activity Actions

feat(8.0): u64 BigInt graph provider contract — punch list a-d,g,h

Browse source 
GraphIndexProvider now speaks BigInt at the boundary (D.2 mirror):
- getNeighbors/getVerbIdsBySource/getVerbIdsByTarget take entity ints and
  return entity/verb ints as bigint[]
- new REQUIRED verbIntsToIds(bigint[]) batch reverse resolver (L.7
  identity-fingerprint design — verb ids are UUIDs by contract, so the
  provider-side interning is losslessly reversible)
- addVerb(verb, sourceInt, targetInt) returns the interned verb int;
  removeVerb(verbId) joins the contract

Coordinator (brainy.ts) owns ALL UUID <-> int conversion: getOrAssign on
writes, getInt on reads (unmapped UUID -> empty result without calling the
provider), getUuid / verbIntsToIds on returns, plus a bounded ~100k-entry
insertion-order warm cache for verb-int -> verb-id pairs fed by addVerb
returns and resolver results. GraphVerb gains derived sourceInt/targetInt
(populated at add time, never persisted). findConnectedSubtype gains a
native fast path that routes single-type single-subtype outgoing BFS
through the provider when available.

JS GraphAdjacencyIndex satisfies the contract while staying string/u32-keyed
internally: entity ints resolve through the shared entity-id mapper (threaded
in by the coordinator on init/fork/checkout), verb ints come from an
in-process append-only interning map re-derived from storage on
rebuild/cold-start. ColumnStoreProvider widens the same way: addEntity/
removeEntity take bigint, sortTopK/filteredSortTopK return bigint[].

relate() now rejects a caller-supplied id with a teaching error — verb ids
are brainy-generated UUIDs by contract in 8.0 (previously a passed id was
silently ignored). No Roaring64 provider-boundary decode site exists yet;
the JS-internal column store stays Roaring32 and the Treemap decoder lands
with the first consumer of provider-returned filter buffers.

Public brain API unchanged. 1413 tests green (+10 new BigInt contract tests).
This commit is contained in:
David Snelling 2026-06-10 10:45:45 -07:00
parent 62f6472fa0
commit 2427bb7960
17 changed files with 1164 additions and 328 deletions
Download patch file Download diff file Expand all files Collapse all files

17
src/types/graphTypes.ts
View file

@ -368,7 +368,7 @@ export interface GraphNoun {
* Represents relationships between nouns
*/
export interface GraphVerb {
id: string // Unique identifier for the verb
id: string // Unique identifier — always a UUID (8.0 contract: brainy generates every verb id, so providers may key verb-int interning on the raw UUID bytes)
sourceId: string // Entity UUID of the source noun
targetId: string // Entity UUID of the target noun
label?: string // Optional descriptive label
@ -381,6 +381,21 @@ export interface GraphVerb {
embedding?: number[] // Vector representation of the relationship
confidence?: number // Confidence score (0-1)
weight?: number // Strength/importance of the relationship
/**
* Derived state: the source entity's interned integer ID (u64-safe BigInt).
* Populated by the coordinator from the shared entity-id mapper at add time,
* immediately before the verb is handed to the graph-index provider. NEVER
* persisted to storage JSON — the mapper is the source of truth, and
* persisting would denormalize state that can go stale across a mapper rebuild.
*/
sourceInt?: bigint
/**
* Derived state: the target entity's interned integer ID (u64-safe BigInt).
* Same lifecycle as {@link GraphVerb.sourceInt}: coordinator-populated at add
* time, never persisted to storage JSON.
*/
targetInt?: bigint
}
/**