fix: complete VFS root directory and Contains relationship fixes
- Fix root directory metadata to always have vfsType: 'directory' - Add compatibility layer for malformed entity metadata - Ensure Contains relationships are maintained for all file operations - Fix resolvePath() special case for root directory - Add comprehensive documentation for VFS troubleshooting - Document proper usage of standard NounType and VerbType enums Resolves critical VFS bugs reported by brain-cloud team
This commit is contained in:
parent
40715226fa
commit
0e972525b6
4 changed files with 532 additions and 4 deletions
257
docs/vfs/TROUBLESHOOTING.md
Normal file
257
docs/vfs/TROUBLESHOOTING.md
Normal file
|
|
@ -0,0 +1,257 @@
|
|||
# VFS Troubleshooting Guide
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### Issue: "VFSError: Not a directory: /"
|
||||
|
||||
**Symptoms:**
|
||||
- `readdir('/')` throws "Not a directory" error
|
||||
- Root directory exists but isn't recognized as directory
|
||||
- Files can be written but not listed
|
||||
|
||||
**Root Cause:**
|
||||
The root directory entity exists but doesn't have the proper metadata structure.
|
||||
|
||||
**Solution (v3.15.0+):**
|
||||
This issue has been fixed in v3.15.0. The VFS now:
|
||||
1. Ensures root directory has `vfsType: 'directory'` metadata
|
||||
2. Adds compatibility layer for entities with malformed metadata
|
||||
3. Automatically repairs metadata on entity retrieval
|
||||
|
||||
**Manual Fix (if needed):**
|
||||
```javascript
|
||||
// Force re-initialization of root directory
|
||||
await vfs.init() // Will repair root if needed
|
||||
|
||||
// Or manually update root entity
|
||||
const rootId = vfs.rootEntityId
|
||||
await brain.update({
|
||||
id: rootId,
|
||||
metadata: {
|
||||
path: '/',
|
||||
vfsType: 'directory',
|
||||
// ... other metadata
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue: "readdir() returns empty array despite files existing"
|
||||
|
||||
**Symptoms:**
|
||||
- Files are successfully written to VFS
|
||||
- Files can be read individually
|
||||
- `readdir()` returns `[]` for directories with files
|
||||
|
||||
**Root Cause:**
|
||||
Contains relationships are missing between parent directories and files.
|
||||
|
||||
**Solution (v3.15.0+):**
|
||||
This issue has been fixed. The VFS now:
|
||||
1. Creates Contains relationships when writing new files
|
||||
2. Ensures Contains relationships exist when updating files
|
||||
3. Repairs missing relationships automatically
|
||||
|
||||
**Manual Fix (if needed):**
|
||||
```javascript
|
||||
// Repair missing Contains relationship
|
||||
const parentId = await vfs.resolvePath('/directory')
|
||||
const fileId = await vfs.resolvePath('/directory/file.txt')
|
||||
|
||||
await brain.relate({
|
||||
from: parentId,
|
||||
to: fileId,
|
||||
type: VerbType.Contains
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue: "VFS not initialized" error
|
||||
|
||||
**Symptoms:**
|
||||
- Any VFS operation throws "VFS not initialized"
|
||||
- Operations fail even after creating VFS instance
|
||||
|
||||
**Root Cause:**
|
||||
The VFS `init()` method wasn't called after getting the VFS instance.
|
||||
|
||||
**Solution:**
|
||||
```javascript
|
||||
// ✅ CORRECT
|
||||
const vfs = brain.vfs() // Get instance
|
||||
await vfs.init() // Initialize (REQUIRED!)
|
||||
|
||||
// ❌ WRONG
|
||||
const vfs = brain.vfs()
|
||||
// Missing: await vfs.init()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue: Files disappear after process restart
|
||||
|
||||
**Symptoms:**
|
||||
- Files exist during session
|
||||
- All files gone after restart
|
||||
- Fresh VFS each time
|
||||
|
||||
**Root Cause:**
|
||||
Using in-memory storage instead of persistent storage.
|
||||
|
||||
**Solution:**
|
||||
```javascript
|
||||
// ✅ Use persistent storage
|
||||
const brain = new Brainy({
|
||||
storage: {
|
||||
type: 'filesystem', // Persistent
|
||||
path: './brainy-data'
|
||||
}
|
||||
})
|
||||
|
||||
// ❌ Don't use memory for production
|
||||
const brain = new Brainy({
|
||||
storage: { type: 'memory' } // Data lost on restart!
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue: Infinite recursion when listing directories
|
||||
|
||||
**Symptoms:**
|
||||
- Directory appears as its own child
|
||||
- Stack overflow errors
|
||||
- UI freezes
|
||||
|
||||
**Root Cause:**
|
||||
Using path-based filtering instead of graph relationships.
|
||||
|
||||
**Solution:**
|
||||
```javascript
|
||||
// ✅ CORRECT - Use graph relationships
|
||||
const children = await vfs.getDirectChildren('/directory')
|
||||
|
||||
// ❌ WRONG - Path prefix matching causes recursion
|
||||
const allNodes = await brain.find({})
|
||||
const children = allNodes.filter(n =>
|
||||
n.metadata.path.startsWith('/directory/')) // Directory matches itself!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue: Can't find files by content
|
||||
|
||||
**Symptoms:**
|
||||
- Semantic search returns no results
|
||||
- Only exact filename matches work
|
||||
|
||||
**Root Cause:**
|
||||
Files aren't being properly embedded or indexed.
|
||||
|
||||
**Solution:**
|
||||
```javascript
|
||||
// Ensure files have content for embedding
|
||||
await vfs.writeFile('/doc.txt', 'Actual content here') // Not empty!
|
||||
|
||||
// Use semantic search correctly
|
||||
const results = await vfs.search('machine learning', {
|
||||
path: '/documents', // Search within path
|
||||
limit: 10,
|
||||
type: 'file'
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Debugging Tips
|
||||
|
||||
### 1. Check VFS Initialization
|
||||
```javascript
|
||||
console.log('VFS initialized:', vfs.initialized)
|
||||
console.log('Root entity ID:', vfs.rootEntityId)
|
||||
```
|
||||
|
||||
### 2. Verify Entity Metadata
|
||||
```javascript
|
||||
const entity = await vfs.getEntity('/path/to/file')
|
||||
console.log('Entity metadata:', entity.metadata)
|
||||
console.log('VFS type:', entity.metadata.vfsType)
|
||||
```
|
||||
|
||||
### 3. Check Relationships
|
||||
```javascript
|
||||
const parentId = await vfs.resolvePath('/directory')
|
||||
const relations = await brain.getRelations({
|
||||
from: parentId,
|
||||
type: VerbType.Contains
|
||||
})
|
||||
console.log('Child count:', relations.length)
|
||||
```
|
||||
|
||||
### 4. Enable Debug Logging
|
||||
```javascript
|
||||
const brain = new Brainy({
|
||||
storage: { type: 'filesystem' },
|
||||
logger: {
|
||||
level: 'debug',
|
||||
enabled: true
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Performance Tips
|
||||
|
||||
### 1. Use Caching
|
||||
```javascript
|
||||
// Enable caching in VFS config
|
||||
const vfs = brain.vfs({
|
||||
cache: {
|
||||
enabled: true,
|
||||
ttl: 300000, // 5 minutes
|
||||
maxSize: 1000
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### 2. Batch Operations
|
||||
```javascript
|
||||
// Write multiple files efficiently
|
||||
const files = [
|
||||
{ path: '/file1.txt', content: 'content1' },
|
||||
{ path: '/file2.txt', content: 'content2' }
|
||||
]
|
||||
|
||||
await Promise.all(
|
||||
files.map(f => vfs.writeFile(f.path, f.content))
|
||||
)
|
||||
```
|
||||
|
||||
### 3. Limit Directory Depth
|
||||
```javascript
|
||||
// Don't traverse too deep
|
||||
const tree = await vfs.getTreeStructure('/', {
|
||||
maxDepth: 3, // Limit recursion
|
||||
includeHidden: false
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you encounter issues not covered here:
|
||||
|
||||
1. Check the [VFS API Guide](./VFS_API_GUIDE.md)
|
||||
2. Review [VFS Examples](./VFS_EXAMPLES_SCENARIOS.md)
|
||||
3. Look at [test files](../../tests/vfs/) for working examples
|
||||
4. Report issues at [GitHub Issues](https://github.com/soulcraftlabs/brainy/issues)
|
||||
|
||||
Remember: Most VFS issues are related to:
|
||||
- Missing initialization (`await vfs.init()`)
|
||||
- Using memory storage instead of filesystem
|
||||
- Missing Contains relationships
|
||||
- Incorrect path handling
|
||||
199
docs/vfs/VFS_GRAPH_TYPES.md
Normal file
199
docs/vfs/VFS_GRAPH_TYPES.md
Normal file
|
|
@ -0,0 +1,199 @@
|
|||
# VFS Graph Type Usage Guide
|
||||
|
||||
## Standard Type System
|
||||
|
||||
The Brainy VFS uses Brainy's standard graph type system for all entities and relationships. This ensures compatibility with the broader Brainy ecosystem and enables powerful cross-domain queries.
|
||||
|
||||
## Entity Types (NounType)
|
||||
|
||||
### Directory Entities
|
||||
- **Type:** `NounType.Collection`
|
||||
- **Purpose:** Represents directories/folders that contain other entities
|
||||
- **Metadata:** Includes `vfsType: 'directory'` for VFS-specific operations
|
||||
|
||||
```javascript
|
||||
// Directories are created as Collections
|
||||
await brain.add({
|
||||
type: NounType.Collection,
|
||||
metadata: {
|
||||
path: '/documents',
|
||||
vfsType: 'directory',
|
||||
// ... other metadata
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### File Entities
|
||||
|
||||
The VFS intelligently selects the appropriate NounType based on file content:
|
||||
|
||||
- **`NounType.Document`** - Text files, JSON, source code, markdown
|
||||
- **`NounType.Media`** - Images, videos, audio files
|
||||
- **`NounType.File`** - Generic/binary files
|
||||
|
||||
```javascript
|
||||
// Automatic type selection based on MIME type
|
||||
function getFileNounType(mimeType) {
|
||||
if (mimeType.startsWith('text/') || mimeType.includes('json')) {
|
||||
return NounType.Document
|
||||
}
|
||||
if (mimeType.startsWith('image/') ||
|
||||
mimeType.startsWith('video/') ||
|
||||
mimeType.startsWith('audio/')) {
|
||||
return NounType.Media
|
||||
}
|
||||
return NounType.File
|
||||
}
|
||||
```
|
||||
|
||||
## Relationship Types (VerbType)
|
||||
|
||||
### Core VFS Relationships
|
||||
|
||||
#### Parent-Child Structure
|
||||
- **Type:** `VerbType.Contains`
|
||||
- **Direction:** Parent → Child
|
||||
- **Purpose:** Represents the hierarchical file system structure
|
||||
|
||||
```javascript
|
||||
// Creating directory structure
|
||||
await brain.relate({
|
||||
from: parentDirectoryId,
|
||||
to: childFileOrDirectoryId,
|
||||
type: VerbType.Contains
|
||||
})
|
||||
```
|
||||
|
||||
#### Custom File Relationships
|
||||
|
||||
You can add custom relationships between files using any VerbType:
|
||||
|
||||
```javascript
|
||||
// Document references another
|
||||
await vfs.addRelationship('/doc1.md', '/doc2.md', VerbType.References)
|
||||
|
||||
// Code file depends on library
|
||||
await vfs.addRelationship('/app.js', '/lib/utils.js', VerbType.DependsOn)
|
||||
|
||||
// Image derived from original
|
||||
await vfs.addRelationship('/edited.jpg', '/original.jpg', VerbType.DerivedFrom)
|
||||
```
|
||||
|
||||
## VFS-Specific Metadata
|
||||
|
||||
While using standard graph types, VFS adds domain-specific metadata for efficient file operations:
|
||||
|
||||
```javascript
|
||||
{
|
||||
// Standard Brainy fields
|
||||
type: NounType.Document, // Standard noun type
|
||||
|
||||
// VFS-specific metadata
|
||||
metadata: {
|
||||
path: '/documents/report.pdf',
|
||||
name: 'report.pdf',
|
||||
vfsType: 'file', // VFS-specific: 'file' or 'directory'
|
||||
size: 1024000,
|
||||
mimeType: 'application/pdf',
|
||||
permissions: 0o644,
|
||||
owner: 'user',
|
||||
group: 'users',
|
||||
accessed: Date.now(),
|
||||
modified: Date.now(),
|
||||
// ... custom metadata
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Benefits of Standard Types
|
||||
|
||||
### 1. Cross-Domain Queries
|
||||
```javascript
|
||||
// Find all documents (including VFS files) about "machine learning"
|
||||
const results = await brain.search('machine learning', {
|
||||
where: { type: NounType.Document }
|
||||
})
|
||||
```
|
||||
|
||||
### 2. Graph Traversal
|
||||
```javascript
|
||||
// Find all entities contained in a directory
|
||||
const contained = await brain.getRelations({
|
||||
from: directoryId,
|
||||
type: VerbType.Contains
|
||||
})
|
||||
|
||||
// Find what contains a file (parent directories)
|
||||
const parents = await brain.getRelations({
|
||||
to: fileId,
|
||||
type: VerbType.Contains
|
||||
})
|
||||
```
|
||||
|
||||
### 3. Semantic Understanding
|
||||
```javascript
|
||||
// Files are automatically embedded based on their content type
|
||||
// Documents get text embeddings
|
||||
// Media files get metadata embeddings
|
||||
// This enables semantic search across all file types
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### DO:
|
||||
✅ Use `NounType.Collection` for directories
|
||||
✅ Use appropriate file NounTypes based on content
|
||||
✅ Use `VerbType.Contains` for parent-child relationships
|
||||
✅ Add custom relationships with standard VerbTypes
|
||||
✅ Include `vfsType` metadata for VFS operations
|
||||
|
||||
### DON'T:
|
||||
❌ Use string literals for types (use enums)
|
||||
❌ Create custom noun/verb types for VFS
|
||||
❌ Mix graph relationships with metadata-only queries
|
||||
❌ Forget to create Contains relationships
|
||||
|
||||
## Example: Complete File Creation
|
||||
|
||||
```javascript
|
||||
// Creating a file with proper types
|
||||
const fileEntity = await brain.add({
|
||||
type: NounType.Document, // Standard noun type
|
||||
data: 'File content for embeddings',
|
||||
metadata: {
|
||||
path: '/docs/guide.md',
|
||||
vfsType: 'file', // VFS-specific metadata
|
||||
mimeType: 'text/markdown',
|
||||
size: Buffer.byteLength('File content for embeddings')
|
||||
}
|
||||
})
|
||||
|
||||
// Create Contains relationship with parent
|
||||
await brain.relate({
|
||||
from: parentDirectoryId,
|
||||
to: fileEntity.id,
|
||||
type: VerbType.Contains // Standard verb type
|
||||
})
|
||||
```
|
||||
|
||||
## Migration from Legacy Code
|
||||
|
||||
If you have legacy code using strings for types:
|
||||
|
||||
```javascript
|
||||
// ❌ OLD (strings)
|
||||
await brain.relate({
|
||||
type: 'contains' // Wrong!
|
||||
})
|
||||
|
||||
// ✅ NEW (enums)
|
||||
await brain.relate({
|
||||
type: VerbType.Contains // Correct!
|
||||
})
|
||||
```
|
||||
|
||||
Always import and use the type enums:
|
||||
|
||||
```javascript
|
||||
import { NounType, VerbType } from '@soulcraft/brainy'
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue