feat(vfs): add comprehensive VFS root debugging script
Add diagnostic tools to help Workshop team identify why vfs.readdir('/')
returns empty despite 608 Contains relationships existing:
- debug-vfs-root.js: Script that shows VFS root ID, all collections,
and outgoing Contains relationships from each directory
- VFS_DEBUG_INSTRUCTIONS.md: Step-by-step instructions for running
the debug script and interpreting results
This will help identify if the bug is:
1. VFS using wrong root entity ID
2. Duplicate root entities (VFS using empty root, files under different root)
3. Root entity doesn't exist in database
4. Contains relationships exist but aren't FROM the root
5. v4.7.1 optimization not being triggered
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
parent
ff01782410
commit
5a245f95f8
2 changed files with 312 additions and 0 deletions
188
VFS_DEBUG_INSTRUCTIONS.md
Normal file
188
VFS_DEBUG_INSTRUCTIONS.md
Normal file
|
|
@ -0,0 +1,188 @@
|
|||
# 🔍 VFS Root Debugging Instructions
|
||||
|
||||
## Problem Summary
|
||||
|
||||
Despite 7 attempted fixes (v4.5.1 through v4.7.1), vfs.readdir('/') still returns empty even though:
|
||||
- ✅ 600 document entities exist
|
||||
- ✅ 608 Contains relationships exist
|
||||
- ✅ 9 collection entities (directories) exist
|
||||
|
||||
## Root Cause Hypothesis
|
||||
|
||||
The VFS instance is likely using a **different root entity ID** than the actual root directory where files were imported. This would explain why:
|
||||
- Import succeeds (creates files under the REAL root)
|
||||
- getRelations() succeeds (relationships exist in database)
|
||||
- But readdir('/') returns empty (VFS querying the WRONG root)
|
||||
|
||||
## Debug Script
|
||||
|
||||
I've created `debug-vfs-root.js` which will:
|
||||
1. Show the root entity ID that VFS is using
|
||||
2. List ALL collection entities (directories) in the database
|
||||
3. For each directory, count outgoing Contains relationships
|
||||
4. Identify which directory is the VFS root and whether it has children
|
||||
|
||||
## How to Run
|
||||
|
||||
```bash
|
||||
# Make sure you're using v4.7.1
|
||||
$ cd /path/to/brainy/project
|
||||
|
||||
# Copy the debug script to your Brainy installation
|
||||
$ cp /media/dpsifr/storage/home/Projects/brainy/debug-vfs-root.js .
|
||||
|
||||
# Run it with your FileSystemStorage database
|
||||
$ node debug-vfs-root.js
|
||||
```
|
||||
|
||||
## Expected Output
|
||||
|
||||
The script will show:
|
||||
```
|
||||
🔍 VFS Root Debugging Script
|
||||
============================================================
|
||||
✅ Brainy initialized
|
||||
|
||||
✅ VFS instance created
|
||||
|
||||
📍 VFS Root Entity ID: abc123-xyz...
|
||||
|
||||
✅ Root entity EXISTS in database:
|
||||
Type: collection
|
||||
Path: /
|
||||
VFS Type: directory
|
||||
Created: 2025-10-27T16:45:00.000Z
|
||||
|
||||
🔍 Finding ALL collection entities (directories)...
|
||||
Found 9 collection entities:
|
||||
|
||||
👑 ID: abc123-xyz...
|
||||
Path: /
|
||||
VFS Type: directory
|
||||
Created: 2025-10-27T16:45:00.000Z
|
||||
✅ THIS IS THE VFS ROOT
|
||||
|
||||
ID: def456-uvw...
|
||||
Path: /Characters
|
||||
VFS Type: directory
|
||||
Created: 2025-10-27T16:46:00.000Z
|
||||
|
||||
[... 7 more directories ...]
|
||||
|
||||
🔍 Checking Contains relationships FROM each collection...
|
||||
|
||||
Collection abc123-xyz...:
|
||||
Path: /
|
||||
Outgoing Contains: 8
|
||||
✅ THIS IS THE VFS ROOT - should return 8 items for readdir('/')
|
||||
|
||||
Collection def456-uvw...:
|
||||
Path: /Characters
|
||||
Outgoing Contains: 127
|
||||
|
||||
[... more directories ...]
|
||||
|
||||
🔍 Counting ALL Contains relationships in database...
|
||||
Total Contains relationships: 608
|
||||
|
||||
📋 Sample Contains relationships (first 10):
|
||||
1. abc123-xyz... -> def456-uvw...
|
||||
From: / (directory)
|
||||
To: /Characters (directory)
|
||||
|
||||
2. def456-uvw... -> ghi789-rst...
|
||||
From: /Characters (directory)
|
||||
To: /Characters/entity-001.json (file)
|
||||
|
||||
[... more samples ...]
|
||||
|
||||
============================================================
|
||||
🏁 Debug Complete
|
||||
```
|
||||
|
||||
## What to Look For
|
||||
|
||||
### ✅ Good Case (VFS Working)
|
||||
```
|
||||
📍 VFS Root Entity ID: abc123-xyz...
|
||||
✅ Root entity EXISTS in database
|
||||
Collection abc123-xyz...:
|
||||
Path: /
|
||||
Outgoing Contains: 8 👈 NON-ZERO!
|
||||
✅ THIS IS THE VFS ROOT
|
||||
```
|
||||
|
||||
### ❌ Bad Case #1: VFS Using Wrong Root
|
||||
```
|
||||
📍 VFS Root Entity ID: xxx000-yyy...
|
||||
✅ Root entity EXISTS in database
|
||||
Collection xxx000-yyy...:
|
||||
Path: /
|
||||
Outgoing Contains: 0 👈 ZERO! This is the bug!
|
||||
✅ THIS IS THE VFS ROOT
|
||||
|
||||
Collection abc123-zzz...:
|
||||
Path: /
|
||||
Outgoing Contains: 8 👈 Files are under THIS root instead!
|
||||
```
|
||||
|
||||
### ❌ Bad Case #2: VFS Root Doesn't Exist
|
||||
```
|
||||
📍 VFS Root Entity ID: xxx000-yyy...
|
||||
❌ Root entity DOES NOT EXIST in database!
|
||||
This is the bug! VFS is using a root ID that doesn't exist.
|
||||
```
|
||||
|
||||
### ❌ Bad Case #3: Root Has No Children
|
||||
```
|
||||
📍 VFS Root Entity ID: abc123-xyz...
|
||||
✅ Root entity EXISTS in database
|
||||
Collection abc123-xyz...:
|
||||
Path: /
|
||||
Outgoing Contains: 0 👈 ZERO! Files aren't under root!
|
||||
✅ THIS IS THE VFS ROOT
|
||||
|
||||
[All other collections have Contains relationships, but NOT from root]
|
||||
```
|
||||
|
||||
## What This Tells Us
|
||||
|
||||
Based on the output, we can determine:
|
||||
|
||||
1. **If "Outgoing Contains: 0" for VFS root**: The VFS is querying the correct root, but that root has no children. This means files were created under a DIFFERENT root or weren't properly linked.
|
||||
|
||||
2. **If multiple "/" paths exist**: There are duplicate root entities. VFS is using one root, but files are under a different root.
|
||||
|
||||
3. **If "Root entity DOES NOT EXIST"**: VFS is using a stale/wrong entity ID that was deleted or never existed.
|
||||
|
||||
4. **If "Outgoing Contains: 8"**: VFS root HAS children! This means my v4.7.1 fix has another bug - the optimization isn't being triggered or has a logic error.
|
||||
|
||||
## Next Steps
|
||||
|
||||
Please run this script and send me the full output. Based on what we see, I'll know exactly how to fix the real bug!
|
||||
|
||||
## Architecture Notes
|
||||
|
||||
The VFS query flow is:
|
||||
```
|
||||
vfs.readdir('/')
|
||||
-> PathResolver.resolve('/')
|
||||
-> returns this.rootEntityId
|
||||
-> PathResolver.getChildren(rootEntityId)
|
||||
-> brain.getRelations({ from: rootEntityId, type: VerbType.Contains })
|
||||
-> brainy.ts builds filter
|
||||
-> storage.getVerbs({ filter: { sourceId: rootEntityId, verbType } })
|
||||
-> MY v4.7.1 FIX: Check if sourceId + verbType filters exist
|
||||
-> If YES: Call getVerbsBySource_internal(rootEntityId)
|
||||
-> Get verbs from graph adjacency index
|
||||
-> Filter by verbType
|
||||
-> Return Contains relationships
|
||||
```
|
||||
|
||||
If the debug shows "Outgoing Contains: 0" for the VFS root, then either:
|
||||
- A. getVerbsBySource_internal() is broken
|
||||
- B. The graph adjacency index isn't being populated
|
||||
- C. My v4.7.1 optimization has a bug and isn't being called
|
||||
- D. The rootEntityId is wrong
|
||||
|
||||
This script will tell us which one!
|
||||
124
debug-vfs-root.js
Normal file
124
debug-vfs-root.js
Normal file
|
|
@ -0,0 +1,124 @@
|
|||
/**
|
||||
* VFS Root Debugging Script
|
||||
*
|
||||
* This script debugs why vfs.readdir('/') returns empty despite
|
||||
* 608 Contains relationships existing in the database.
|
||||
*/
|
||||
|
||||
import { Brainy } from './dist/brainy.js'
|
||||
import { VerbType, NounType } from './dist/types/graphTypes.js'
|
||||
|
||||
async function debugVFSRoot() {
|
||||
console.log('\n🔍 VFS Root Debugging Script\n')
|
||||
console.log('=' .repeat(60))
|
||||
|
||||
// Initialize Brainy with FileSystemStorage
|
||||
const brain = new Brainy({
|
||||
storage: {
|
||||
type: 'filesystem',
|
||||
config: {
|
||||
path: './brainy-data'
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
await brain.ready()
|
||||
console.log('✅ Brainy initialized\n')
|
||||
|
||||
// Get VFS instance
|
||||
const vfs = brain.vfs()
|
||||
console.log('✅ VFS instance created\n')
|
||||
|
||||
// Get the root entity ID that VFS is using
|
||||
const vfsRootId = (vfs as any).rootEntityId
|
||||
console.log(`📍 VFS Root Entity ID: ${vfsRootId}\n`)
|
||||
|
||||
// Try to get the root entity
|
||||
const rootEntity = await brain.get(vfsRootId)
|
||||
if (rootEntity) {
|
||||
console.log('✅ Root entity EXISTS in database:')
|
||||
console.log(` Type: ${rootEntity.type}`)
|
||||
console.log(` Path: ${rootEntity.metadata?.path}`)
|
||||
console.log(` VFS Type: ${rootEntity.metadata?.vfsType}`)
|
||||
console.log(` Created: ${new Date(rootEntity.createdAt || 0).toISOString()}`)
|
||||
console.log()
|
||||
} else {
|
||||
console.log('❌ Root entity DOES NOT EXIST in database!')
|
||||
console.log(' This is the bug! VFS is using a root ID that doesn\'t exist.\n')
|
||||
}
|
||||
|
||||
// Find ALL collection entities (directories)
|
||||
console.log('🔍 Finding ALL collection entities (directories)...')
|
||||
const allCollections = await brain.find({
|
||||
type: NounType.Collection,
|
||||
limit: 100
|
||||
})
|
||||
console.log(` Found ${allCollections.length} collection entities:\n`)
|
||||
|
||||
for (const coll of allCollections) {
|
||||
const isRoot = coll.metadata?.path === '/' && coll.metadata?.vfsType === 'directory'
|
||||
console.log(` ${isRoot ? '👑' : ' '} ID: ${coll.id}`)
|
||||
console.log(` Path: ${coll.metadata?.path}`)
|
||||
console.log(` VFS Type: ${coll.metadata?.vfsType}`)
|
||||
console.log(` Created: ${new Date(coll.entity?.createdAt || 0).toISOString()}`)
|
||||
|
||||
// Check if this matches VFS root
|
||||
if (coll.id === vfsRootId) {
|
||||
console.log(` ✅ THIS IS THE VFS ROOT`)
|
||||
}
|
||||
console.log()
|
||||
}
|
||||
|
||||
// For each potential root, count outgoing Contains relationships
|
||||
console.log('🔍 Checking Contains relationships FROM each collection...\n')
|
||||
|
||||
for (const coll of allCollections) {
|
||||
const relations = await brain.getRelations({
|
||||
from: coll.id,
|
||||
type: VerbType.Contains
|
||||
})
|
||||
|
||||
console.log(` Collection ${coll.id}:`)
|
||||
console.log(` Path: ${coll.metadata?.path}`)
|
||||
console.log(` Outgoing Contains: ${relations.length}`)
|
||||
|
||||
if (coll.id === vfsRootId) {
|
||||
console.log(` ✅ THIS IS THE VFS ROOT - should return ${relations.length} items for readdir('/')`)
|
||||
|
||||
if (relations.length === 0) {
|
||||
console.log(` ❌ BUT IT HAS ZERO CHILDREN! This is why readdir() returns empty!`)
|
||||
}
|
||||
}
|
||||
console.log()
|
||||
}
|
||||
|
||||
// Count total Contains relationships in database
|
||||
console.log('🔍 Counting ALL Contains relationships in database...')
|
||||
const allContains = await brain.getRelations({
|
||||
type: VerbType.Contains,
|
||||
limit: 1000
|
||||
})
|
||||
console.log(` Total Contains relationships: ${allContains.length}\n`)
|
||||
|
||||
// Sample some Contains relationships
|
||||
console.log('📋 Sample Contains relationships (first 10):')
|
||||
for (let i = 0; i < Math.min(10, allContains.length); i++) {
|
||||
const rel = allContains[i]
|
||||
const fromEntity = await brain.get(rel.from)
|
||||
const toEntity = await brain.get(rel.to)
|
||||
|
||||
console.log(` ${i + 1}. ${rel.from} -> ${rel.to}`)
|
||||
console.log(` From: ${fromEntity?.metadata?.path || 'unknown'} (${fromEntity?.metadata?.vfsType || 'unknown'})`)
|
||||
console.log(` To: ${toEntity?.metadata?.path || 'unknown'} (${toEntity?.metadata?.vfsType || 'unknown'})`)
|
||||
}
|
||||
|
||||
console.log('\n' + '='.repeat(60))
|
||||
console.log('🏁 Debug Complete\n')
|
||||
|
||||
process.exit(0)
|
||||
}
|
||||
|
||||
debugVFSRoot().catch(err => {
|
||||
console.error('❌ Error:', err)
|
||||
process.exit(1)
|
||||
})
|
||||
Loading…
Add table
Add a link
Reference in a new issue