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:
parent
b198281ce1
commit
1264fec534
4 changed files with 271 additions and 32 deletions
108
tests/unit/plugin-version-coupling.test.ts
Normal file
108
tests/unit/plugin-version-coupling.test.ts
Normal file
|
|
@ -0,0 +1,108 @@
|
|||
/**
|
||||
* @module tests/unit/plugin-version-coupling
|
||||
* @description Guards the brainy↔native-plugin version coupling (audit P0). A
|
||||
* mismatched or failed accelerator must FAIL LOUD, never silently fall back to
|
||||
* the default JS engine — that silent degrade was the #1 cross-repo drift
|
||||
* (e.g. an old @soulcraft/cor running invisibly against brainy 8.x). Covers:
|
||||
* 1. `pluginRangeSatisfies` (the dep-free semver-range matcher, incl. RC tags)
|
||||
* 2. `brainyRange` mismatch → init throws
|
||||
* 3. activate() throwing → init throws (no swallow)
|
||||
* 4. the legacy provider-key cliff ('hnsw' but not 'vector') → init throws
|
||||
* 5. an explicitly-listed plugin that can't load → init throws
|
||||
* 6. a graceful decline (activate()→false) → no throw, loud warn
|
||||
*/
|
||||
import { describe, it, expect } from 'vitest'
|
||||
import { Brainy } from '../../src/brainy.js'
|
||||
import { pluginRangeSatisfies, type BrainyPlugin, type BrainyPluginContext } from '../../src/plugin.js'
|
||||
|
||||
function memBrain(): Brainy {
|
||||
return new Brainy({ requireSubtype: false, storage: { type: 'memory' }, silent: true })
|
||||
}
|
||||
|
||||
describe('pluginRangeSatisfies (dep-free range matcher)', () => {
|
||||
it('handles the comparator forms a brainyRange realistically uses', () => {
|
||||
expect(pluginRangeSatisfies('8.0.0', '>=8.0.0')).toBe(true)
|
||||
expect(pluginRangeSatisfies('7.31.2', '>=8.0.0')).toBe(false)
|
||||
expect(pluginRangeSatisfies('8.4.1', '>=8.0.0 <9.0.0')).toBe(true)
|
||||
expect(pluginRangeSatisfies('9.0.0', '>=8.0.0 <9.0.0')).toBe(false)
|
||||
expect(pluginRangeSatisfies('8.2.0', '^8.0.0')).toBe(true)
|
||||
expect(pluginRangeSatisfies('9.0.0', '^8.0.0')).toBe(false)
|
||||
expect(pluginRangeSatisfies('8.0.0', '=8.0.0')).toBe(true)
|
||||
expect(pluginRangeSatisfies('8.0.1', '=8.0.0')).toBe(false)
|
||||
})
|
||||
|
||||
it('tolerates a prerelease tag on the running version (RC builds satisfy a stable floor)', () => {
|
||||
// The lockstep ships as 8.0.0-rc1 — it MUST satisfy cor's `>=8.0.0` range.
|
||||
expect(pluginRangeSatisfies('8.0.0-rc1', '>=8.0.0')).toBe(true)
|
||||
expect(pluginRangeSatisfies('8.0.0-rc1', '^8.0.0')).toBe(true)
|
||||
expect(pluginRangeSatisfies('8.0.0-rc1', '>=8.0.0 <9.0.0')).toBe(true)
|
||||
})
|
||||
|
||||
it('fails OPEN on a malformed range (never blocks a valid brain on a bad declaration)', () => {
|
||||
expect(pluginRangeSatisfies('8.0.0', 'not-a-range')).toBe(true)
|
||||
expect(pluginRangeSatisfies('8.0.0', '')).toBe(true)
|
||||
})
|
||||
})
|
||||
|
||||
/** A minimal fake plugin; `onActivate` lets a test register providers / throw. */
|
||||
function fakePlugin(
|
||||
name: string,
|
||||
opts: { brainyRange?: string; onActivate?: (ctx: BrainyPluginContext) => boolean } = {}
|
||||
): BrainyPlugin {
|
||||
return {
|
||||
name,
|
||||
brainyRange: opts.brainyRange,
|
||||
async activate(ctx) {
|
||||
return opts.onActivate ? opts.onActivate(ctx) : true
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
describe('version coupling at init() — no silent fallback', () => {
|
||||
it('throws when a plugin declares a brainyRange the running brainy is outside', async () => {
|
||||
const brain = memBrain()
|
||||
brain.use(fakePlugin('@fake/incompatible', { brainyRange: '>=999.0.0' }))
|
||||
await expect(brain.init()).rejects.toThrow(/supports brainy|version-matched/)
|
||||
})
|
||||
|
||||
it('does NOT throw when the brainyRange is satisfied', async () => {
|
||||
const brain = memBrain()
|
||||
brain.use(fakePlugin('@fake/compatible', { brainyRange: '>=0.0.0' }))
|
||||
await expect(brain.init()).resolves.toBeUndefined()
|
||||
await brain.close()
|
||||
})
|
||||
|
||||
it('throws (does not swallow) when activate() throws', async () => {
|
||||
const brain = memBrain()
|
||||
brain.use(fakePlugin('@fake/boom', { onActivate: () => { throw new Error('kaboom') } }))
|
||||
await expect(brain.init()).rejects.toThrow(/failed to activate|kaboom/)
|
||||
})
|
||||
|
||||
it('throws on the legacy provider-key cliff (registers hnsw but not vector)', async () => {
|
||||
const brain = memBrain()
|
||||
brain.use(fakePlugin('@fake/old-cor', {
|
||||
onActivate: (ctx) => { ctx.registerProvider('hnsw', {}); return true }
|
||||
}))
|
||||
await expect(brain.init()).rejects.toThrow(/legacy vector provider|requires/)
|
||||
})
|
||||
|
||||
it('a graceful decline (activate()→false) is non-fatal — init succeeds on the default engine', async () => {
|
||||
// Decline is a documented, non-fatal path (brainy logs a loud warning and
|
||||
// uses the default engine for that plugin's providers). The contract that
|
||||
// matters here: it does NOT abort init the way a hard failure does.
|
||||
const brain = memBrain()
|
||||
brain.use(fakePlugin('@fake/declines', { onActivate: () => false }))
|
||||
await expect(brain.init()).resolves.toBeUndefined()
|
||||
await brain.close()
|
||||
})
|
||||
|
||||
it('throws when an explicitly-listed plugin package cannot be loaded', async () => {
|
||||
const brain = new Brainy({
|
||||
requireSubtype: false,
|
||||
storage: { type: 'memory' },
|
||||
silent: true,
|
||||
plugins: ['@soulcraft/this-package-does-not-exist-xyz']
|
||||
})
|
||||
await expect(brain.init()).rejects.toThrow(/could not be loaded|config\.plugins/)
|
||||
})
|
||||
})
|
||||
|
|
@ -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', () => {
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue