**refactor: rename directories and variables for semantic clarity in OPFS storage**

### Changes:
- Renamed `nodes` to `nouns` and `edges` to `verbs` across `opfsStorage.ts`, improving code semantics:
  - Directory constants (e.g., `NODES_DIR` → `NOUNS_DIR`).
  - Class properties, method names, and variables updated accordingly.
- Introduced global type augmentation for `FileSystemDirectoryHandle` to support `entries()` method, improving compatibility.
- Updated directory management logic:
  - Adjusted initialization, recreation, and metadata retrieval methods to reflect new nomenclature.
  - Enhanced handling for directory entries in both `nouns` and `verbs` contexts.
- Refined comments, formatting, and TypeScript annotations for consistency.

### Purpose:
Improved the code's readability and semantic clarity by aligning directory and variable names with their conceptual purpose (`nouns` for entities, `verbs` for relationships). Enhanced maintainability and developer understanding of the storage implementation.

src/storage/fileSystemStorage.ts

@@ -6,8 +6,8 @@ let path: any
 
 // Constants for directory and file names
 const ROOT_DIR = 'brainy-data'
-const NODES_DIR = 'nodes'
+const NOUNS_DIR = 'nouns'
-const EDGES_DIR = 'edges'
+const VERBS_DIR = 'verbs'
 const METADATA_DIR = 'metadata'
 
 // Constants for noun type directories
