@soulcraft/brainy 4.7.4 → 4.8.1

package/dist/storage/adapters/fileSystemStorage.js

@@ -2,6 +2,7 @@
  * File System Storage Adapter
  * File system storage adapter for Node.js environments
  */
+import { NounType } from '../../coreTypes.js';
 import { BaseStorage, SYSTEM_DIR, STATISTICS_KEY } from '../baseStorage.js';
 // Node.js modules - dynamically imported to avoid issues in browser environments
 let fs;
@@ -768,13 +769,23 @@ export class FileSystemStorage extends BaseStorage {
                         }
                         connections = connectionsMap;
                     }
-                    // v4.0.0: Create HNSWNounWithMetadata by combining noun with metadata
+                    // v4.8.0: Extract standard fields from metadata to top-level
+                    const metadataObj = (metadata || {});
+                    const { noun: nounType, createdAt, updatedAt, confidence, weight, service, data: dataField, createdBy, ...customMetadata } = metadataObj;
                     const nounWithMetadata = {
                         id: parsedNoun.id,
                         vector: parsedNoun.vector,
                         connections: connections,
                         level: parsedNoun.level || 0,
-                        metadata: (metadata || {}) // Empty if none
+                        type: nounType || NounType.Thing,
+                        createdAt: createdAt || Date.now(),
+                        updatedAt: updatedAt || Date.now(),
+                        confidence: confidence,
+                        weight: weight,
+                        service: service,
+                        data: dataField,
+                        createdBy,
+                        metadata: customMetadata
                     };
                     items.push(nounWithMetadata);
                     successfullyLoaded++;
