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

feat: vector provider identity is a required name field (hnsw-js), rendered [vector-index:<name>]

Browse source 
Reconciles the vector-index rename to the ruled three-layer naming: the
provider contract's identity field is now a REQUIRED readonly name (was
optional providerId), self-reported and truthful, rendered as
[vector-index:<name>] where the index identifies itself and stamped into
the op-name strings journals already parse (AddToVectorIndex(<name>)).
The built-in JS engine names itself hnsw-js. A runtime provider instance
compiled against the previous optional contract is tolerated - never
crashed on, never silently mislabeled: it stamps unknown-provider and
emits one loud warning naming the missing field. Graph index operations
keep their static names (they never interpolate provider identity), and
no public API exports a provider-routed hnsw-carrying name, so no
deprecation shim is required.
This commit is contained in:
David Snelling 2026-07-23 08:53:05 -07:00
parent 55b867c998
commit 3be4ba96c2
6 changed files with 92 additions and 38 deletions
Download patch file Download diff file Expand all files Collapse all files

29
src/transaction/operations/IndexOperations.ts
View file

@ -16,19 +16,34 @@ import type { Operation, RollbackAction } from '../types.js'
/**
* Backend identity stamped into an operation's emitted `name` string (e.g.
* `AddToVectorIndex(js-hnsw)`), resolved from the provider's own
* {@link VectorIndexProvider.providerId} when it self-identifies.
* `AddToVectorIndex(hnsw-js)`), resolved from the provider's own
* {@link VectorIndexProvider.name} self-report.
*
* These operation classes are backend-neutral (the vector index they wrap may
* be Brainy's own JS HNSW fallback OR a native acceleration provider), but
* their names surface directly in consumer-visible transaction journals and
* timings. A provider that hasn't set `providerId` resolves to
* `'unknown-provider'` rather than guessing — silently defaulting to the JS
* engine's name here is exactly the class of bug this stamping exists to
* prevent (an operator diagnosing a backend that isn't the one that ran).
* timings. `name` is REQUIRED at the TypeScript level — but a native provider
* instance compiled against the previous (pre-required) contract can still
* reach this function at runtime without it. That legacy case is tolerated,
* never crashed on and never silently mislabeled: it resolves to
* `'unknown-provider'` and emits ONE loud warning naming the missing contract
* field, so the fix (implement `name`) is discoverable rather than a silent
* fossil label in every journal line thereafter.
*/
const warnedMissingName = new WeakSet<VectorIndexProvider>()
function resolveVectorProviderId(index: VectorIndexProvider): string {
return index.providerId ?? 'unknown-provider'
const name = (index as { name?: unknown }).name
if (typeof name === 'string') return name
if (!warnedMissingName.has(index)) {
warnedMissingName.add(index)
console.warn(
'[vector-index] provider is missing the required `name` field (VectorIndexProvider.name, ' +
'required since 8.10.0) — stamping "unknown-provider" in transaction op names until the ' +
'provider declares its own identity.'
)
}
return 'unknown-provider'
}
/**