@@ -24,8 +24,8 @@ const DEFAULT_DIR = 'default' // For nodes without a noun type
  */
 export class FileSystemStorage implements StorageAdapter {
   private rootDir: string
-  private nodesDir: string
+  private nounsDir: string
-  private edgesDir: string
+  private verbsDir: string
   private metadataDir: string
   private personDir: string
   private placeDir: string
@@ -39,8 +39,8 @@ export class FileSystemStorage implements StorageAdapter {
   constructor(rootDirectory?: string) {
     // We'll set the paths in the init method after dynamically importing the modules
     this.rootDir = rootDirectory || ''
-    this.nodesDir = ''
+    this.nounsDir = ''
-    this.edgesDir = ''
+    this.verbsDir = ''
     this.metadataDir = ''
     this.personDir = ''
     this.placeDir = ''
@@ -73,26 +73,26 @@ export class FileSystemStorage implements StorageAdapter {
         // Now set up the directory paths
         const rootDir = this.rootDir || process.cwd()
         this.rootDir = path.resolve(rootDir, ROOT_DIR)
-        this.nodesDir = path.join(this.rootDir, NODES_DIR)
+        this.nounsDir = path.join(this.rootDir, NOUNS_DIR)
-        this.edgesDir = path.join(this.rootDir, EDGES_DIR)
+        this.verbsDir = path.join(this.rootDir, VERBS_DIR)
         this.metadataDir = path.join(this.rootDir, METADATA_DIR)
 
         // Set up noun type directory paths
-        this.personDir = path.join(this.nodesDir, PERSON_DIR)
+        this.personDir = path.join(this.nounsDir, PERSON_DIR)
-        this.placeDir = path.join(this.nodesDir, PLACE_DIR)
+        this.placeDir = path.join(this.nounsDir, PLACE_DIR)
-        this.thingDir = path.join(this.nodesDir, THING_DIR)
+        this.thingDir = path.join(this.nounsDir, THING_DIR)
-        this.eventDir = path.join(this.nodesDir, EVENT_DIR)
+        this.eventDir = path.join(this.nounsDir, EVENT_DIR)
-        this.conceptDir = path.join(this.nodesDir, CONCEPT_DIR)
+        this.conceptDir = path.join(this.nounsDir, CONCEPT_DIR)
-        this.contentDir = path.join(this.nodesDir, CONTENT_DIR)
+        this.contentDir = path.join(this.nounsDir, CONTENT_DIR)
-        this.defaultDir = path.join(this.nodesDir, DEFAULT_DIR)
+        this.defaultDir = path.join(this.nounsDir, DEFAULT_DIR)
       } catch (importError) {
         throw new Error(`Failed to import Node.js modules: ${importError}. This adapter requires a Node.js environment.`)
       }
 
       // Create directories if they don't exist
       await this.ensureDirectoryExists(this.rootDir)
-      await this.ensureDirectoryExists(this.nodesDir)
+      await this.ensureDirectoryExists(this.nounsDir)
-      await this.ensureDirectoryExists(this.edgesDir)
+      await this.ensureDirectoryExists(this.verbsDir)
       await this.ensureDirectoryExists(this.metadataDir)
 
       // Create noun type directories
@@ -430,7 +430,7 @@ export class FileSystemStorage implements StorageAdapter {
         connections: this.mapToObject(verb.connections, (set) => Array.from(set as Set<string>))
       }
 
-      const filePath = path.join(this.edgesDir, `${verb.id}.json`)
+      const filePath = path.join(this.verbsDir, `${verb.id}.json`)
       await fs.promises.writeFile(
         filePath,
         JSON.stringify(serializableEdge, null, 2),
@@ -449,7 +449,7 @@ export class FileSystemStorage implements StorageAdapter {
     await this.ensureInitialized()
 
     try {
-      const filePath = path.join(this.edgesDir, `${id}.json`)
+      const filePath = path.join(this.verbsDir, `${id}.json`)
 
       // Check if a file exists
       try {
@@ -490,7 +490,7 @@ export class FileSystemStorage implements StorageAdapter {
     await this.ensureInitialized()
 
     try {
-      const files = await fs.promises.readdir(this.edgesDir)
+      const files = await fs.promises.readdir(this.verbsDir)
       const edgePromises = files
         .filter((file: string) => file.endsWith('.json'))
         .map((file: string) => {
@@ -558,7 +558,7 @@ export class FileSystemStorage implements StorageAdapter {
     await this.ensureInitialized()
 
     try {
-      const filePath = path.join(this.edgesDir, `${id}.json`)
+      const filePath = path.join(this.verbsDir, `${id}.json`)
 
       // Check if a file exists before attempting to delete
       try {
@@ -625,12 +625,12 @@ export class FileSystemStorage implements StorageAdapter {
 
     try {
       // Delete and recreate the nodes, edges, and metadata directories
-      await this.deleteDirectory(this.nodesDir)
+      await this.deleteDirectory(this.nounsDir)
-      await this.deleteDirectory(this.edgesDir)
+      await this.deleteDirectory(this.verbsDir)
       await this.deleteDirectory(this.metadataDir)
 
-      await this.ensureDirectoryExists(this.nodesDir)
+      await this.ensureDirectoryExists(this.nounsDir)
-      await this.ensureDirectoryExists(this.edgesDir)
+      await this.ensureDirectoryExists(this.verbsDir)
       await this.ensureDirectoryExists(this.metadataDir)
 
       // Create noun type directories
@@ -802,8 +802,8 @@ export class FileSystemStorage implements StorageAdapter {
       }
 
       // Calculate size for each directory
-      const nodesDirSize = await calculateDirSize(this.nodesDir)
+      const nodesDirSize = await calculateDirSize(this.nounsDir)
-      const edgesDirSize = await calculateDirSize(this.edgesDir)
+      const edgesDirSize = await calculateDirSize(this.verbsDir)
       const metadataDirSize = await calculateDirSize(this.metadataDir)
 
       // Calculate sizes of noun type directories

src/storage/s3CompatibleStorage.ts

@@ -5,12 +5,13 @@ type HNSWNode = HNSWNoun;
 type Edge = GraphVerb;
 
 // Constants for S3 bucket prefixes
-const NODES_PREFIX = 'nodes/'
+const NOUNS_PREFIX = 'nouns/'
-const EDGES_PREFIX = 'edges/'
+const VERBS_PREFIX = 'verbs/'
+const EDGES_PREFIX = 'verbs/' // Alias for VERBS_PREFIX for edge operations
 const METADATA_PREFIX = 'metadata/'
 
 // Constants for noun type prefixes
-const PERSON_PREFIX = 'nodes/person/'
+const PERSON_PREFIX = 'nouns/person/'
 const PLACE_PREFIX = 'place/'
 const THING_PREFIX = 'thing/'
 const EVENT_PREFIX = 'event/'
@@ -283,7 +284,7 @@ export class S3CompatibleStorage implements StorageAdapter {
             const response = await this.s3Client.send(
               new GetObjectCommand({
                 Bucket: this.bucketName,
-                Key: `${NODES_PREFIX}${DEFAULT_PREFIX}${id}.json`
+                Key: `${NOUNS_PREFIX}${DEFAULT_PREFIX}${id}.json`
               })
             )
 
@@ -319,7 +320,7 @@ export class S3CompatibleStorage implements StorageAdapter {
                 const response = await this.s3Client.send(
                   new GetObjectCommand({
                     Bucket: this.bucketName,
-                    Key: `${NODES_PREFIX}${prefix}${id}.json`
+                    Key: `${NOUNS_PREFIX}${prefix}${id}.json`
                   })
                 )
 
@@ -393,7 +394,7 @@ export class S3CompatibleStorage implements StorageAdapter {
       const listResponse = await this.s3Client.send(
         new ListObjectsV2Command({
           Bucket: this.bucketName,
-          Prefix: `${NODES_PREFIX}${prefix}`
+          Prefix: `${NOUNS_PREFIX}${prefix}`
         })
       )
 
@@ -515,7 +516,7 @@ export class S3CompatibleStorage implements StorageAdapter {
             await this.s3Client.send(
               new GetObjectCommand({
                 Bucket: this.bucketName,
-                Key: `${NODES_PREFIX}${DEFAULT_PREFIX}${id}.json`
+                Key: `${NOUNS_PREFIX}${DEFAULT_PREFIX}${id}.json`
               })
             )
 
@@ -523,7 +524,7 @@ export class S3CompatibleStorage implements StorageAdapter {
             await this.s3Client.send(
               new DeleteObjectCommand({
                 Bucket: this.bucketName,
-                Key: `${NODES_PREFIX}${DEFAULT_PREFIX}${id}.json`
+                Key: `${NOUNS_PREFIX}${DEFAULT_PREFIX}${id}.json`
               })
             )
             return // Node found and deleted
@@ -545,7 +546,7 @@ export class S3CompatibleStorage implements StorageAdapter {
                 await this.s3Client.send(
                   new GetObjectCommand({
                     Bucket: this.bucketName,
-                    Key: `${NODES_PREFIX}${prefix}${id}.json`
+                    Key: `${NOUNS_PREFIX}${prefix}${id}.json`
                   })
                 )
 
@@ -553,7 +554,7 @@ export class S3CompatibleStorage implements StorageAdapter {
                 await this.s3Client.send(
                   new DeleteObjectCommand({
                     Bucket: this.bucketName,
-                    Key: `${NODES_PREFIX}${prefix}${id}.json`
+                    Key: `${NOUNS_PREFIX}${prefix}${id}.json`
                   })
                 )
                 return // Node found and deleted
@@ -592,7 +593,7 @@ export class S3CompatibleStorage implements StorageAdapter {
       await this.s3Client.send(
         new PutObjectCommand({
           Bucket: this.bucketName,
-          Key: `${EDGES_PREFIX}${edge.id}.json`,
+          Key: `${VERBS_PREFIX}${edge.id}.json`,
           Body: JSON.stringify(serializableEdge, null, 2),
           ContentType: 'application/json'
         })
@@ -618,7 +619,7 @@ export class S3CompatibleStorage implements StorageAdapter {
         const response = await this.s3Client.send(
           new GetObjectCommand({
             Bucket: this.bucketName,
-            Key: `${EDGES_PREFIX}${id}.json`
+            Key: `${VERBS_PREFIX}${id}.json`
           })
         )
 
@@ -665,7 +666,7 @@ export class S3CompatibleStorage implements StorageAdapter {
       const listResponse = await this.s3Client.send(
         new ListObjectsV2Command({
           Bucket: this.bucketName,
-          Prefix: EDGES_PREFIX
+          Prefix: VERBS_PREFIX
         })
       )
 
@@ -932,9 +933,9 @@ export class S3CompatibleStorage implements StorageAdapter {
           totalSize += object.Size || 0
 
           const key = object.Key || ''
-          if (key.startsWith(NODES_PREFIX)) {
+          if (key.startsWith(NOUNS_PREFIX)) {
             nodeCount++
-          } else if (key.startsWith(EDGES_PREFIX)) {
+          } else if (key.startsWith(VERBS_PREFIX)) {
             edgeCount++
           } else if (key.startsWith(METADATA_PREFIX)) {
             metadataCount++
@@ -968,7 +969,7 @@ export class S3CompatibleStorage implements StorageAdapter {
         const listResponse = await this.s3Client.send(
           new ListObjectsV2Command({
             Bucket: this.bucketName,
-            Prefix: `${NODES_PREFIX}${prefix}`
+            Prefix: `${NOUNS_PREFIX}${prefix}`
           })
         )