@@ -1124,11 +1135,9 @@ export class FileSystemStorage extends BaseStorage {
                     const edge = JSON.parse(data);
                     // Get metadata which contains the actual verb information
                     const metadata = await this.getVerbMetadata(id);
-                    // v4.0.0: No fallbacks - skip verbs without metadata
-                    if (!metadata) {
-                        console.warn(`Verb ${id} has no metadata, skipping`);
-                        continue;
-                    }
+                    // v4.8.1: Don't skip verbs without metadata - metadata is optional
+                    // FIX: This was the root cause of the VFS bug (11 versions)
+                    // Verbs can exist without metadata files (e.g., from imports/migrations)
                     // Convert connections Map to proper format if needed
                     let connections = edge.connections;
                     if (connections && typeof connections === 'object' && !(connections instanceof Map)) {
@@ -1138,7 +1147,9 @@ export class FileSystemStorage extends BaseStorage {
                         }
                         connections = connectionsMap;
                     }
-                    // v4.0.0: Clean HNSWVerbWithMetadata construction
+                    // v4.8.0: Extract standard fields from metadata to top-level
+                    const metadataObj = (metadata || {});
+                    const { createdAt, updatedAt, confidence, weight, service, data: dataField, createdBy, ...customMetadata } = metadataObj;
                     const verbWithMetadata = {
                         id: edge.id,
                         vector: edge.vector,
@@ -1146,7 +1157,14 @@ export class FileSystemStorage extends BaseStorage {
                         verb: edge.verb,
                         sourceId: edge.sourceId,
                         targetId: edge.targetId,
-                        metadata: metadata
+                        createdAt: createdAt || Date.now(),
+                        updatedAt: updatedAt || Date.now(),
+                        confidence: confidence,
+                        weight: weight,
+                        service: service,
+                        data: dataField,
+                        createdBy,
+                        metadata: customMetadata
                     };
                     // Apply filters if provided
                     if (options.filter) {
@@ -2005,11 +2023,9 @@ export class FileSystemStorage extends BaseStorage {
                     const data = await fs.promises.readFile(filePath, 'utf-8');
                     const edge = JSON.parse(data);
                     const metadata = await this.getVerbMetadata(id);
-                    // v4.0.0: No fallbacks - skip verbs without metadata
-                    if (!metadata) {
-                        processedCount++;
-                        return true; // continue, skip this verb
-                    }
+                    // v4.8.1: Don't skip verbs without metadata - metadata is optional
+                    // FIX: This was the root cause of the VFS bug (11 versions)
+                    // Verbs can exist without metadata files (e.g., from imports/migrations)
                     // Convert connections if needed
                     let connections = edge.connections;
                     if (connections && typeof connections === 'object' && !(connections instanceof Map)) {
@@ -2019,7 +2035,9 @@ export class FileSystemStorage extends BaseStorage {
                         }
                         connections = connectionsMap;
                     }
-                    // v4.0.0: Clean HNSWVerbWithMetadata construction
+                    // v4.8.0: Extract standard fields from metadata to top-level
+                    const metadataObj = (metadata || {});
+                    const { createdAt, updatedAt, confidence, weight, service, data: dataField, createdBy, ...customMetadata } = metadataObj;
                     const verbWithMetadata = {
                         id: edge.id,
                         vector: edge.vector,
@@ -2027,7 +2045,14 @@ export class FileSystemStorage extends BaseStorage {
                         verb: edge.verb,
                         sourceId: edge.sourceId,
                         targetId: edge.targetId,
-                        metadata: metadata
+                        createdAt: createdAt || Date.now(),
+                        updatedAt: updatedAt || Date.now(),
+                        confidence: confidence,
+                        weight: weight,
+                        service: service,
+                        data: dataField,
+                        createdBy,
+                        metadata: customMetadata
                     };
                     // Apply filters
                     if (options.filter) {

package/dist/storage/adapters/gcsStorage.js

@@ -8,6 +8,7 @@
  * 3. Service Account Credentials Object
  * 4. HMAC Keys (fallback for backward compatibility)
  */
+import { NounType } from '../../coreTypes.js';
 import { BaseStorage, SYSTEM_DIR, STATISTICS_KEY, getDirectoryPath } from '../baseStorage.js';
 import { BrainyError } from '../../errors/brainyError.js';
 import { CacheManager } from '../cacheManager.js';
@@ -832,13 +833,23 @@ export class GcsStorage extends BaseStorage {
                         continue;
                 }
             }
-            // Combine node with metadata
+            // v4.8.0: Extract standard fields from metadata to top-level
+            const metadataObj = (metadata || {});
+            const { noun: nounType, createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
             const nounWithMetadata = {
                 id: node.id,
                 vector: [...node.vector],
                 connections: new Map(node.connections),
                 level: node.level || 0,
-                metadata: (metadata || {}) // Empty if none
+                type: nounType || NounType.Thing,
+                createdAt: createdAt || Date.now(),
+                updatedAt: updatedAt || Date.now(),
+                confidence: confidence,
+                weight: weight,
+                service: service,
+                data: data,
+                createdBy,
+                metadata: customMetadata
             };
             items.push(nounWithMetadata);
         }
@@ -1076,7 +1087,9 @@ export class GcsStorage extends BaseStorage {
                             continue;
                     }
                 }
-                // Combine verb with metadata
+                // v4.8.0: Extract standard fields from metadata to top-level
+                const metadataObj = (metadata || {});
+                const { createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
                 const verbWithMetadata = {
                     id: hnswVerb.id,
                     vector: [...hnswVerb.vector],
@@ -1084,7 +1097,14 @@ export class GcsStorage extends BaseStorage {
                     verb: hnswVerb.verb,
                     sourceId: hnswVerb.sourceId,
                     targetId: hnswVerb.targetId,
-                    metadata: metadata || {}
+                    createdAt: createdAt || Date.now(),
+                    updatedAt: updatedAt || Date.now(),
+                    confidence: confidence,
+                    weight: weight,
+                    service: service,
+                    data: data,
+                    createdBy,
+                    metadata: customMetadata
                 };
                 items.push(verbWithMetadata);
             }

package/dist/storage/adapters/memoryStorage.js

@@ -2,6 +2,7 @@
  * Memory Storage Adapter
  * In-memory storage adapter for environments where persistent storage is not available or needed
  */
+import { NounType } from '../../coreTypes.js';
 import { BaseStorage } from '../baseStorage.js';
 // No type aliases needed - using the original types directly
 /**
@@ -154,13 +155,26 @@ export class MemoryStorage extends BaseStorage {
             // Get metadata from separate storage
             // FIX v4.7.4: Don't skip nouns without metadata - metadata is optional in v4.0.0
             const metadata = await this.getNounMetadata(id);
-            // v4.0.0: Create HNSWNounWithMetadata with metadata field
+            // v4.8.0: Extract standard fields from metadata to top-level
+            const metadataObj = (metadata || {});
+            const { noun: nounType, createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
+            // v4.8.0: Create HNSWNounWithMetadata with standard fields at top-level
             const nounWithMetadata = {
                 id: noun.id,
                 vector: [...noun.vector],
                 connections: new Map(),
                 level: noun.level || 0,
-                metadata: (metadata || {}) // Include metadata field (empty if none)
+                // v4.8.0: Standard fields at top-level
+                type: nounType || NounType.Thing,
+                createdAt: createdAt || Date.now(),
+                updatedAt: updatedAt || Date.now(),
+                confidence: confidence,
+                weight: weight,
+                service: service,
+                data: data,
+                createdBy,
+                // Only custom user fields in metadata
+                metadata: customMetadata
             };
             // Copy connections
             for (const [level, connections] of noun.connections.entries()) {
@@ -359,7 +373,10 @@ export class MemoryStorage extends BaseStorage {
             // FIX v4.7.4: Don't skip verbs without metadata - metadata is optional in v4.0.0
             // Core fields (verb, sourceId, targetId) are in HNSWVerb itself
             const metadata = await this.getVerbMetadata(id);
-            // v4.0.0: Create HNSWVerbWithMetadata with metadata field
+            // v4.8.0: Extract standard fields from metadata to top-level
+            const metadataObj = metadata || {};
+            const { createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
+            // v4.8.0: Create HNSWVerbWithMetadata with standard fields at top-level
             const verbWithMetadata = {
                 id: hnswVerb.id,
                 vector: [...hnswVerb.vector],
@@ -368,8 +385,16 @@ export class MemoryStorage extends BaseStorage {
                 verb: hnswVerb.verb,
                 sourceId: hnswVerb.sourceId,
                 targetId: hnswVerb.targetId,
-                // Metadata field (empty if none)
-                metadata: metadata || {}
+                // v4.8.0: Standard fields at top-level
+                createdAt: createdAt || Date.now(),
+                updatedAt: updatedAt || Date.now(),
+                confidence: confidence,
+                weight: weight,
+                service: service,
+                data: data,
+                createdBy,
+                // Only custom user fields in metadata
+                metadata: customMetadata
             };
             // Copy connections
             for (const [level, connections] of hnswVerb.connections.entries()) {

package/dist/storage/adapters/opfsStorage.js

@@ -2,6 +2,7 @@
  * OPFS (Origin Private File System) Storage Adapter
  * Provides persistent storage for the vector database using the Origin Private File System API
  */
+import { NounType } from '../../coreTypes.js';
 import { BaseStorage, NOUNS_DIR, VERBS_DIR, METADATA_DIR, NOUN_METADATA_DIR, VERB_METADATA_DIR, INDEX_DIR } from '../baseStorage.js';
 import { getShardIdFromUuid } from '../sharding.js';
 import '../../types/fileSystemTypes.js';
@@ -1446,13 +1447,23 @@ export class OPFSStorage extends BaseStorage {
                             continue;
                     }
                 }
-                // v4.0.0: Create HNSWNounWithMetadata by combining noun with metadata
+                // v4.8.0: Extract standard fields from metadata to top-level
+                const metadataObj = (metadata || {});
+                const { noun: nounType, createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
                 const nounWithMetadata = {
                     id: noun.id,
                     vector: [...noun.vector],
                     connections: new Map(noun.connections),
                     level: noun.level || 0,
-                    metadata: (metadata || {}) // Empty if none
+                    type: nounType || NounType.Thing,
+                    createdAt: createdAt || Date.now(),
+                    updatedAt: updatedAt || Date.now(),
+                    confidence: confidence,
+                    weight: weight,
+                    service: service,
+                    data: data,
+                    createdBy,
+                    metadata: customMetadata
                 };
                 items.push(nounWithMetadata);
             }
@@ -1572,7 +1583,9 @@ export class OPFSStorage extends BaseStorage {
                             continue;
                     }
                 }
-                // v4.0.0: Create HNSWVerbWithMetadata by combining verb with metadata
+                // v4.8.0: Extract standard fields from metadata to top-level
+                const metadataObj = (metadata || {});
+                const { createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
                 const verbWithMetadata = {
                     id: hnswVerb.id,
                     vector: [...hnswVerb.vector],
@@ -1580,7 +1593,14 @@ export class OPFSStorage extends BaseStorage {
                     verb: hnswVerb.verb,
                     sourceId: hnswVerb.sourceId,
                     targetId: hnswVerb.targetId,
-                    metadata: (metadata || {}) // Empty if none
+                    createdAt: createdAt || Date.now(),
+                    updatedAt: updatedAt || Date.now(),
+                    confidence: confidence,
+                    weight: weight,
+                    service: service,
+                    data: data,
+                    createdBy,
+                    metadata: customMetadata
                 };
                 items.push(verbWithMetadata);
             }

package/dist/storage/adapters/r2Storage.js

@@ -11,6 +11,7 @@
  *
  * Based on latest GCS and S3 implementations with R2-specific enhancements
  */
+import { NounType } from '../../coreTypes.js';
 import { BaseStorage, SYSTEM_DIR, STATISTICS_KEY, getDirectoryPath } from '../baseStorage.js';
 import { BrainyError } from '../../errors/brainyError.js';
 import { CacheManager } from '../cacheManager.js';
@@ -918,13 +919,23 @@ export class R2Storage extends BaseStorage {
                             continue;
                     }
                 }
-                // v4.0.0: Create HNSWNounWithMetadata by combining noun with metadata
+                // v4.8.0: Extract standard fields from metadata to top-level
+                const metadataObj = (metadata || {});
+                const { noun: nounType, createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
                 const nounWithMetadata = {
                     id: noun.id,
                     vector: [...noun.vector],
                     connections: new Map(noun.connections),
                     level: noun.level || 0,
-                    metadata: (metadata || {}) // Empty if none
+                    type: nounType || NounType.Thing,
+                    createdAt: createdAt || Date.now(),
+                    updatedAt: updatedAt || Date.now(),
+                    confidence: confidence,
+                    weight: weight,
+                    service: service,
+                    data: data,
+                    createdBy,
+                    metadata: customMetadata
                 };
                 items.push(nounWithMetadata);
             }

package/dist/storage/adapters/s3CompatibleStorage.js

@@ -3,6 +3,7 @@
  * Uses the AWS S3 client to interact with S3-compatible storage services
  * including Amazon S3, Cloudflare R2, and Google Cloud Storage
  */
+import { NounType } from '../../coreTypes.js';
 import { BaseStorage, INDEX_DIR, SYSTEM_DIR, STATISTICS_KEY, getDirectoryPath } from '../baseStorage.js';
 import { StorageCompatibilityLayer } from '../backwardCompatibility.js';
 import { StorageOperationExecutors } from '../../utils/operationUtils.js';
@@ -1479,6 +1480,9 @@ export class S3CompatibleStorage extends BaseStorage {
         const verbsWithMetadata = [];
         for (const hnswVerb of result.edges) {
             const metadata = await this.getVerbMetadata(hnswVerb.id);
+            // v4.8.0: Extract standard fields from metadata to top-level
+            const metadataObj = (metadata || {});
+            const { createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
             const verbWithMetadata = {
                 id: hnswVerb.id,
                 vector: [...hnswVerb.vector],
@@ -1486,7 +1490,14 @@ export class S3CompatibleStorage extends BaseStorage {
                 verb: hnswVerb.verb,
                 sourceId: hnswVerb.sourceId,
                 targetId: hnswVerb.targetId,
-                metadata: metadata || {}
+                createdAt: createdAt || Date.now(),
+                updatedAt: updatedAt || Date.now(),
+                confidence: confidence,
+                weight: weight,
+                service: service,
+                data: data,
+                createdBy,
+                metadata: customMetadata
             };
             verbsWithMetadata.push(verbWithMetadata);
         }
@@ -2899,13 +2910,23 @@ export class S3CompatibleStorage extends BaseStorage {
                     }
                 }
             }
-            // Create HNSWNounWithMetadata
+            // v4.8.0: Extract standard fields from metadata to top-level
+            const metadataObj = (metadata || {});
+            const { noun: nounType, createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
             const nounWithMetadata = {
                 id: node.id,
                 vector: [...node.vector],
                 connections: new Map(node.connections),
                 level: node.level || 0,
-                metadata: (metadata || {}) // Empty if none
+                type: nounType || NounType.Thing,
+                createdAt: createdAt || Date.now(),
+                updatedAt: updatedAt || Date.now(),
+                confidence: confidence,
+                weight: weight,
+                service: service,
+                data: data,
+                createdBy,
+                metadata: customMetadata
             };
             nounsWithMetadata.push(nounWithMetadata);
         }

package/dist/storage/adapters/typeAwareStorageAdapter.js

@@ -335,105 +335,27 @@ export class TypeAwareStorageAdapter extends BaseStorage {
      * Get verbs by source
      */
     async getVerbsBySource_internal(sourceId) {
-        // Need to search across all verb types
-        // TODO: Optimize with metadata index in Phase 1b
-        const verbs = [];
-        for (let i = 0; i < VERB_TYPE_COUNT; i++) {
-            const type = TypeUtils.getVerbFromIndex(i);
-            const prefix = `entities/verbs/${type}/vectors/`;
-            const paths = await this.u.listObjectsUnderPath(prefix);
-            for (const path of paths) {
-                try {
-                    const id = path.split('/').pop()?.replace('.json', '');
-                    if (!id)
-                        continue;
-                    // Load the HNSWVerb
-                    const hnswVerb = await this.u.readObjectFromPath(path);
-                    if (!hnswVerb)
-                        continue;
-                    // Check sourceId from HNSWVerb (v4.0.0: core fields are in HNSWVerb)
-                    if (hnswVerb.sourceId !== sourceId)
-                        continue;
-                    // Load metadata separately (optional in v4.0.0!)
-                    // FIX: Don't skip verbs without metadata - metadata is optional!
-                    // VFS relationships often have NO metadata (just verb/source/target)
-                    const metadata = await this.getVerbMetadata(id);
-                    // Create HNSWVerbWithMetadata (verbs don't have level field)
-                    // Convert connections from plain object to Map<number, Set<string>>
-                    const connectionsMap = new Map();
-                    if (hnswVerb.connections && typeof hnswVerb.connections === 'object') {
-                        for (const [level, ids] of Object.entries(hnswVerb.connections)) {
-                            connectionsMap.set(Number(level), new Set(ids));
-                        }
-                    }
-                    const verbWithMetadata = {
-                        id: hnswVerb.id,
-                        vector: [...hnswVerb.vector],
-                        connections: connectionsMap,
-                        verb: hnswVerb.verb,
-                        sourceId: hnswVerb.sourceId,
-                        targetId: hnswVerb.targetId,
-                        metadata: metadata || {} // Empty metadata if none exists
-                    };
-                    verbs.push(verbWithMetadata);
-                }
-                catch (error) {
-                    // Continue searching
-                }
-            }
-        }
-        return verbs;
+        // v4.8.1 PERFORMANCE FIX: Delegate to underlying storage instead of scanning all files
+        // Previous implementation was O(total_verbs) - scanned ALL 40 verb types and ALL verb files
+        // This was the root cause of the 11-version VFS bug (timeouts/zero results)
+        //
+        // Underlying storage adapters have optimized implementations:
+        // - FileSystemStorage: Uses getVerbsWithPagination with sourceId filter
+        // - GcsStorage: Uses batch queries with prefix filtering
+        // - S3Storage: Uses listObjects with sourceId-based filtering
+        //
+        // Phase 1b TODO: Add graph adjacency index query for O(1) lookups:
+        // const verbIds = await this.graphIndex?.getOutgoingEdges(sourceId) || []
+        // return Promise.all(verbIds.map(id => this.getVerb(id)))
+        return this.underlying.getVerbsBySource(sourceId);
     }
     /**
      * Get verbs by target
      */
     async getVerbsByTarget_internal(targetId) {
-        // Similar to getVerbsBySource_internal
-        const verbs = [];
-        for (let i = 0; i < VERB_TYPE_COUNT; i++) {
-            const type = TypeUtils.getVerbFromIndex(i);
-            const prefix = `entities/verbs/${type}/vectors/`;
-            const paths = await this.u.listObjectsUnderPath(prefix);
-            for (const path of paths) {
-                try {
-                    const id = path.split('/').pop()?.replace('.json', '');
-                    if (!id)
-                        continue;
-                    // Load the HNSWVerb
-                    const hnswVerb = await this.u.readObjectFromPath(path);
-                    if (!hnswVerb)
-                        continue;
-                    // Check targetId from HNSWVerb (v4.0.0: core fields are in HNSWVerb)
-                    if (hnswVerb.targetId !== targetId)
-                        continue;
-                    // Load metadata separately (optional in v4.0.0!)
-                    // FIX: Don't skip verbs without metadata - metadata is optional!
-                    const metadata = await this.getVerbMetadata(id);
-                    // Create HNSWVerbWithMetadata (verbs don't have level field)
-                    // Convert connections from plain object to Map<number, Set<string>>
-                    const connectionsMap = new Map();
-                    if (hnswVerb.connections && typeof hnswVerb.connections === 'object') {
-                        for (const [level, ids] of Object.entries(hnswVerb.connections)) {
-                            connectionsMap.set(Number(level), new Set(ids));
-                        }
-                    }
-                    const verbWithMetadata = {
-                        id: hnswVerb.id,
-                        vector: [...hnswVerb.vector],
-                        connections: connectionsMap,
-                        verb: hnswVerb.verb,
-                        sourceId: hnswVerb.sourceId,
-                        targetId: hnswVerb.targetId,
-                        metadata: metadata || {} // Empty metadata if none exists
-                    };
-                    verbs.push(verbWithMetadata);
-                }
-                catch (error) {
-                    // Continue
-                }
-            }
-        }
-        return verbs;
+        // v4.8.1 PERFORMANCE FIX: Delegate to underlying storage (same as getVerbsBySource fix)
+        // Previous implementation was O(total_verbs) - scanned ALL 40 verb types and ALL verb files
+        return this.underlying.getVerbsByTarget(targetId);
     }
     /**
      * Get verbs by type (O(1) with type-first paths!)
@@ -463,6 +385,9 @@ export class TypeAwareStorageAdapter extends BaseStorage {
                         connectionsMap.set(Number(level), new Set(ids));
                     }
                 }
+                // v4.8.0: Extract standard fields from metadata to top-level
+                const metadataObj = (metadata || {});
+                const { createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
                 const verbWithMetadata = {
                     id: hnswVerb.id,
                     vector: [...hnswVerb.vector],
@@ -470,7 +395,14 @@ export class TypeAwareStorageAdapter extends BaseStorage {
                     verb: hnswVerb.verb,
                     sourceId: hnswVerb.sourceId,
                     targetId: hnswVerb.targetId,
-                    metadata: metadata || {} // Empty metadata if none exists
+                    createdAt: createdAt || Date.now(),
+                    updatedAt: updatedAt || Date.now(),
+                    confidence: confidence,
+                    weight: weight,
+                    service: service,
+                    data: data,
+                    createdBy,
+                    metadata: customMetadata
                 };
                 verbs.push(verbWithMetadata);
             }

package/dist/storage/baseStorage.js

@@ -5,6 +5,7 @@
 import { GraphAdjacencyIndex } from '../graph/graphAdjacencyIndex.js';
 import { BaseStorageAdapter } from './adapters/baseStorageAdapter.js';
 import { validateNounType, validateVerbType } from '../utils/typeValidation.js';
+import { NounType } from '../types/graphTypes.js';
 import { getShardIdFromUuid } from './sharding.js';
 // Clean directory structure (v4.7.2+)
 // All storage adapters use this consistent structure
@@ -46,6 +47,10 @@ export class BaseStorage extends BaseStorageAdapter {
      * @private
      */
     analyzeKey(id, context) {
+        // v4.8.0: Guard against undefined/null IDs
+        if (!id || typeof id !== 'string') {
+            throw new Error(`Invalid storage key: ${id} (must be a non-empty string)`);
+        }
         // System resource detection
         const isSystemKey = id.startsWith('__metadata_') ||
             id.startsWith('__index_') ||
@@ -142,13 +147,24 @@ export class BaseStorage extends BaseStorageAdapter {
             console.warn(`[Storage] Noun ${id} has vector but no metadata - this should not happen in v4.0.0`);
             return null;
         }
-        // Combine into HNSWNounWithMetadata
+        // Combine into HNSWNounWithMetadata - v4.8.0: Extract standard fields to top-level
+        const { noun, createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadata;
         return {
             id: vector.id,
             vector: vector.vector,
             connections: vector.connections,
             level: vector.level,
-            metadata
+            // v4.8.0: Standard fields at top-level
+            type: noun || NounType.Thing,
+            createdAt: createdAt || Date.now(),
+            updatedAt: updatedAt || Date.now(),
+            confidence: confidence,
+            weight: weight,
+            service: service,
+            data: data,
+            createdBy,
+            // Only custom user fields remain in metadata
+            metadata: customMetadata
         };
     }
     /**
@@ -160,14 +176,25 @@ export class BaseStorage extends BaseStorageAdapter {
         await this.ensureInitialized();
         // Internal method returns HNSWNoun[], need to combine with metadata
         const nouns = await this.getNounsByNounType_internal(nounType);
-        // Combine each noun with its metadata
+        // Combine each noun with its metadata - v4.8.0: Extract standard fields to top-level
         const nounsWithMetadata = [];
         for (const noun of nouns) {
             const metadata = await this.getNounMetadata(noun.id);
             if (metadata) {
+                const { noun: nounType, createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadata;
                 nounsWithMetadata.push({
                     ...noun,
-                    metadata
+                    // v4.8.0: Standard fields at top-level
+                    type: nounType || NounType.Thing,
+                    createdAt: createdAt || Date.now(),
+                    updatedAt: updatedAt || Date.now(),
+                    confidence: confidence,
+                    weight: weight,
+                    service: service,
+                    data: data,
+                    createdBy,
+                    // Only custom user fields in metadata
+                    metadata: customMetadata
                 });
             }
         }
@@ -220,7 +247,8 @@ export class BaseStorage extends BaseStorageAdapter {
             console.warn(`[Storage] Verb ${id} has vector but no metadata - this should not happen in v4.0.0`);
             return null;
         }
-        // Combine into HNSWVerbWithMetadata
+        // Combine into HNSWVerbWithMetadata - v4.8.0: Extract standard fields to top-level
+        const { createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadata;
         return {
             id: verb.id,
             vector: verb.vector,
@@ -228,7 +256,16 @@ export class BaseStorage extends BaseStorageAdapter {
             verb: verb.verb,
             sourceId: verb.sourceId,
             targetId: verb.targetId,
-            metadata
+            // v4.8.0: Standard fields at top-level
+            createdAt: createdAt || Date.now(),
+            updatedAt: updatedAt || Date.now(),
+            confidence: confidence,
+            weight: weight,
+            service: service,
+            data: data,
+            createdBy,
+            // Only custom user fields remain in metadata
+            metadata: customMetadata
         };
     }
     /**