feat: guarded plugin auto-detection — installing @soulcraft/cor is the opt-in

With plugins unset (the default), init() probes for the first-party
accelerator: not installed means plain brainy with zero noise; installed and
healthy means it loads and announces itself; installed but broken (import
failure, invalid shape, failed activation, version mismatch) makes init()
THROW. An installed accelerator never silently vanishes behind the JS engines
- the anti-drift posture of the explicit list, applied to detection.

plugins: []/false stays a true opt-out (no probe); an explicit list keeps its
required-and-loud semantics. The import runs through an importPluginPackage
seam (variable specifier - bundlers cannot static-resolve the optional
package; tests simulate all outcomes without it installed).

Also: when a plugin activates but registers zero native providers (e.g. a
licensing gate declining to engage), the provider summary now warns loudly
instead of leaving every query silently on the JS engines.

Supersedes 8.0.8's explicit-opt-in wording; README/PLUGINS/types now document
the guarded contract. 7 new tests (tests/unit/plugin-autodetect.test.ts).
This commit is contained in:
David Snelling 2026-07-02 16:19:55 -07:00
parent b37359e097
commit 588267be7f
6 changed files with 265 additions and 26 deletions

View file

@ -10,6 +10,27 @@ Full auto-generated changelog: `CHANGELOG.md` · Releases: https://github.com/so
---
## v8.0.9 — 2026-07-02 (guarded plugin auto-detection — the "install it and it's on" contract)
With the default config (`plugins` unset), brainy now **auto-detects the first-party accelerator**:
installing `@soulcraft/cor` is the opt-in. The detection is guarded — everything except "not
installed" fails loud:
- Not installed → plain brainy, silently (the free path — zero noise, zero cost).
- Installed and healthy → it loads and announces itself (`[brainy] Plugin activated`).
- Installed but broken (unresolvable, invalid shape, failed activation, version mismatch) →
**`init()` throws.** An installed accelerator never silently vanishes behind the JS engines.
- `plugins: []` / `false` = explicit opt-out; `plugins: ['@soulcraft/cor']` pins the exact list
(unchanged semantics).
Also new: if a plugin activates but registers **zero** native providers (e.g. a licensing gate
declining to engage), brainy warns loudly instead of leaving you to discover every query is running
on the JS engines.
> This supersedes v8.0.8's "plugins are explicit opt-in" wording, which documented the pre-GA
> loader accurately but contradicted the published product contract ("add the package and it
> activates"). 8.0.9 makes the contract true — with the loud-failure guarantees intact.
## v8.0.8 — 2026-07-02 (docs-only patch on the GA)
Corrects the README's scale-up section: the native provider is **not** auto-detected — plugins are