fix: metadata batch reading from correct directory

Fixed bug where getMetadataBatch() was reading from wrong directory:
- FileSystemStorage: Changed to use getNounMetadata() instead of getMetadata()
- OPFSStorage: Changed to use getNounMetadata() instead of getMetadata()
- MetadataIndex fallback: Fixed to use getNounMetadata()
- Added getNounMetadata() to StorageAdapter interface

This resolves 0% success rate during metadata index rebuild.

Also added comprehensive API documentation for return values and data field behavior.

src/storage/adapters/opfsStorage.ts

@@ -633,33 +633,33 @@ export class OPFSStorage extends BaseStorage {
 
     const results = new Map<string, any>()
     const batchSize = 10 // Process 10 files at a time
-    
+
     // Process in batches to avoid overwhelming OPFS
     for (let i = 0; i < ids.length; i += batchSize) {
       const batch = ids.slice(i, i + batchSize)
-      
+
       const batchPromises = batch.map(async (id) => {
         try {
-          const metadata = await this.getMetadata(id)
+          const metadata = await this.getNounMetadata(id)
           return { id, metadata }
         } catch (error) {
           console.debug(`Failed to read metadata for ${id}:`, error)
           return { id, metadata: null }
         }
       })
-      
+
       const batchResults = await Promise.all(batchPromises)
-      
+
       for (const { id, metadata } of batchResults) {
         if (metadata !== null) {
           results.set(id, metadata)
         }
       }
-      
+
       // Small yield between batches
       await new Promise(resolve => setImmediate(resolve))
     }
-    
+
     return results
   }