From 1eb0ffc3412dff4a9fe591af20068749c284dae5 Mon Sep 17 00:00:00 2001
From: David Snelling <david@soulcraft.com>
Date: Tue, 9 Jun 2026 14:26:31 -0700
Subject: [PATCH] docs(8.0): document subtype required-by-default deferral
 (scaffold step 10)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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)
---
 src/brainy.ts | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/brainy.ts b/src/brainy.ts
index 61f8a8bb..632719c9 100644
--- a/src/brainy.ts
+++ b/src/brainy.ts
@@ -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',