feat(8.0)!: flip requireSubtype default to true (BRAINY-8.0-SUBTYPE-CONTRACT § C-1)

Brainy 8.0 makes subtype required by default on every public write path
(`add`, `addMany`, `update`, `relate`, `relateMany`, `updateRelation`,
import). Per the locked C-1 contract, every entity and relation gets a
non-empty subtype string by the time the storage layer sees it.

OPT-OUT REMAINS FULLY SUPPORTED

The runtime flag is still consumer-controlled. Three opt-out paths
cover migration / legacy fixtures / typed escape:

- `new Brainy({ requireSubtype: false })` — last-resort: turn off the
  contract entirely. Recommended only for migration windows or test
  fixtures that legitimately can't supply a subtype.
- `new Brainy({ requireSubtype: { except: [NounType.Thing, ...] } })` —
  per-type allowlist: strict everywhere except the listed types.
- `brain.requireSubtype(type, options)` — per-type registration with
  optional vocabulary. Composes with the brain-wide flag.

Default is now `true`. Opt-out is explicit and documented; nothing
silently degrades.

TEST SWEEP

Bulk-applied `requireSubtype: false` to every `new Brainy({...})` call
site across 120 test files. Three sed patterns covered the shapes:
  - `new Brainy({` → `new Brainy({ requireSubtype: false,`
  - `new Brainy<T>({` → `new Brainy<T>({ requireSubtype: false,`
  - `new Brainy()` → `new Brainy({ requireSubtype: false })`

tests/helpers/test-factory.ts → createTestConfig() defaults
`requireSubtype: false` so test files using the helper inherit the
opt-out without per-site edits.

The test sites that DO exercise subtype semantics (the
subtype-and-facets suite, the strict-mode-self-test suite, the verb-
subtype-and-enforcement suite, etc.) already pass real subtypes — they
were the 7.30.x acceptance tests for this contract. Those tests
continue to pass unchanged.

CHANGES

src/brainy.ts
- normalizeConfig() — `requireSubtype` default `false` → `true`.
  Comment refreshed to document the three opt-out paths.

tests/* (120 files)
- Bulk-edited brain construction sites. No functional test changes; the
  opt-out preserves the test author's original intent.

tests/helpers/test-factory.ts
- createTestConfig() base config gains `requireSubtype: false`.

NO-OP for consumers who were already passing subtype on every write.

For consumers who weren't, the upgrade path is one of the three opt-out
forms above. Migration recipe documented in 8.0 release notes (next
commit).

VERIFICATION

- npx tsc --noEmit: clean
- npm test: 1408 / 1409 (same pre-existing race-condition outstanding;
  no other regressions from the flip)

tests/unit/brainy-core.unit.test.ts

@@ -14,7 +14,7 @@ describe('Brainy 3.0 Core (Unit Tests)', () => {
 
   beforeEach(async () => {
     // Create instance with real embeddings for production-ready tests
-    brain = new Brainy({
+    brain = new Brainy({ requireSubtype: false,
       storage: { type: 'memory' }
     })
     

tests/unit/brainy-get-optimization.test.ts

@@ -22,7 +22,7 @@ describe('brain.get() Metadata-Only Optimization (v5.11.1)', () => {
   let entityId: string
 
   beforeEach(async () => {
-    brain = new Brainy({
+    brain = new Brainy({ requireSubtype: false,
       storage: new MemoryStorage(),
       silent: true
     })

tests/unit/brainy/batch-operations.test.ts

@@ -6,7 +6,7 @@ describe('Brainy Batch Operations', () => {
   let brain: Brainy<any>
   
   beforeEach(async () => {
-    brain = new Brainy({ storage: { type: 'memory' } })
+    brain = new Brainy({ requireSubtype: false, storage: { type: 'memory' } })
     await brain.init()
   })
   

tests/unit/brainy/find.test.ts

@@ -7,7 +7,7 @@ describe('Brainy.find()', () => {
   let brain: Brainy<any>
 
   beforeEach(async () => {
-    brain = new Brainy({
+    brain = new Brainy({ requireSubtype: false,
       storage: { type: 'memory' }  // Use memory storage for isolation
     })
     await brain.init()

tests/unit/brainy/hybrid-search.test.ts

@@ -14,7 +14,7 @@ describe('Hybrid Search (v7.7.0)', () => {
   let brain: Brainy<any>
 
   beforeEach(async () => {
-    brain = new Brainy({
+    brain = new Brainy({ requireSubtype: false,
       storage: { type: 'memory' }
     })
     await brain.init()

tests/unit/brainy/relate-duplicate-optimization.test.ts

@@ -13,7 +13,7 @@ describe('Duplicate Check Optimization', () => {
   let brain: Brainy
 
   beforeEach(async () => {
-    brain = new Brainy()
+    brain = new Brainy({ requireSubtype: false })
     await brain.init()
   })
 

tests/unit/create-entities-default.test.ts

@@ -20,7 +20,7 @@ describe('createEntities Default Value (v4.3.2 Bug Fix)', () => {
       fs.rmSync(testDir, { recursive: true })
     }
 
-    brain = new Brainy({
+    brain = new Brainy({ requireSubtype: false,
       storage: {
         type: 'filesystem',
         path: testDir

tests/unit/graph/graphIndex-pagination.test.ts

@@ -19,7 +19,7 @@ describe('GraphAdjacencyIndex Pagination', () => {
   let neighborIds: string[]
 
   beforeEach(async () => {
-    brain = new Brainy()
+    brain = new Brainy({ requireSubtype: false })
     await brain.init()
 
     // Create central entity

tests/unit/import/InstancePool.test.ts

@@ -7,7 +7,7 @@ describe('InstancePool', () => {
   let pool: InstancePool
 
   beforeEach(async () => {
-    brain = new Brainy({ storage: { type: 'memory' } })
+    brain = new Brainy({ requireSubtype: false, storage: { type: 'memory' } })
     await brain.init()
     pool = new InstancePool(brain)
   })

tests/unit/import/preserve-source-fix.test.ts

@@ -19,7 +19,7 @@ describe('Import preserveSource Fix (v5.1.2)', () => {
   let testFilePath: string
 
   beforeEach(async () => {
-    brain = new Brainy({
+    brain = new Brainy({ requireSubtype: false,
       storage: { type: 'memory' },
       silent: true
     })

tests/unit/neural/NaturalLanguageProcessor.test.ts

@@ -13,7 +13,7 @@ describe('NaturalLanguageProcessor', () => {
   let nlp: NaturalLanguageProcessor
   
   beforeEach(async () => {
-    brain = new Brainy({ storage: { type: 'memory' } })
+    brain = new Brainy({ requireSubtype: false, storage: { type: 'memory' } })
     await brain.init()
     nlp = new NaturalLanguageProcessor(brain)
     

tests/unit/neural/domain-time-clustering.test.ts

@@ -14,7 +14,7 @@ describe('Domain and Time Clustering', () => {
   let brain: Brainy
 
   beforeEach(async () => {
-    brain = new Brainy({
+    brain = new Brainy({ requireSubtype: false,
       enableCache: false,
       storage: { type: 'memory' } // Use memory storage for tests
     })

tests/unit/neural/neural-simplified.test.ts

@@ -13,7 +13,7 @@ describe('Neural API - Production Testing', () => {
 
   // v5.1.0: Use memory storage and disable augmentations for faster, reliable tests
   beforeEach(async () => {
-    brain = new Brainy({
+    brain = new Brainy({ requireSubtype: false,
       storage: { type: 'memory' },
       silent: true
     })

tests/unit/neural/signals/EmbeddingSignal.test.ts

@@ -8,7 +8,7 @@ describe('EmbeddingSignal', () => {
   let signal: EmbeddingSignal
 
   beforeEach(async () => {
-    brain = new Brainy({ storage: { type: 'memory' } })
+    brain = new Brainy({ requireSubtype: false, storage: { type: 'memory' } })
     await brain.init()
     signal = new EmbeddingSignal(brain)
   })

tests/unit/performance/add-performance.test.ts

@@ -16,7 +16,7 @@ describe('add() Performance Regression Tests', () => {
   let brain: Brainy
 
   beforeEach(async () => {
-    brain = new Brainy({
+    brain = new Brainy({ requireSubtype: false,
       storage: { type: 'memory' },
       silent: true
     })

tests/unit/plugin.test.ts

@@ -211,7 +211,7 @@ describe('Brainy plugin integration', () => {
       }
     }
 
-    const brain = new Brainy({
+    const brain = new Brainy({ requireSubtype: false,
       storage: { type: 'memory' },
       silent: true,
     })
@@ -240,7 +240,7 @@ describe('Brainy plugin integration', () => {
       }
     }
 
-    const brain = new Brainy({
+    const brain = new Brainy({ requireSubtype: false,
       storage: { type: 'memory' },
       silent: true,
     })
@@ -258,7 +258,7 @@ describe('Brainy plugin integration', () => {
       activate: async () => false
     }
 
-    const brain = new Brainy({
+    const brain = new Brainy({ requireSubtype: false,
       storage: { type: 'memory' },
       silent: true,
     })
@@ -287,7 +287,7 @@ describe('Brainy plugin integration', () => {
       }
     }
 
-    const brain = new Brainy({
+    const brain = new Brainy({ requireSubtype: false,
       storage: { type: 'memory' },
       silent: true,
     })
@@ -313,7 +313,7 @@ describe('Brainy plugin integration', () => {
       activate: async () => true
     }
 
-    const brain = new Brainy({ storage: { type: 'memory' } })
+    const brain = new Brainy({ requireSubtype: false, storage: { type: 'memory' } })
     const result = brain.use(plugin)
     expect(result).toBe(brain)
   })

tests/unit/storage/vfs-mkdir-bug.test.ts

@@ -21,7 +21,7 @@ describe('VFS mkdir() Bug Fix (v6.2.9)', () => {
   let brain: Brainy
 
   beforeEach(async () => {
-    brain = new Brainy({
+    brain = new Brainy({ requireSubtype: false,
       storage: { type: 'memory' }
     })
     await brain.init()

tests/unit/type-filtering.unit.test.ts

@@ -11,7 +11,7 @@ describe('Type Filtering (A Consumer Team Issue)', () => {
   let brain: Brainy
 
   beforeEach(async () => {
-    brain = new Brainy({
+    brain = new Brainy({ requireSubtype: false,
       storage: { type: 'memory' }
     })
     await brain.init()

tests/unit/utils/entity-id-mapper-stability.test.ts

@@ -32,7 +32,7 @@ describe('EntityIdMapper stability (foundation for 2.4.0)', () => {
   let brain: Brainy
 
   beforeEach(async () => {
-    brain = new Brainy({ storage: { type: 'memory' }, silent: true })
+    brain = new Brainy({ requireSubtype: false, storage: { type: 'memory' }, silent: true })
     await brain.init()
   })
 

tests/unit/utils/memoryLimits.test.ts

@@ -196,7 +196,7 @@ describe('Memory Limits - Container Detection & Smart Calculation', () => {
 
   describe('Brain Integration', () => {
     it('should configure memory limits via Brain constructor', async () => {
-      const brain = new Brainy({
+      const brain = new Brainy({ requireSubtype: false,
         storage: { type: 'memory' },
         maxQueryLimit: 15000,
         silent: true
@@ -214,7 +214,7 @@ describe('Memory Limits - Container Detection & Smart Calculation', () => {
     })
 
     it('should configure reserved memory via Brain constructor', async () => {
-      const brain = new Brainy({
+      const brain = new Brainy({ requireSubtype: false,
         storage: { type: 'memory' },
         reservedQueryMemory: 500 * 1024 * 1024, // 500 MB
         silent: true
@@ -236,7 +236,7 @@ describe('Memory Limits - Container Detection & Smart Calculation', () => {
     it('should auto-detect container limits when no config provided', async () => {
       process.env.CLOUD_RUN_MEMORY = '2Gi'
 
-      const brain = new Brainy({
+      const brain = new Brainy({ requireSubtype: false,
         storage: { type: 'memory' },
         silent: true
       })
@@ -260,7 +260,7 @@ describe('Memory Limits - Container Detection & Smart Calculation', () => {
     it('should return complete memory statistics', async () => {
       process.env.CLOUD_RUN_MEMORY = '4Gi'
 
-      const brain = new Brainy({
+      const brain = new Brainy({ requireSubtype: false,
         storage: { type: 'memory' },
         maxQueryLimit: 20000,
         silent: true
@@ -301,7 +301,7 @@ describe('Memory Limits - Container Detection & Smart Calculation', () => {
       process.env.CLOUD_RUN_MEMORY = '4Gi'
 
       // Don't set overrides, let it use containerMemory
-      const brain = new Brainy({
+      const brain = new Brainy({ requireSubtype: false,
         storage: { type: 'memory' },
         silent: true
       })
@@ -317,7 +317,7 @@ describe('Memory Limits - Container Detection & Smart Calculation', () => {
     })
 
     it('should handle browser environment gracefully', async () => {
-      const brain = new Brainy({
+      const brain = new Brainy({ requireSubtype: false,
         storage: { type: 'memory' },
         silent: true
       })
@@ -338,7 +338,7 @@ describe('Memory Limits - Container Detection & Smart Calculation', () => {
     it('should handle 4GB Cloud Run container optimally', async () => {
       process.env.CLOUD_RUN_MEMORY = '4Gi'
 
-      const brain = new Brainy({
+      const brain = new Brainy({ requireSubtype: false,
         storage: { type: 'memory' },
         silent: true
       })
@@ -360,7 +360,7 @@ describe('Memory Limits - Container Detection & Smart Calculation', () => {
     it('should allow manual override for power users', async () => {
       process.env.CLOUD_RUN_MEMORY = '4Gi'
 
-      const brain = new Brainy({
+      const brain = new Brainy({ requireSubtype: false,
         storage: { type: 'memory' },
         maxQueryLimit: 50000, // Power user wants higher limit
         silent: true
@@ -383,7 +383,7 @@ describe('Memory Limits - Container Detection & Smart Calculation', () => {
     it('should handle bare metal deployment (no container)', async () => {
       // No container env vars
 
-      const brain = new Brainy({
+      const brain = new Brainy({ requireSubtype: false,
         storage: { type: 'memory' },
         silent: true
       })

tests/unit/utils/resultRanking.test.ts

@@ -169,7 +169,7 @@ describe('resultRanking — Brainy.find() integration', () => {
 
   it('routes find() relevance ranking through a registered sort:topK provider', async () => {
     const calls: Array<{ k: number; descending: boolean; n: number }> = []
-    const brain = new Brainy({ storage: { type: 'memory' }, silent: true })
+    const brain = new Brainy({ requireSubtype: false, storage: { type: 'memory' }, silent: true })
     brain.use(makeSortTopKPlugin(calls))
     await brain.init()
     await seed(brain)
@@ -195,7 +195,7 @@ describe('resultRanking — Brainy.find() integration', () => {
     // order, and scores must match exactly. (Two separate brains would differ due to
     // independent approximate-NN candidate selection, not the ranking hook.)
     const calls: Array<{ k: number; descending: boolean; n: number }> = []
-    const brain = new Brainy({ storage: { type: 'memory' }, silent: true })
+    const brain = new Brainy({ requireSubtype: false, storage: { type: 'memory' }, silent: true })
     brain.use(makeSortTopKPlugin(calls))
     await brain.init()
     await seed(brain)
@@ -219,7 +219,7 @@ describe('resultRanking — Brainy.find() integration', () => {
     // rather than relying on cross-query ANN stability. Also assert the provider is asked
     // for the full page (offset + limit), which is what makes pagination correct.
     const calls: Array<{ k: number; descending: boolean; n: number }> = []
-    const brain = new Brainy({ storage: { type: 'memory' }, silent: true })
+    const brain = new Brainy({ requireSubtype: false, storage: { type: 'memory' }, silent: true })
     brain.use(makeSortTopKPlugin(calls))
     await brain.init()
     await seed(brain)

tests/unit/vfs-multi-instance-diagnostic.test.ts

@@ -11,7 +11,7 @@ describe('VFS Multi-instance Diagnostic', () => {
   let brain: Brainy
 
   beforeEach(async () => {
-    brain = new Brainy({
+    brain = new Brainy({ requireSubtype: false,
       storage: { type: 'memory' }
     })
     await brain.init()

tests/unit/vfs-restart-fix.test.ts

@@ -20,7 +20,7 @@ describe('VFS restart persistence', () => {
 
     try {
       // === SESSION 1: Write data ===
-      let brain = new Brainy({
+      let brain = new Brainy({ requireSubtype: false,
         storage: { type: 'filesystem', rootDirectory: dir },
         disableAutoRebuild: true,
         plugins: [],
@@ -47,7 +47,7 @@ describe('VFS restart persistence', () => {
       await brain.close()
 
       // === SESSION 2: Read data after restart ===
-      brain = new Brainy({
+      brain = new Brainy({ requireSubtype: false,
         storage: { type: 'filesystem', rootDirectory: dir },
         disableAutoRebuild: true,
         plugins: [],
@@ -86,7 +86,7 @@ describe('VFS restart persistence', () => {
 
     try {
       // === SESSION 1: Write multiple files ===
-      let brain = new Brainy({
+      let brain = new Brainy({ requireSubtype: false,
         storage: { type: 'filesystem', rootDirectory: dir },
         disableAutoRebuild: true,
         plugins: [],
@@ -111,7 +111,7 @@ describe('VFS restart persistence', () => {
       await brain.close()
 
       // === SESSION 2: Verify all data persisted ===
-      brain = new Brainy({
+      brain = new Brainy({ requireSubtype: false,
         storage: { type: 'filesystem', rootDirectory: dir },
         disableAutoRebuild: true,
         plugins: [],

tests/unit/vfs/blob-storage-integration.test.ts

@@ -26,7 +26,7 @@ describe('VFS Unified BlobStorage (v5.2.0)', () => {
     testDir = path.join('/tmp', `brainy-test-blob-${Date.now()}-${Math.random().toString(36).slice(2)}`)
     await fs.mkdir(testDir, { recursive: true })
 
-    brain = new Brainy({
+    brain = new Brainy({ requireSubtype: false,
       storage: {
         type: 'filesystem',
         options: { path: testDir }