From 4b980a46a8ff388d6ad2b5f1bb7952f6ee1412b1 Mon Sep 17 00:00:00 2001
From: David Snelling <david@soulcraft.com>
Date: Tue, 28 Oct 2025 13:57:59 -0700
Subject: [PATCH] debug: add comprehensive logging to trace VFS undefined names
 bug

- Add debug logging to VFS readdir() to show children and VFSDirent structure
- Add debug logging to PathResolver.getChildren() to trace entity retrieval
- Add debug logging to convertNounToEntity() to trace metadata extraction
- Helps diagnose v4.8.4 VFS undefined names bug reported by Workshop team

Ref: BRAINY_V4.8.4_VFS_UNDEFINED_NAMES_BUG.md
---
 src/brainy.ts                | 15 +++++++++++++++
 src/vfs/PathResolver.ts      | 13 +++++++++++++
 src/vfs/VirtualFileSystem.ts | 21 ++++++++++++++++++++-
 3 files changed, 48 insertions(+), 1 deletion(-)

diff --git a/src/brainy.ts b/src/brainy.ts
index f0a9512f..9dc4e25f 100644
--- a/src/brainy.ts
+++ b/src/brainy.ts
@@ -573,6 +573,14 @@ export class Brainy<T = any> implements BrainyInterface<T> {
     // v4.8.0: Storage adapters ALREADY extract standard fields to top-level!
     // Just read from top-level fields of HNSWNounWithMetadata
 
+    console.log(`[DEBUG convertNounToEntity] Converting noun ${noun.id}:`, {
+      nounMetadataKeys: noun.metadata ? Object.keys(noun.metadata) : [],
+      nounType: noun.type,
+      hasName: !!noun.metadata?.name,
+      hasPath: !!noun.metadata?.path,
+      hasVfsType: !!noun.metadata?.vfsType
+    })
+
     // v4.8.0: Clean structure with standard fields at top-level
     const entity: Entity<T> = {
       id: noun.id,
@@ -592,6 +600,13 @@ export class Brainy<T = any> implements BrainyInterface<T> {
       metadata: noun.metadata as T
     }
 
+    console.log(`[DEBUG convertNounToEntity] Converted entity metadata:`, {
+      entityMetadataKeys: entity.metadata ? Object.keys(entity.metadata as any) : [],
+      metadata_name: (entity.metadata as any)?.name,
+      metadata_path: (entity.metadata as any)?.path,
+      metadata_vfsType: (entity.metadata as any)?.vfsType
+    })
+
     return entity
   }
 
diff --git a/src/vfs/PathResolver.ts b/src/vfs/PathResolver.ts
index c683dbb2..5749610c 100644
--- a/src/vfs/PathResolver.ts
+++ b/src/vfs/PathResolver.ts
@@ -230,6 +230,7 @@ export class PathResolver {
       from: dirId,
       type: VerbType.Contains
     })
+    console.log(`[DEBUG PathResolver] getChildren(${dirId}): Found ${relations.length} Contains relations`)
 
     const validChildren: VFSEntity[]= []
     const childNames = new Set<string>()
@@ -237,12 +238,24 @@ export class PathResolver {
     // Fetch all child entities via relationships
     for (const relation of relations) {
       const entity = await this.brain.get(relation.to)
+      console.log(`[DEBUG PathResolver] Retrieved entity ${relation.to}:`, {
+        exists: !!entity,
+        type: entity?.type,
+        hasMetadata: !!entity?.metadata,
+        metadataKeys: entity?.metadata ? Object.keys(entity.metadata) : [],
+        metadata_vfsType: entity?.metadata?.vfsType,
+        metadata_name: entity?.metadata?.name
+      })
+
       if (entity && entity.metadata?.vfsType && entity.metadata?.name) {
         validChildren.push(entity as VFSEntity)
         childNames.add(entity.metadata.name)
+      } else {
+        console.log(`[DEBUG PathResolver] ❌ FILTERED OUT entity ${relation.to} - missing vfsType or name`)
       }
     }
 
+    console.log(`[DEBUG PathResolver] Returning ${validChildren.length} valid children (filtered from ${relations.length})`)
     // Update cache
     this.parentCache.set(dirId, childNames)
     return validChildren
diff --git a/src/vfs/VirtualFileSystem.ts b/src/vfs/VirtualFileSystem.ts
index ef7e8ff4..2479bf5c 100644
--- a/src/vfs/VirtualFileSystem.ts
+++ b/src/vfs/VirtualFileSystem.ts
@@ -846,6 +846,20 @@ export class VirtualFileSystem implements IVirtualFileSystem {
 
     // Get children
     let children = await this.pathResolver.getChildren(entityId)
+    console.log(`[DEBUG VFS] readdir(${path}): Found ${children.length} children`)
+
+    // Debug first child
+    if (children.length > 0) {
+      const firstChild = children[0]
+      console.log(`[DEBUG VFS] First child structure:`, {
+        id: firstChild.id,
+        type: firstChild.type,
+        metadataKeys: Object.keys(firstChild.metadata || {}),
+        metadata_name: firstChild.metadata?.name,
+        metadata_path: firstChild.metadata?.path,
+        metadata_vfsType: firstChild.metadata?.vfsType
+      })
+    }
 
     // Apply filters
     if (options?.filter) {
@@ -870,12 +884,17 @@ export class VirtualFileSystem implements IVirtualFileSystem {
 
     // Return appropriate format
     if (options?.withFileTypes) {
-      return children.map(child => ({
+      const result = children.map(child => ({
         name: child.metadata.name,
         path: child.metadata.path,
         type: child.metadata.vfsType,
         entityId: child.id
       } as VFSDirent))
+      console.log(`[DEBUG VFS] Returning ${result.length} VFSDirent items`)
+      if (result.length > 0) {
+        console.log(`[DEBUG VFS] First VFSDirent:`, result[0])
+      }
+      return result
     }
 
     return children.map(child => child.metadata.name)