Merge remote-tracking branch 'origin/test/close-every-brain' into tmp/ob-main-merge

tests/integration/api-parameter-validation.test.ts

@@ -34,6 +34,10 @@ describe('API Parameter Validation', () => {
     })
   })
 
+  afterAll(async () => {
+    await brain.close()
+  })
+
   it('should use "where" parameter for metadata filtering', async () => {
     const results = await brain.find({
       where: { category: 'test-category' },

tests/integration/entity-confidence-weight.test.ts

@@ -7,7 +7,7 @@
  * - Backward compatibility preserved
  */
 
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { Brainy } from '../../src/brainy.js'
 import { NounType } from '../../src/types/graphTypes.js'
 
@@ -19,6 +19,10 @@ describe('Entity Confidence & Weight Exposure', () => {
     await brain.init()
   })
 
+  afterEach(async () => {
+    await brain.close()
+  })
+
   describe('Entity interface', () => {
     it('should expose confidence when adding entity with confidence', async () => {
       const id = await brain.add({

tests/integration/find-fields-projection.test.ts

@@ -19,7 +19,7 @@
  * index-served (a body field, or a bucketed timestamp), exactly the owing rows
  * are read and the rest are still served from the index.
  */
-import { describe, it, expect, beforeAll, vi } from 'vitest'
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest'
 import { Brainy } from '../../src/brainy'
 import { NounType } from '../../src/types/graphTypes'
 import { generateTestVector } from '../helpers/test-factory'
@@ -59,6 +59,10 @@ describe('find/get({ fields }) — projection', () => {
     await brain.flush()
   })
 
+  afterAll(async () => {
+    await brain.close()
+  })
+
   /** Count canonical record reads for one call. */
   const countingReads = async <R>(body: () => Promise<R>): Promise<{ out: R; reads: number }> => {
     const spy = vi.spyOn(brain as any, 'batchGet')

tests/integration/find-hybrid-filter-before-hydrate.test.ts

@@ -31,7 +31,7 @@
  * never the legs. And the text leg is asked about the universe's ids only —
  * what it marshals is bounded by the universe, not by the store.
  */
-import { describe, it, expect, beforeAll, vi } from 'vitest'
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest'
 import { Brainy } from '../../src/brainy'
 import { NounType, VerbType } from '../../src/types/graphTypes'
 import { rankIndicesByScore, reorderByIndices } from '../../src/utils/resultRanking'
@@ -287,6 +287,10 @@ describe('hybrid find: filter before hydrate — the answer is unchanged', () =>
     expect(typeof (brain as any).metadataIndex.getIdSetForFilter).not.toBe('function')
   })
 
+  afterAll(async () => {
+    await brain.close()
+  })
+
   it('the fixture does not truncate the text leg — the universe covers every text match', async () => {
     const index = (brain as any).metadataIndex
     const textMatches = await index.getIdsForTextQuery(QUERY)
@@ -553,6 +557,10 @@ describe('hybrid find: the text leg ranks inside the filter, not around it', ()
     }
   })
 
+  afterAll(async () => {
+    await brain.close()
+  })
+
   it('the old order let the filter consume the whole text leg', async () => {
     const index = (brain as any).metadataIndex
     const universe: string[] = await (brain as any).filterIdsBelted({ lane: 'alpha' })

tests/integration/find-near.test.ts

@@ -9,7 +9,7 @@
  * it). Now the anchor is fetched with its vector, and an anchor without one
  * refuses by name instead of failing inside the index.
  */
-import { describe, it, expect, beforeAll } from 'vitest'
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
 import { Brainy } from '../../src/brainy'
 import { NounType } from '../../src/types/graphTypes'
 import { v5 } from '../../src/universal/uuid'
@@ -28,6 +28,10 @@ describe('find({ near }) uses the anchor vector', () => {
     await brain.add({ id: 'far', data: 'far row', type: NounType.Thing, vector: generateTestVector() })
   })
 
+  afterAll(async () => {
+    await brain.close()
+  })
+
   it('returns the anchor\'s neighbours by its own vector', async () => {
     const results = await brain.find({ near: { id: 'anchor' }, limit: 3 })
     expect(results.length).toBeGreaterThan(0)

tests/integration/find-orderby-every-path.test.ts

@@ -40,7 +40,7 @@
  * the covering is ASSERTED from the leg's own output rather than assumed. This
  * pin is about ordering, and it says nothing about recall.
  */
-import { describe, it, expect, beforeAll } from 'vitest'
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
 import { Brainy } from '../../src/brainy'
 import { NounType, VerbType } from '../../src/types/graphTypes'
 import { resolveEntityId } from '../../src/utils/idNormalization'
@@ -107,6 +107,10 @@ describe('find(): orderBy is the order on every path', () => {
     }
   })
 
+  afterAll(async () => {
+    await brain.close()
+  })
+
   it('the fixture: the hybrid candidate set covers the whole filter universe', async () => {
     const universe: string[] = await (brain as any).filterIdsBelted({ lane: 'alpha' })
     expect(universe).toHaveLength(ROWS)

tests/integration/find-planner-door.test.ts

@@ -23,7 +23,7 @@
  * against the adjacency before it is believed, so a not-serving graph refuses
  * loudly instead of answering `[]` as truth.
  */
-import { describe, it, expect, beforeAll, vi } from 'vitest'
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest'
 import { Brainy } from '../../src/brainy'
 import { NounType, VerbType } from '../../src/types/graphTypes'
 import { generateTestVector } from '../helpers/test-factory'
@@ -56,6 +56,10 @@ describe('find(): the optional planner door', () => {
     }
   })
 
+  afterAll(async () => {
+    await brain.close()
+  })
+
   /** Install a planner door for one call, then remove it. */
   const withDoor = async <T>(
     door: (...a: any[]) => Promise<any>,

tests/integration/find-unified-integration.test.ts

@@ -48,6 +48,7 @@ describe('Unified Find() Integration Tests', () => {
 
   afterAll(async () => {
     await cleanup.cleanup()
+    await brain.close()
     brain = null as any
   })
 

tests/integration/id-normalization.test.ts

@@ -18,7 +18,7 @@
  * All entities carry explicit 384-dim vectors so no test invokes the embedder.
  */
 
-import { describe, it, expect } from 'vitest'
+import { describe, it, expect, afterEach } from 'vitest'
 import { Brainy } from '../../src/brainy.js'
 import { NounType, VerbType } from '../../src/types/graphTypes.js'
 import { v5, v7, isUUID } from '../../src/universal/uuid.js'
@@ -37,8 +37,15 @@ async function makeBrain(): Promise<Brainy> {
 }
 
 describe('id normalization — transparent string-key round-trips', () => {
+  const opened: Brainy[] = []
+
+  afterEach(async () => {
+    for (const b of opened.splice(0)) await b.close().catch(() => {})
+  })
+
   it('1. add() returns v5(key); get(key) and get(returnedId) both resolve; _originalId preserved', async () => {
     const brain = await makeBrain()
+    opened.push(brain)
 
     const returnedId = await brain.add({ id: 'user-1', vector: vec(1), type: NounType.Person })
 
@@ -60,6 +67,7 @@ describe('id normalization — transparent string-key round-trips', () => {
 
   it('2. relate() by string keys; related(key) and related({from:key}) return the edge to v5(toKey)', async () => {
     const brain = await makeBrain()
+    opened.push(brain)
 
     await brain.add({ id: 'user-1', vector: vec(1), type: NounType.Person })
     await brain.add({ id: 'doc-1', vector: vec(2), type: NounType.Document })
@@ -85,6 +93,7 @@ describe('id normalization — transparent string-key round-trips', () => {
 
   it('3. update() by string key reflects on get(key)', async () => {
     const brain = await makeBrain()
+    opened.push(brain)
 
     await brain.add({ id: 'user-1', vector: vec(1), type: NounType.Person, metadata: { role: 'admin' } })
     await brain.update({ id: 'user-1', metadata: { role: 'owner' } })
@@ -98,6 +107,7 @@ describe('id normalization — transparent string-key round-trips', () => {
 
   it('4. remove() by string key deletes; get(key) is null', async () => {
     const brain = await makeBrain()
+    opened.push(brain)
 
     await brain.add({ id: 'user-1', vector: vec(1), type: NounType.Person })
     expect(await brain.get('user-1')).not.toBeNull()
@@ -110,6 +120,7 @@ describe('id normalization — transparent string-key round-trips', () => {
 
   it('5. find({ connected: { from: key } }) resolves the anchor key', async () => {
     const brain = await makeBrain()
+    opened.push(brain)
 
     await brain.add({ id: 'user-1', vector: vec(1), type: NounType.Person })
     await brain.add({ id: 'doc-1', vector: vec(2), type: NounType.Document })
@@ -122,6 +133,7 @@ describe('id normalization — transparent string-key round-trips', () => {
 
   it('6. transact() add+relate by string keys round-trips with consistent canonical ids', async () => {
     const brain = await makeBrain()
+    opened.push(brain)
 
     // Seed user-1 so the relate op has a target to point at.
     await brain.add({ id: 'user-1', vector: vec(1), type: NounType.Person })
@@ -149,6 +161,7 @@ describe('id normalization — transparent string-key round-trips', () => {
 
   it('7. addMany() + relateMany() with string ids round-trip', async () => {
     const brain = await makeBrain()
+    opened.push(brain)
 
     const added = await brain.addMany({
       items: [
@@ -175,6 +188,7 @@ describe('id normalization — transparent string-key round-trips', () => {
 
   it('8. determinism: same key maps to same UUID — two adds upsert ONE entity, not two', async () => {
     const brain = await makeBrain()
+    opened.push(brain)
 
     const id1 = await brain.add({ id: 'user-1', vector: vec(1), type: NounType.Person, metadata: { n: 1 } })
     const id2 = await brain.add({ id: 'user-1', vector: vec(1), type: NounType.Person, metadata: { n: 2 } })
@@ -193,6 +207,7 @@ describe('id normalization — transparent string-key round-trips', () => {
 
   it('9. valid-UUID passthrough: a real UUID is kept verbatim with NO _originalId', async () => {
     const brain = await makeBrain()
+    opened.push(brain)
 
     const realUuid = v7()
     const returnedId = await brain.add({ id: realUuid, vector: vec(5), type: NounType.Thing })
@@ -207,6 +222,7 @@ describe('id normalization — transparent string-key round-trips', () => {
 
   it('10. no-id add() mints a v7; newId() mints a v7', async () => {
     const brain = await makeBrain()
+    opened.push(brain)
 
     const autoId = await brain.add({ vector: vec(6), type: NounType.Thing })
     expect(isUUID(autoId)).toBe(true)

tests/integration/multi-process-safety.test.ts

@@ -107,7 +107,11 @@ describe('Multi-process safety + read-only mode', () => {
 
       const blocked = new Brainy({ requireSubtype: false, storage: { type: 'filesystem', path: dir } })
       await expect(blocked.init()).rejects.toThrow(/another writer holds/i)
-      // Don't track `blocked` for afterEach cleanup since init failed.
+      // A rejected init() still registered `blocked` in Brainy's global
+      // instance registry (the constructor does that unconditionally) — close()
+      // is safe to call even though init() never completed, and is what
+      // deregisters it (and, once idle, the process-level shutdown hooks).
+      await blocked.close().catch(() => {})
     })
 
     it('takes over a STALE foreign lock (dead PID + old heartbeat) and claims atomically', async () => {
@@ -151,6 +155,7 @@ describe('Multi-process safety + read-only mode', () => {
       const err: any = await blocked.init().catch((e) => e)
       expect(err.code).toBe('BRAINY_WRITER_LOCKED')
       expect(err.lockInfo?.pid).toBe(otherPid)
+      await blocked.close().catch(() => {})
     })
 
     it('release drains an in-flight heartbeat — no phantom lock re-created after unlink', async () => {

tests/integration/related-verb-array.test.ts

@@ -30,6 +30,7 @@ describe('related() with a verb-type array returns every requested type', () =>
   })
 
   afterAll(async () => {
+    await brain.close()
     brain = null as any
   })
 

tests/integration/relationship-intelligence.test.ts

@@ -59,7 +59,8 @@ describe('Relationship Intelligence', () => {
     await brain.init()
   })
 
-  afterEach(() => {
+  afterEach(async () => {
+    await brain.close()
     if (fs.existsSync(testDir)) {
       fs.rmSync(testDir, { recursive: true })
     }

tests/integration/rev-and-ifabsent.test.ts

@@ -9,7 +9,7 @@
  *   - addMany({ ifAbsent: true }) applies the flag to every item
  */
 
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { Brainy } from '../../src/brainy.js'
 import { RevisionConflictError } from '../../src/transaction/RevisionConflictError.js'
 import { NounType } from '../../src/types/graphTypes.js'
@@ -22,6 +22,10 @@ describe('7.31.0 — _rev CAS + ifAbsent', () => {
     await brain.init()
   })
 
+  afterEach(async () => {
+    await brain.close()
+  })
+
   describe('_rev initialization + surface', () => {
     it('initializes _rev to 1 on add()', async () => {
       const id = await brain.add({ data: 'hello', type: NounType.Document })

tests/integration/vfs-containment-batched.test.ts

@@ -81,6 +81,7 @@ describe('repairContainment: batched pass 2', () => {
   })
 
   afterAll(async () => {
+    await brain.close()
     brain = null as any
   })
 

tests/integration/vfs-debug.test.ts

@@ -9,9 +9,10 @@ import * as XLSX from 'xlsx'
 describe('VFS Debug', () => {
   it('minimal VFS writeFile test', async () => {
     const brain = new Brainy({ requireSubtype: false, storage: { type: 'memory' } })
-    await brain.init()
+    try {
+      await brain.init()
 
-    console.log('✅ Brain initialized')
+      console.log('✅ Brain initialized')
 
     // Get VFS and initialize
     const vfs = brain.vfs
@@ -77,5 +78,8 @@ describe('VFS Debug', () => {
     // THE REAL TEST: Can we query VFS?
     expect(children.length).toBeGreaterThan(0)
     expect(rootContents.length).toBeGreaterThan(0)
+    } finally {
+      await brain.close()
+    }
   })
 })

tests/integration/writer-lock-fencing.test.ts

@@ -61,6 +61,7 @@ describe('writer-lock fencing', () => {
     // Old rule: heartbeat-age eviction → silent takeover → split brain.
     // New rule: live PID = live writer; the second opener throws typed.
     const second = new Brainy({ storage: { type: 'filesystem', path: dir }, requireSubtype: false })
+    brains.push(second)
     await expect(second.init()).rejects.toMatchObject({ code: 'BRAINY_WRITER_LOCKED' })
   }, 120000)
 

tests/performance/typeAware.bench.test.ts

@@ -17,7 +17,7 @@
  * - Note limitations and edge cases
  */
 
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { Brainy } from '../../src/brainy.js'
 import { TypeAwareStorageAdapter } from '../../src/storage/adapters/typeAwareStorageAdapter.js'
 import { FileSystemStorage } from '../../src/storage/adapters/fileSystemStorage.js'
@@ -67,6 +67,10 @@ describe('TypeAware Performance Benchmarks', () => {
       }
     })
 
+    afterEach(async () => {
+      await brainMemory.close()
+    })
+
     it('should measure type-based query performance', async () => {
       // MEASURED: Query for one type (200 entities)
       const start = performance.now()

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

@@ -5,7 +5,7 @@
  * No mocks, no fakes, real implementation
  */
 
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { Brainy } from '../../src/brainy.js'
 import { NounType } from '../../src/types/graphTypes.js'
 
@@ -21,6 +21,10 @@ describe('Brainy 3.0 Core (Unit Tests)', () => {
     await brain.init()
   })
 
+  afterEach(async () => {
+    await brain.close()
+  })
+
   describe('CRUD Operations', () => {
     it('should create items with add', async () => {
       const id = await brain.add({ 

tests/unit/brainy/degraded-reads-surfaced.test.ts

@@ -19,13 +19,19 @@ import { prodLog } from '../../../src/utils/logger.js'
 const UUID = (suffix: string): string => `00000000-0000-4000-8000-0000000000${suffix}`
 
 describe('Finding 10 — degraded derived-index state is surfaced on reads', () => {
+  const opened: Brainy[] = []
+
   beforeEach(() => {
     process.env.BRAINY_DETERMINISTIC_EMBEDDINGS = 'true'
   })
-  afterEach(() => vi.restoreAllMocks())
+  afterEach(async () => {
+    vi.restoreAllMocks()
+    for (const b of opened.splice(0)) await b.close().catch(() => {})
+  })
 
   it('checkHealth() reports adopt-forward degraded ids as unhealthy', async () => {
     const brain = new Brainy({ storage: { type: 'memory' }, dimensions: 384, requireSubtype: false })
+    opened.push(brain)
     await brain.init()
     ;(brain as any)._indexDegradedIds.add(UUID('de'))
 
@@ -37,6 +43,7 @@ describe('Finding 10 — degraded derived-index state is surfaced on reads', ()
   it('find()/get() warn loudly while degraded, ONCE, then repairIndex() clears it', async () => {
     const warn = vi.spyOn(prodLog, 'warn').mockImplementation(() => {})
     const brain = new Brainy({ storage: { type: 'memory' }, dimensions: 384, requireSubtype: false })
+    opened.push(brain)
     await brain.init()
     await brain.add({ id: UUID('a1'), data: 'x', type: NounType.Document })
     ;(brain as any)._indexRebuildFailed = new Error('rebuild boom')
@@ -59,6 +66,7 @@ describe('Finding 10 — degraded derived-index state is surfaced on reads', ()
 
   it('persistSingleOp records receipt.degraded (widened return type, not dropped)', async () => {
     const brain = new Brainy({ storage: { type: 'memory' }, dimensions: 384, requireSubtype: false })
+    opened.push(brain)
     await brain.init()
     // Simulate a degraded receipt by wrapping the generation store's commitSingleOp.
     const gs: any = (brain as any).generationStore

tests/unit/brainy/find-complement-operators.test.ts

@@ -7,7 +7,7 @@
  * soft-delete semantic: `field !== value` MUST include entities that have no
  * such field at all.
  */
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { Brainy } from '../../../src/brainy'
 import { NounType } from '../../../src/types/graphTypes'
 
@@ -26,6 +26,10 @@ describe('find() complement operators (ne / exists:false / missing:true)', () =>
     ids.noField2 = await brain.add({ data: 'n2', type: NounType.Thing, metadata: { other: 2 } })
   })
 
+  afterEach(async () => {
+    await brain.close()
+  })
+
   it('ne returns everything except the matching value — INCLUDING entities without the field', async () => {
     const rows = await brain.find({ where: { status: { ne: 'active' } }, limit: 100 })
     const got = new Set(rows.map((r) => r.id))

tests/unit/brainy/find-index-integrity-guard.test.ts

@@ -12,7 +12,7 @@
  * returns an id whose record matches NEITHER the type nor the where filter) and
  * assert the phantom is dropped while the genuine matches survive.
  */
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { Brainy } from '../../../src/brainy'
 import { NounType } from '../../../src/types/graphTypes'
 
@@ -48,6 +48,10 @@ describe('find() index-integrity guard (phantom row class)', () => {
     })
   })
 
+  afterEach(async () => {
+    await brain.close()
+  })
+
   it('healthy index: the discriminant query returns only the staff Person', async () => {
     const rows = await brain.find({ type: NounType.Person, where: { entityType: 'staff' }, limit: 100 })
     expect(rows.map((r) => r.id)).toEqual([staffId])

tests/unit/brainy/find.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { Brainy } from '../../../src/brainy'
 import { createAddParams } from '../../helpers/test-factory'
 import { NounType } from '../../../src/types/graphTypes'
@@ -12,7 +12,11 @@ describe('Brainy.find()', () => {
     })
     await brain.init()
   })
-  
+
+  afterEach(async () => {
+    await brain.close()
+  })
+
   describe('success paths', () => {
     it('should find entities by text query', async () => {
       // Arrange

tests/unit/brainy/metadata-provider-contract.test.ts

@@ -18,7 +18,7 @@
  * exercised by cor's combined matrix); they inject probe/spy hooks onto the live JS
  * metadata index, which has neither method by default.
  */
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { Brainy } from '../../../src/brainy'
 import { NounType } from '../../../src/types/graphTypes'
 
@@ -34,6 +34,10 @@ describe('metadata-provider contract wiring (getIdsForFilter opts)', () => {
     mi = (brain as any).metadataIndex
   })
 
+  afterEach(async () => {
+    await brain.close()
+  })
+
   it('RETIRED: a read never calls probeConsistency() / self-heals via detectAndRepairCorruption — that is the read-triggered dark rebuild the health-gate law forbids', async () => {
     let probes = 0
     let repairs = 0

tests/unit/brainy/migration-gate-family-scoped.test.ts

@@ -8,7 +8,7 @@
  * gate that hung getStats / readdir / readFile behind an unrelated family's
  * migration until the wait timed out.
  */
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { Brainy } from '../../../src/brainy.js'
 import { MigrationInProgressError } from '../../../src/errors/brainyError.js'
 
@@ -38,12 +38,19 @@ const jam = (provider: unknown) => {
 }
 
 describe('migration LOCK is family-scoped', () => {
+  const opened: Brainy[] = []
+
   beforeEach(() => {
     process.env.BRAINY_DETERMINISTIC_EMBEDDINGS = 'true'
   })
 
+  afterEach(async () => {
+    for (const b of opened.splice(0)) await b.close().catch(() => {})
+  })
+
   it('a stuck VECTOR migration does not block canonical or graph/metadata reads', async () => {
     const brain = await seed()
+    opened.push(brain)
     const childId = (
       (await brain.vfs.readdir('/notes', { withFileTypes: true })) as Array<{ entityId: string }>
     )[0].entityId
@@ -60,6 +67,7 @@ describe('migration LOCK is family-scoped', () => {
 
   it('a stuck VECTOR migration STILL blocks a read that needs the vector family', async () => {
     const brain = await seed()
+    opened.push(brain)
     jam((brain as any).index)
 
     // A semantic query consults the vector index — it must wait, and (bounded by
@@ -70,6 +78,7 @@ describe('migration LOCK is family-scoped', () => {
 
   it('a stuck GRAPH migration blocks traversal but not vector/canonical reads', async () => {
     const brain = await seed()
+    opened.push(brain)
     const childId = (
       (await brain.vfs.readdir('/notes', { withFileTypes: true })) as Array<{ entityId: string }>
     )[0].entityId
@@ -87,6 +96,7 @@ describe('migration LOCK is family-scoped', () => {
 
   it('with no migration in flight, every read serves (the fast path is a no-op)', async () => {
     const brain = await seed()
+    opened.push(brain)
     await expect(brain.getStats()).resolves.toBeDefined()
     await expect(brain.find({ query: 'doc' })).resolves.toBeDefined()
     await expect(brain.vfs.readdir('/notes')).resolves.toHaveLength(1)

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

@@ -18,7 +18,7 @@ describe('Duplicate Check Optimization', () => {
   })
 
   afterEach(async () => {
-    // Cleanup is automatic with memory storage
+    await brain.close()
   })
 
   it('should detect duplicate relationships using GraphAdjacencyIndex', async () => {

tests/unit/get-index-status-readiness.test.ts

@@ -7,7 +7,7 @@
  * _indexRebuildFailed / _indexDegradedIds degraded states (mirroring
  * validateIndexConsistency / checkHealth).
  */
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { Brainy, NounType } from '../../src/index.js'
 
 describe('getIndexStatus honest readiness (Finding 9)', () => {
@@ -20,6 +20,10 @@ describe('getIndexStatus honest readiness (Finding 9)', () => {
     await brain.flush()
   })
 
+  afterEach(async () => {
+    await brain.close()
+  })
+
   it('a not-ready provider makes populated honest (false) and exposes ready:false', async () => {
     brain.index.isReady = () => false // count present, serving structure NOT loaded
     const status = await brain.getIndexStatus()

tests/unit/graph/graph-fastpath-honest-readiness.test.ts

@@ -8,7 +8,7 @@
  * scan; and a one-shot probe self-heals a no-isReady provider whose adjacency
  * did not cold-load.
  */
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { Brainy, NounType, VerbType } from '../../../src/index.js'
 
 describe('graph fast-path honest readiness (Finding 2)', () => {
@@ -33,6 +33,10 @@ describe('graph fast-path honest readiness (Finding 2)', () => {
     await storage.getVerbsBySource(a)
   })
 
+  afterEach(async () => {
+    await brain.close()
+  })
+
   it('not-ready provider → shard scan returns the REAL edges, not a silent []', async () => {
     const gi = storage.graphIndex
     // Simulate a cold native provider: count/manifest loaded (isInitialized) but

tests/unit/metadata-cold-read-guard.test.ts

@@ -15,7 +15,7 @@
  * The 8.0 JS index cold-loads correctly, so we simulate the cold native failure
  * mode by intercepting the provider's getIdsForFilter/rebuild.
  */
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { Brainy, NounType, MetadataIndexNotReadyError } from '../../src/index.js'
 
 const V = () => Array.from({ length: 384 }, (_, i) => Math.sin(i * 0.1) + 0.001)
@@ -31,6 +31,10 @@ describe('Metadata cold-read guard (#venue silent-[])', () => {
     await brain.flush()
   })
 
+  afterEach(async () => {
+    await brain.close()
+  })
+
   it('warm brain: filtered find is correct and the guard does not rebuild', async () => {
     const mi = brain.metadataIndex
     let rebuilds = 0

tests/unit/migration-lock.test.ts

@@ -18,7 +18,7 @@
  * the production feature-detection reads it.
  */
 
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { Brainy, NounType, MigrationInProgressError } from '../../src/index.js'
 import { GraphAdjacencyIndex } from '../../src/graph/graphAdjacencyIndex.js'
 
@@ -39,6 +39,12 @@ describe('Migration LOCK (#18) — coordinated 7.x→8.0 auto-upgrade', () => {
     await brain.init()
   })
 
+  afterEach(async () => {
+    // The "close() is not gated" test already closes `brain` itself as its
+    // own assertion — closing an already-closed brain is a safe no-op here.
+    await brain.close().catch(() => {})
+  })
+
   it('does not gate operations when no provider is migrating (fast path)', async () => {
     const id = await brain.add({ data: 'hello', type: NounType.Concept })
     expect(id).toBeTruthy()
@@ -130,6 +136,9 @@ describe('Migration LOCK (#18) — coordinated 7.x→8.0 auto-upgrade', () => {
       expect(e).toBeInstanceOf(MigrationInProgressError)
       expect(e.retryable).toBe(true)
       expect(typeof e.elapsedMs).toBe('number')
+    } finally {
+      // close() is proven not-gated by the test below — safe even mid-migration.
+      await shortBrain.close()
     }
   })
 

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

@@ -13,10 +13,11 @@ describe('EmbeddingSignal', () => {
     signal = new EmbeddingSignal(brain)
   })
 
-  afterEach(() => {
+  afterEach(async () => {
     signal.clearCache()
     signal.clearHistory()
     signal.resetStats()
+    await brain.close()
   })
 
   describe('initialization', () => {

tests/unit/plugin-autodetect.test.ts

@@ -89,12 +89,14 @@ describe('Guarded plugin auto-detection (plugins: undefined)', () => {
     })
     const brain: any = new Brainy({ requireSubtype: false, storage: { type: 'memory' }, silent: true })
     await expect(brain.init()).rejects.toThrow(/installed but failed to load/)
+    await brain.close().catch(() => {})
   })
 
   it('installed but not a valid plugin (missing activate) → init() throws', async () => {
     stubImport(async () => ({ default: { name: '@soulcraft/cor' } })) // no activate()
     const brain: any = new Brainy({ requireSubtype: false, storage: { type: 'memory' }, silent: true })
     await expect(brain.init()).rejects.toThrow(/not a valid Brainy plugin/)
+    await brain.close().catch(() => {})
   })
 
   it('installed but activation fails → init() throws (activateAll posture applies)', async () => {
@@ -108,6 +110,7 @@ describe('Guarded plugin auto-detection (plugins: undefined)', () => {
     }))
     const brain: any = new Brainy({ requireSubtype: false, storage: { type: 'memory' }, silent: true })
     await expect(brain.init()).rejects.toThrow(/failed to activate/)
+    await brain.close().catch(() => {})
   })
 
   it('plugins: [] and plugins: false → no probe at all (explicit opt-out)', async () => {
@@ -132,5 +135,6 @@ describe('Guarded plugin auto-detection (plugins: undefined)', () => {
       silent: true
     })
     await expect(brain.init()).rejects.toThrow(/listed in config\.plugins but could not be loaded/)
+    await brain.close().catch(() => {})
   })
 })

tests/unit/plugin-version-coupling.test.ts

@@ -143,5 +143,6 @@ describe('version coupling at init() — no silent fallback', () => {
       plugins: ['@soulcraft/this-package-does-not-exist-xyz']
     })
     await expect(brain.init()).rejects.toThrow(/could not be loaded|config\.plugins/)
+    await brain.close().catch(() => {})
   })
 })

tests/unit/plugin.test.ts

@@ -298,9 +298,10 @@ describe('Brainy plugin integration', () => {
     // 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/)
+    await brain.close().catch(() => {})
   })
 
-  it('should use() return this for chaining', () => {
+  it('should use() return this for chaining', async () => {
     const plugin: BrainyPlugin = {
       name: 'chain-test',
       activate: async () => true
@@ -309,5 +310,8 @@ describe('Brainy plugin integration', () => {
     const brain = new Brainy({ requireSubtype: false, storage: { type: 'memory' } })
     const result = brain.use(plugin)
     expect(result).toBe(brain)
+    // Never init()'d — the constructor still registered it in Brainy's global
+    // instance registry, so it still needs a close() to deregister.
+    await brain.close().catch(() => {})
   })
 })

tests/unit/storage/pagination-parallel-hydration.test.ts

@@ -7,7 +7,7 @@
  * hydration (zero per-entity reads when unfiltered). Both must preserve the exact
  * pagination contract: same order, cursor continuation, filters, totalCount.
  */
-import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
 import { Brainy, NounType } from '../../../src/index.js'
 
 describe('paginated enumeration — parallel hydration + id-only (cortex heal-cost)', () => {
@@ -30,6 +30,10 @@ describe('paginated enumeration — parallel hydration + id-only (cortex heal-co
     storage = brain.storage
   })
 
+  afterEach(async () => {
+    await brain.close()
+  })
+
   /** Page the whole dataset through a small limit via cursor and collect ordered ids. */
   const pageAll = async (fn: (opts: any) => Promise<any>, key: 'items' | 'ids') => {
     const out: string[] = []

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

@@ -4,7 +4,7 @@
  * Tests to verify that brain.find({ type: NounType.X }) correctly filters entities
  */
 
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { Brainy, NounType } from '../../src/index.js'
 
 describe('Type Filtering (A Consumer Team Issue)', () => {
@@ -17,6 +17,10 @@ describe('Type Filtering (A Consumer Team Issue)', () => {
     await brain.init()
   })
 
+  afterEach(async () => {
+    await brain.close()
+  })
+
   it('should filter entities by NounType.Person', async () => {
     // Add 3 people
     await brain.add({ data: 'John Smith', type: NounType.Person, metadata: { name: 'John' } })

tests/unit/utils/metadataIndex-array-bound.test.ts

@@ -48,6 +48,10 @@ describe('the indexable-array bound', () => {
     await brain.init()
   })
 
+  afterEach(async () => {
+    await brain.close()
+  })
+
   describe('BELOW the bound: the array indexes, every element of it', () => {
     it('the eleven-element array that used to vanish is searchable', async () => {
       // ELEVEN — one over the old silent limit, the whole shape of the defect.

tests/unit/utils/metadataIndex-sparse-range-collation.test.ts

@@ -42,7 +42,7 @@
  * column store adopts the field. It is named in `getIdsFromChunksForRange`'s
  * doc comment rather than papered over.
  */
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { Brainy } from '../../../src/brainy'
 import { NounType } from '../../../src/types/graphTypes'
 import { SparseIndex, ChunkManager } from '../../../src/utils/metadataIndexChunking'
@@ -122,6 +122,10 @@ describe('legacy sparse index: range queries order values, or refuse', () => {
     expect(index.columnStore.hasField(FIELD)).toBe(false)
   })
 
+  afterEach(async () => {
+    await brain.close()
+  })
+
   describe('(a) a long BOUND against ordinary short values', () => {
     // 'apple' < 'mango' < 'zebra', and every bound below is compared against
     // these three raw keys.

tests/unit/validate-invariants-delegation.test.ts

@@ -6,7 +6,7 @@
  * validateInvariants(), and repairIndex() maps a failing invariant with heal:'rebuild'
  * to that provider's rebuild(). "healthy-while-broken must be impossible."
  */
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { Brainy, NounType } from '../../src/index.js'
 import type { ProviderInvariantReport } from '../../src/index.js'
 
@@ -48,6 +48,10 @@ describe('validateIndexConsistency delegates to provider validateInvariants() (P
     await brain.flush()
   })
 
+  afterEach(async () => {
+    await brain.close()
+  })
+
   it('a broken provider report makes the store unhealthy and names the failing invariant', async () => {
     brain.index.validateInvariants = async () => brokenReport('vector')
     const v = await brain.validateIndexConsistency()

tests/unit/vector-cold-read-guard.test.ts

@@ -12,7 +12,7 @@
  * signal (from either strategy) THROWS VectorIndexNotReadyError immediately,
  * with no rebuild attempt in between — never a silent empty result.
  */
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { Brainy, NounType, VectorIndexNotReadyError } from '../../src/index.js'
 
 const V = (): number[] => Array.from({ length: 384 }, (_, i) => Math.sin(i * 0.1) + 0.001)
@@ -28,6 +28,10 @@ describe('Vector cold-read guard (verifyVectorLive) — silent-[] on cold semant
     await brain.flush()
   })
 
+  afterEach(async () => {
+    await brain.close()
+  })
+
   it('warm brain: semantic find is correct and the guard does not rebuild', async () => {
     const vi = brain.index
     let rebuilds = 0

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

@@ -4,7 +4,7 @@
  * Tests to verify VFS import behavior and identify if VFS creates only wrappers or also graph entities
  */
 
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { Brainy, NounType } from '../../src/index.js'
 
 describe('VFS Multi-instance Diagnostic', () => {
@@ -17,6 +17,10 @@ describe('VFS Multi-instance Diagnostic', () => {
     await brain.init()
   })
 
+  afterEach(async () => {
+    await brain.close()
+  })
+
   it('should verify VFS creates document wrappers AND allows entity filtering', async () => {
     console.log('\n🔬 VFS Multi-instance Diagnostic Test\n')
     console.log('='.repeat(70))

tests/vfs/tree-operations.unit.test.ts

@@ -3,7 +3,7 @@
  * Ensures tree methods prevent recursion and work correctly
  */
 
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { Brainy } from '../../src/brainy.js'
 import { VirtualFileSystem } from '../../src/vfs/VirtualFileSystem.js'
 import { VFSTreeUtils } from '../../src/vfs/TreeUtils.js'
@@ -24,6 +24,10 @@ describe('VFS Tree Operations', () => {
     await vfs.init()
   })
 
+  afterEach(async () => {
+    await brain.close()
+  })
+
   describe('Critical: No Self-Inclusion Bug', () => {
     it('should NEVER return a directory as its own child', async () => {
       // Create test structure

tests/vfs/vfs-bug-fixes.unit.test.ts

@@ -6,7 +6,7 @@
  * - Issue #2: File read decompression error
  */
 
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { Brainy } from '../../src/brainy.js'
 import { VirtualFileSystem } from '../../src/vfs/VirtualFileSystem.js'
 
@@ -25,6 +25,10 @@ describe('VFS Bug Fixes', () => {
     await vfs.init()
   })
 
+  afterEach(async () => {
+    await brain.close()
+  })
+
   describe('Issue #1: Duplicate Directory Nodes', () => {
     it('should not create duplicate directory entries when writing multiple files to same directory', async () => {
       // Write multiple files to the same directory (reproduce the bug scenario)

tests/vfs/vfs-bulkwrite-race.unit.test.ts

@@ -12,7 +12,7 @@
  * other operations in parallel batches.
  */
 
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { Brainy } from '../../src/brainy.js'
 import { VirtualFileSystem } from '../../src/vfs/VirtualFileSystem.js'
 
@@ -30,6 +30,10 @@ describe('VFS bulkWrite Race Condition Fix', () => {
     await vfs.init()
   })
 
+  afterEach(async () => {
+    await brain.close()
+  })
+
   describe('operation ordering', () => {
     it('should create directories before files when mixed in same batch', async () => {
       // This is the exact scenario that triggered the race condition: