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/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)
     })
   })