fix(vfs): prevent race condition in bulkWrite by ordering operations

- Process mkdir operations sequentially first (sorted by path depth)
- Then process write/delete/update operations in parallel batches
- Prevents duplicate directory entities when mkdir and write for
  related paths are in the same batch
- Add comprehensive tests for bulkWrite race condition scenarios
- Update API documentation for accuracy

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

docs/README.md

@@ -1,4 +1,4 @@
-# Brainy Documentation (v4.0.0)
+# Brainy Documentation (v6.5.0)
 
 Welcome to the comprehensive documentation for Brainy, the multi-dimensional AI database with Triple Intelligence Engine.
 
@@ -77,28 +77,31 @@ await brain.find("recent articles about AI with high ratings")
 ## Quick Example
 
 ```typescript
-import { Brainy } from 'brainy'
+import { Brainy, NounType, VerbType } from '@soulcraft/brainy'
 
 // Initialize
 const brain = new Brainy()
 await brain.init()
 
 // Add entities (nouns)
-const articleId = await brain.add("Revolutionary AI Breakthrough", {
-  type: "article",
-  category: "technology",
-  rating: 4.8
+const articleId = await brain.add({
+  data: "Revolutionary AI Breakthrough",
+  type: NounType.Document,
+  metadata: { category: "technology", rating: 4.8 }
 })
 
-const authorId = await brain.add("Dr. Sarah Chen", {
-  type: "person",
-  role: "researcher"
+const authorId = await brain.add({
+  data: "Dr. Sarah Chen",
+  type: NounType.Person,
+  metadata: { role: "researcher" }
 })
 
 // Create relationships (verbs)
-await brain.relate(authorId, articleId, "authored", {
-  date: "2024-01-15",
-  contribution: "primary"
+await brain.relate({
+  from: authorId,
+  to: articleId,
+  type: VerbType.CreatedBy,
+  metadata: { date: "2024-01-15", contribution: "primary" }
 })
 
 // Query naturally