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

refactor(8.0): API-surface + quality polish from the readiness audit

Browse source 
- find() search-mode: collapsed the two overlapping options to one canonical
  `searchMode: SearchMode` (the redundant `mode` alias was silently ignored on
  the primary find() path while honored on the historical path — a footgun) and
  removed the unwired `explain?` FindParams field (never read by find()).
- Documentation accuracy on the public type surface: entity ids documented as
  UUID v7 (auto) / v5 (natural key), not v4; dropped the stale "Brainy 3.0"
  banners and "backward compatibility" hedging on the fresh-8.0 Result type;
  documented the via/type alias; removed the dead GraphConstraints.bidirectional;
  fixed the no-op `EmbeddedGraphVerb = Omit<GraphVerb,'source'>` to omit the real
  sourceId; corrected the GraphIndexProvider.isInitialized JSDoc; documented
  removeMany's per-chunk generation granularity; JSDoc'd the public VFS surface.
- Honest perf comments in source: removed unmeasured billion-scale figures from
  the LSMTree / graphAdjacencyIndex headers (the JS fallback is in-memory after
  open; native is the scale path).
- Robustness: getVerbMetadata propagates read errors symmetrically with
  getNounMetadata; the find() egress integrity-guard keeps a row when the JS
  matcher doesn't implement an operator the provider already matched on; hardened
  the boundary-no-native CI guard to catch side-effect imports + re-exports.
- Tests: de-theatricalized a relateMany test to assert the real contract; fixed
  a stale Model-B header.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
David Snelling 2026-06-29 10:04:19 -07:00
parent 47e8031124
commit a52dba2168
10 changed files with 346 additions and 45 deletions
Download patch file Download diff file Expand all files Collapse all files

8
src/db/db.ts
View file

@ -481,7 +481,6 @@ export class Db<T = any> {
delete universeParams.query
delete universeParams.vector
delete universeParams.searchMode
delete universeParams.mode
delete universeParams.orderBy
delete universeParams.order
universeParams.limit = AT_GEN_VECTOR_UNIVERSE_CAP
@ -1063,9 +1062,10 @@ function indexOnlyFindDimensions(params: FindParams): Array<[string, boolean]> {
['aggregation', params.aggregate !== undefined],
['relation expansion (includeRelations)', params.includeRelations === true],
[
`search mode '${params.mode ?? params.searchMode}'`,
(params.mode !== undefined && params.mode !== 'metadata' && params.mode !== 'auto') ||
(params.searchMode !== undefined && params.searchMode !== 'auto')
`search mode '${params.searchMode}'`,
params.searchMode !== undefined &&
params.searchMode !== 'auto' &&
params.searchMode !== 'metadata'
]
]
}

7
src/db/generationStore.ts
View file

@ -595,9 +595,10 @@ export class GenerationStore {
/**
* @description Commit ONE single-operation write (`add`/`update`/`remove`/
* `relate`/`updateRelation`/`unrelate` and their `*Many` per-item calls) as
* its own immutable generation — the Model-B "every write versioned"
* contract. Structurally a one-operation {@link commitTransaction} with
* `relate`/`updateRelation`/`unrelate` and the per-item calls of `addMany`/
* `updateMany`/`relateMany`) as its own immutable generation — the Model-B
* "every write versioned" contract. (`removeMany` commits each delete *chunk*
* as a single generation for bulk efficiency — the one non-per-item path.) Structurally a one-operation {@link commitTransaction} with
* **deferred durability**:
*
* - Under the commit mutex it reserves generation `N`, captures byte-identical