feat(8.0): version-coupling guard — a mismatched/failed native plugin fails loud, never silent JS fallback

A wrong or missing accelerator (@soulcraft/cor) used to silently degrade to the
default JS engine — the #1 source of invisible cross-repo drift. Brainy does no
plugin auto-detection (a registered plugin is always explicitly requested via
config.plugins or brain.use()), so any mismatch/failure is now fatal:

- BrainyPlugin gains optional `brainyRange` (semver range of brainy it supports);
  init() throws if the running brainy is outside it. New dep-free, prerelease-safe
  matcher pluginRangeSatisfies() (8.0.0-rc1 satisfies >=8.0.0).
- activateAll(): a plugin that THROWS during activate now re-throws (was swallowed
  to a JS fallback); a graceful decline (activate()→false) stays non-fatal but logs
  a loud warning.
- loadPlugins(): an explicitly-listed package that can't load — or isn't a valid
  plugin — throws (was a silent skip).
- Provider-key cliff: a pre-8.0 plugin that registers a legacy vector key
  ('hnsw'/'diskann') but not the 8.0 'vector' key throws (brainy 8.x reads only
  'vector', so it would otherwise run JS vectors invisibly).

Tests: tests/unit/plugin-version-coupling.test.ts (range matcher incl. rc1; range
mismatch / activate-throw / cliff / missing-package all throw; decline non-fatal).
Updated two plugin.test.ts cases that asserted the old silent-swallow behavior.
Build green; 1464 unit green. cor declares its brainyRange per handoff LV.1 #2.
This commit is contained in:
David Snelling 2026-06-19 10:13:04 -07:00
parent b198281ce1
commit 1264fec534
4 changed files with 271 additions and 32 deletions

View file

@ -71,7 +71,7 @@ describe('PluginRegistry', () => {
expect(registry.getActivePlugins()).toEqual([])
})
it('should handle plugin that throws during activate', async () => {
it('throws (does not silently swallow) when a plugin throws during activate', async () => {
const plugin: BrainyPlugin = {
name: 'broken-plugin',
activate: async () => {
@ -85,9 +85,10 @@ describe('PluginRegistry', () => {
version: '7.9.3'
}
// Should not throw — graceful fallback
const activated = await registry.activateAll(context)
expect(activated).toEqual([])
// A registered plugin is always explicitly requested (config.plugins or
// brain.use(); brainy does no auto-detection), so a hard activation failure
// must surface — never a silent fall-back to the default engine.
await expect(registry.activateAll(context)).rejects.toThrow(/failed to activate|activation failed/)
expect(registry.getActivePlugins()).toEqual([])
})
@ -279,7 +280,7 @@ describe('Brainy plugin integration', () => {
await brain.close()
})
it('should fall back gracefully when plugin throws', async () => {
it('throws (no silent fallback) when an explicitly-used plugin crashes on activate', async () => {
const mockPlugin: BrainyPlugin = {
name: 'crashing-plugin',
activate: async () => {
@ -293,18 +294,10 @@ describe('Brainy plugin integration', () => {
})
brain.use(mockPlugin)
// Should not throw — graceful fallback to TS
await brain.init()
expect(brain.getActivePlugins()).toEqual([])
const id = await brain.add({
data: { name: 'test' },
type: NounType.Concept,
metadata: { tag: 'unit-test' }
})
expect(id).toBeTypeOf('string')
await brain.close()
// A brain.use()'d plugin is explicitly requested — a hard activation crash
// must surface as a failed init(), NOT a silent degrade to the default
// engine (the version-coupling guard; see plugin-version-coupling.test.ts).
await expect(brain.init()).rejects.toThrow(/failed to activate|native module not found/)
})
it('should use() return this for chaining', () => {