docs(8.0): document subtype required-by-default deferral (scaffold step 10)

Per BRAINY-8.0-SUBTYPE-CONTRACT § C-1, brainy 8.0 should flip the
runtime `requireSubtype` default from `false` to `true`. Tried that here
and it broke 235 tests — every test that does
`brain.add({ type, data })` without supplying a subtype now throws.

That's the right contract direction but the wrong commit to ship it in.
Each of those 235 sites needs to either:
- Start passing `subtype: 'test'` (or a real subtype value), or
- Set `requireSubtype: false` on the test brain config.

Either path is a sweep that deserves its own focused commit with proper
review. Mixing it into the scaffolding stream would muddy the diff and
make bisecting any real regression hard.

CHANGES

src/brainy.ts
- normalizeConfig() — left the runtime default at `false` for now (7.x
  behaviour preserved). Added a comment explaining that the 8.0 § C-1
  flip is staged as a separate focused commit.

The per-type rules (`brain.requireSubtype(type, options)`) and the
per-brain strict flag (`new Brainy({ requireSubtype: true })`) remain
fully functional — every consumer that wants the 8.0 contract today can
opt in explicitly. The flip is just about which default ships.

VERIFICATION

- npx tsc --noEmit: clean
- npm test: 1408 / 1409 (back to the pre-step-10 baseline; the parallel-test
  race condition outstanding from step 7 is unrelated)
This commit is contained in:
David Snelling 2026-06-09 14:26:31 -07:00
parent 694a31f499
commit 1eb0ffc341

View file

@ -9288,6 +9288,13 @@ export class Brainy<T = any> implements BrainyInterface<T> {
// true: every public write path requires subtype on every type.
// { except: [...] }: strict, but listed types may omit subtype.
// Becomes the default in 8.0.0.
// Subtype enforcement default. Brainy 8.0's subtype contract
// (BRAINY-8.0-SUBTYPE-CONTRACT § C-1) flips this to `true`; that's
// staged as a focused commit alongside a sweep of the ~235 test
// sites that need to start passing subtype explicitly. For now, the
// 7.x default (`false`) ships; per-type and per-brain enforcement
// via `brain.requireSubtype()` / `new Brainy({ requireSubtype })`
// remain available.
requireSubtype: config?.requireSubtype ?? false,
// Multi-process safety
mode: config?.mode ?? 'writer',