refactor(8.0): API-surface + quality polish from the readiness audit

- find() search-mode: collapsed the two overlapping options to one canonical
  `searchMode: SearchMode` (the redundant `mode` alias was silently ignored on
  the primary find() path while honored on the historical path — a footgun) and
  removed the unwired `explain?` FindParams field (never read by find()).
- Documentation accuracy on the public type surface: entity ids documented as
  UUID v7 (auto) / v5 (natural key), not v4; dropped the stale "Brainy 3.0"
  banners and "backward compatibility" hedging on the fresh-8.0 Result type;
  documented the via/type alias; removed the dead GraphConstraints.bidirectional;
  fixed the no-op `EmbeddedGraphVerb = Omit<GraphVerb,'source'>` to omit the real
  sourceId; corrected the GraphIndexProvider.isInitialized JSDoc; documented
  removeMany's per-chunk generation granularity; JSDoc'd the public VFS surface.
- Honest perf comments in source: removed unmeasured billion-scale figures from
  the LSMTree / graphAdjacencyIndex headers (the JS fallback is in-memory after
  open; native is the scale path).
- Robustness: getVerbMetadata propagates read errors symmetrically with
  getNounMetadata; the find() egress integrity-guard keeps a row when the JS
  matcher doesn't implement an operator the provider already matched on; hardened
  the boundary-no-native CI guard to catch side-effect imports + re-exports.
- Tests: de-theatricalized a relateMany test to assert the real contract; fixed
  a stale Model-B header.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

tests/unit/boundary-no-native.test.ts

@@ -46,9 +46,31 @@ function sourceFiles(dir: string): string[] {
 // `@soulcraft/cortex` both match; `@soulcraft/core` (a different name) does not,
 // because the package must be followed by a subpath separator or the closing quote.
 const NATIVE_MODULE =
-  /(?:import\s[^'"]*from\s*|import\s*\(\s*|require\s*\(\s*)['"]@soulcraft\/cor(?:tex)?(?:\/[^'"]*)?['"]/
+  /(?:import\s[^'"]*from\s*|export\s[^'"]*from\s*|import\s*\(\s*|require\s*\(\s*|import\s*)['"]@soulcraft\/cor(?:tex)?(?:\/[^'"]*)?['"]/
 
 describe('open/proprietary boundary — public repo must not depend on @soulcraft/cor', () => {
+  it('the detector catches every static-dependency form (incl. side-effect imports + re-exports)', () => {
+    // Each of these creates a hard dependency on the proprietary package and MUST
+    // be caught (the prior regex missed the bare side-effect import and re-export forms).
+    for (const form of [
+      `import cor from '@soulcraft/cor'`,
+      `import { x } from '@soulcraft/cor'`,
+      `import '@soulcraft/cor'`,
+      `import '@soulcraft/cor/native'`,
+      `export { x } from '@soulcraft/cor'`,
+      `export * from '@soulcraft/cor'`,
+      `const x = require('@soulcraft/cor')`,
+      `const x = await import('@soulcraft/cor')`,
+      `import x from '@soulcraft/cortex'`
+    ]) {
+      expect(NATIVE_MODULE.test(form), `should detect: ${form}`).toBe(true)
+    }
+    // A different package whose name merely starts with the same prefix is NOT a match.
+    for (const ok of [`import x from '@soulcraft/core'`, `// see @soulcraft/cor docs`]) {
+      expect(NATIVE_MODULE.test(ok), `should NOT match: ${ok}`).toBe(false)
+    }
+  })
+
   it('no src/ or tests/ file imports or requires the native package', () => {
     const offenders: string[] = []
     for (const dir of ['src', 'tests']) {

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

@@ -405,21 +405,24 @@ describe('Brainy Batch Operations', () => {
       expect(companyRelations.length).toBeGreaterThanOrEqual(50)
     })
     
-    it('should skip invalid relationships', async () => {
+    it('a batch with a forward-reference endpoint still creates the fully-valid relationships', async () => {
+      // The middle item references a source id that does not (yet) exist — a
+      // forward reference. Whatever its fate, the two fully-valid edges MUST be
+      // created (a bad item must not sink the good ones in a batch).
       const relationships = [
         { from: entities[0], to: entities[1], type: VerbType.FriendOf },
-        { from: 'invalid-id', to: entities[2], type: VerbType.FriendOf },
+        { from: 'no-such-entity', to: entities[2], type: VerbType.FriendOf },
         { from: entities[1], to: entities[2], type: VerbType.FriendOf }
       ]
-      
-      try {
-        // Should skip invalid and continue
-        const relationIds = await brain.relateMany({ items: relationships })
-        expect(relationIds.length).toBeLessThanOrEqual(3)
-      } catch (error) {
-        // Or might throw - that's ok too
-        expect(error).toBeDefined()
-      }
+
+      const relationIds = await brain.relateMany({ items: relationships })
+      expect(Array.isArray(relationIds)).toBe(true)
+
+      // Both fully-valid edges are queryable, regardless of the forward-ref item.
+      const from0 = await brain.related({ from: entities[0] })
+      expect(from0.some((r) => r.to === entities[1])).toBe(true)
+      const from1 = await brain.related({ from: entities[1] })
+      expect(from1.some((r) => r.to === entities[2])).toBe(true)
     })
   })