@soulcraft/brainy 5.4.0 → 5.6.0

package/dist/storage/adapters/typeAwareStorageAdapter.js

@@ -1,1012 +0,0 @@
-/**
- * Type-Aware Storage Adapter
- *
- * Wraps underlying storage (FileSystem, GCS, S3, etc.) with type-first organization.
- * Enables efficient type-based queries via directory structure.
- *
- * IMPLEMENTED Features (v3.45.0):
- * - Type-first paths: entities/nouns/{type}/vectors/{shard}/{uuid}.json
- * - Fixed-size type count tracking: Uint32Array(31 + 40) = 284 bytes
- * - Type-based filtering: List entities by type via directory structure
- * - Type caching: Map<id, type> for frequently accessed entities
- *
- * MEASURED Performance (tests up to 1M entities):
- * - Type count memory: 284 bytes (vs Map-based: ~100KB at 1M scale) = 99.7% reduction
- * - getNounsByType: O(entities_of_type) via directory scan (vs O(total) full scan)
- * - getVerbsByType: O(entities_of_type) via directory scan (vs O(total) full scan)
- * - Type-cached lookups: O(1) after first access
- *
- * PROJECTED Performance (billion-scale, NOT tested):
- * - Total memory: PROJECTED ~50-100GB (vs theoretical 500GB baseline)
- * - Type count: 284 bytes remains constant (not dependent on entity count)
- * - Type cache: Grows with usage (10% cached at 1B = ~5GB overhead)
- * - Note: Billion-scale claims are EXTRAPOLATIONS, not measurements
- *
- * LIMITATIONS:
- * - Type cache grows unbounded (no eviction policy)
- * - Uncached entity lookups: O(types) worst case (searches all type directories)
- * - v4.8.1: getVerbsBySource/Target delegate to underlying (previously O(total_verbs))
- *
- * TEST COVERAGE:
- * - Unit tests: typeAwareStorageAdapter.test.ts (17 tests passing)
- * - Integration tests: Tested with 1,155 entities (Workshop data)
- * - Performance tests: None (no benchmark comparisons yet)
- *
- * @version 3.45.0 (created), 4.8.1 (performance fix)
- * @since Phase 1 - Type-First Implementation
- */
-import { BaseStorage } from '../baseStorage.js';
-import { NounType, TypeUtils, NOUN_TYPE_COUNT, VERB_TYPE_COUNT } from '../../types/graphTypes.js';
-import { getShardIdFromUuid } from '../sharding.js';
-/**
- * Type-first storage paths
- * Beautiful, self-documenting structure
- */
-const SYSTEM_DIR = '_system';
-/**
- * Get type-first path for noun vectors
- */
-function getNounVectorPath(type, id) {
-    const shard = getShardIdFromUuid(id);
-    return `entities/nouns/${type}/vectors/${shard}/${id}.json`;
-}
-/**
- * Get type-first path for noun metadata
- */
-function getNounMetadataPath(type, id) {
-    const shard = getShardIdFromUuid(id);
-    return `entities/nouns/${type}/metadata/${shard}/${id}.json`;
-}
-/**
- * Get type-first path for verb vectors
- */
-function getVerbVectorPath(type, id) {
-    const shard = getShardIdFromUuid(id);
-    return `entities/verbs/${type}/vectors/${shard}/${id}.json`;
-}
-/**
- * Get type-first path for verb metadata
- */
-function getVerbMetadataPath(type, id) {
-    const shard = getShardIdFromUuid(id);
-    return `entities/verbs/${type}/metadata/${shard}/${id}.json`;
-}
-/**
- * Type-Aware Storage Adapter
- *
- * Wraps an underlying storage adapter and adds type-first routing
- * Tracks types with fixed-size arrays for billion-scale efficiency
- */
-export class TypeAwareStorageAdapter extends BaseStorage {
-    constructor(options) {
-        super();
-        // Fixed-size type tracking (99.76% memory reduction vs Maps)
-        this.nounCountsByType = new Uint32Array(NOUN_TYPE_COUNT); // 124 bytes
-        this.verbCountsByType = new Uint32Array(VERB_TYPE_COUNT); // 160 bytes
-        // Total: 284 bytes (vs ~120KB with Maps)
-        // Type cache for fast lookups (id -> type)
-        // Only for entities we've seen this session (bounded size)
-        this.nounTypeCache = new Map();
-        this.verbTypeCache = new Map();
-        this.underlying = options.underlyingStorage;
-        this.verbose = options.verbose || false;
-    }
-    /**
-     * Helper to access protected methods on underlying storage
-     * TypeScript doesn't allow calling protected methods across instances,
-     * so we cast to any to bypass this restriction
-     */
-    get u() {
-        return this.underlying;
-    }
-    /**
-     * Initialize storage adapter
-     */
-    async init() {
-        if (this.verbose) {
-            console.log('[TypeAwareStorage] Initializing...');
-        }
-        // Initialize underlying storage
-        if (typeof this.underlying.init === 'function') {
-            await this.underlying.init();
-        }
-        // Load type statistics from storage (if they exist)
-        await this.loadTypeStatistics();
-        this.isInitialized = true;
-        if (this.verbose) {
-            console.log('[TypeAwareStorage] Initialized successfully');
-            console.log(`[TypeAwareStorage] Noun counts:`, Array.from(this.nounCountsByType));
-            console.log(`[TypeAwareStorage] Verb counts:`, Array.from(this.verbCountsByType));
-        }
-    }
-    /**
-     * Load type statistics from storage
-     * Rebuilds type counts if needed
-     */
-    async loadTypeStatistics() {
-        try {
-            const stats = await this.u.readObjectFromPath(`${SYSTEM_DIR}/type-statistics.json`);
-            if (stats) {
-                // Restore counts from saved statistics
-                if (stats.nounCounts && stats.nounCounts.length === NOUN_TYPE_COUNT) {
-                    this.nounCountsByType = new Uint32Array(stats.nounCounts);
-                }
-                if (stats.verbCounts && stats.verbCounts.length === VERB_TYPE_COUNT) {
-                    this.verbCountsByType = new Uint32Array(stats.verbCounts);
-                }
-            }
-        }
-        catch (error) {
-            if (this.verbose) {
-                console.log('[TypeAwareStorage] No existing type statistics, starting fresh');
-            }
-        }
-    }
-    /**
-     * Save type statistics to storage
-     */
-    async saveTypeStatistics() {
-        const stats = {
-            nounCounts: Array.from(this.nounCountsByType),
-            verbCounts: Array.from(this.verbCountsByType),
-            updatedAt: Date.now()
-        };
-        await this.u.writeObjectToPath(`${SYSTEM_DIR}/type-statistics.json`, stats);
-    }
-    /**
-     * Get noun type from cache
-     *
-     * v4.0.0: Metadata is stored separately, so we rely on the cache
-     * which is populated when saveNounMetadata is called
-     */
-    getNounType(noun) {
-        // Check cache (populated when metadata is saved)
-        const cached = this.nounTypeCache.get(noun.id);
-        if (cached) {
-            return cached;
-        }
-        // Default to 'thing' if unknown
-        // This should only happen if saveNoun_internal is called before saveNounMetadata
-        console.warn(`[TypeAwareStorage] Unknown noun type for ${noun.id}, defaulting to 'thing'`);
-        return 'thing';
-    }
-    /**
-     * Get verb type from verb object
-     *
-     * ARCHITECTURAL FIX (v3.50.1): Simplified - verb field is now always present
-     */
-    getVerbType(verb) {
-        // v3.50.1+: verb is a required field in HNSWVerb
-        if ('verb' in verb && verb.verb) {
-            return verb.verb;
-        }
-        // Fallback for GraphVerb (type alias)
-        if ('type' in verb && verb.type) {
-            return verb.type;
-        }
-        // This should never happen with v3.50.1+ data
-        console.warn(`[TypeAwareStorage] Verb missing type field for ${verb.id}, defaulting to 'relatedTo'`);
-        return 'relatedTo';
-    }
-    // ============================================================================
-    // ABSTRACT METHOD IMPLEMENTATIONS
-    // ============================================================================
-    /**
-     * Save noun (type-first path)
-     */
-    async saveNoun_internal(noun) {
-        const type = this.getNounType(noun);
-        const path = getNounVectorPath(type, noun.id);
-        // Update type tracking
-        const typeIndex = TypeUtils.getNounIndex(type);
-        this.nounCountsByType[typeIndex]++;
-        this.nounTypeCache.set(noun.id, type);
-        // COW-aware write (v5.0.1): Use COW helper for branch isolation
-        await this.writeObjectToBranch(path, noun);
-        // Periodically save statistics (every 100 saves)
-        if (this.nounCountsByType[typeIndex] % 100 === 0) {
-            await this.saveTypeStatistics();
-        }
-    }
-    /**
-     * Get noun (type-first path)
-     */
-    async getNoun_internal(id) {
-        // Try cache first
-        const cachedType = this.nounTypeCache.get(id);
-        if (cachedType) {
-            const path = getNounVectorPath(cachedType, id);
-            // COW-aware read (v5.0.1): Use COW helper for branch isolation
-            return await this.readWithInheritance(path);
-        }
-        // Need to search across all types (expensive, but cached after first access)
-        for (let i = 0; i < NOUN_TYPE_COUNT; i++) {
-            const type = TypeUtils.getNounFromIndex(i);
-            const path = getNounVectorPath(type, id);
-            try {
-                // COW-aware read (v5.0.1): Use COW helper for branch isolation
-                const noun = await this.readWithInheritance(path);
-                if (noun) {
-                    // Cache the type for next time
-                    this.nounTypeCache.set(id, type);
-                    return noun;
-                }
-            }
-            catch (error) {
-                // Not in this type, continue searching
-            }
-        }
-        return null;
-    }
-    /**
-     * Get nouns by noun type (O(1) with type-first paths!)
-     */
-    async getNounsByNounType_internal(nounType) {
-        const type = nounType;
-        const prefix = `entities/nouns/${type}/vectors/`;
-        // COW-aware list (v5.0.1): Use COW helper for branch isolation
-        const paths = await this.listObjectsInBranch(prefix);
-        // Load all nouns of this type
-        const nouns = [];
-        for (const path of paths) {
-            try {
-                // COW-aware read (v5.0.1): Use COW helper for branch isolation
-                const noun = await this.readWithInheritance(path);
-                if (noun) {
-                    nouns.push(noun);
-                    // Cache the type
-                    this.nounTypeCache.set(noun.id, type);
-                }
-            }
-            catch (error) {
-                console.warn(`[TypeAwareStorage] Failed to load noun from ${path}:`, error);
-            }
-        }
-        return nouns;
-    }
-    /**
-     * Delete noun (type-first path)
-     */
-    async deleteNoun_internal(id) {
-        // Try cache first
-        const cachedType = this.nounTypeCache.get(id);
-        if (cachedType) {
-            const path = getNounVectorPath(cachedType, id);
-            // COW-aware delete (v5.0.1): Use COW helper for branch isolation
-            await this.deleteObjectFromBranch(path);
-            // Update counts
-            const typeIndex = TypeUtils.getNounIndex(cachedType);
-            if (this.nounCountsByType[typeIndex] > 0) {
-                this.nounCountsByType[typeIndex]--;
-            }
-            this.nounTypeCache.delete(id);
-            return;
-        }
-        // Search across all types
-        for (let i = 0; i < NOUN_TYPE_COUNT; i++) {
-            const type = TypeUtils.getNounFromIndex(i);
-            const path = getNounVectorPath(type, id);
-            try {
-                // COW-aware delete (v5.0.1): Use COW helper for branch isolation
-                await this.deleteObjectFromBranch(path);
-                // Update counts
-                if (this.nounCountsByType[i] > 0) {
-                    this.nounCountsByType[i]--;
-                }
-                this.nounTypeCache.delete(id);
-                return;
-            }
-            catch (error) {
-                // Not in this type, continue
-            }
-        }
-    }
-    /**
-     * Save verb (type-first path)
-     *
-     * ARCHITECTURAL FIX (v3.50.1): No more caching hack needed!
-     * HNSWVerb now includes verb field, so type is always available
-     */
-    async saveVerb_internal(verb) {
-        // Type is now a first-class field in HNSWVerb - no caching needed!
-        const type = verb.verb;
-        const path = getVerbVectorPath(type, verb.id);
-        // Update type tracking
-        const typeIndex = TypeUtils.getVerbIndex(type);
-        this.verbCountsByType[typeIndex]++;
-        this.verbTypeCache.set(verb.id, type);
-        // COW-aware write (v5.0.1): Use COW helper for branch isolation
-        await this.writeObjectToBranch(path, verb);
-        // Periodically save statistics
-        if (this.verbCountsByType[typeIndex] % 100 === 0) {
-            await this.saveTypeStatistics();
-        }
-    }
-    /**
-     * Get verb (type-first path)
-     *
-     * ARCHITECTURAL FIX (v3.50.1): Cache still useful for performance
-     * Once we know where a verb is, we can retrieve it O(1) instead of searching all types
-     */
-    async getVerb_internal(id) {
-        // Try cache first for O(1) retrieval
-        const cachedType = this.verbTypeCache.get(id);
-        if (cachedType) {
-            const path = getVerbVectorPath(cachedType, id);
-            // COW-aware read (v5.0.1): Use COW helper for branch isolation
-            const verb = await this.readWithInheritance(path);
-            return verb;
-        }
-        // Search across all types (only on first access)
-        for (let i = 0; i < VERB_TYPE_COUNT; i++) {
-            const type = TypeUtils.getVerbFromIndex(i);
-            const path = getVerbVectorPath(type, id);
-            try {
-                // COW-aware read (v5.0.1): Use COW helper for branch isolation
-                const verb = await this.readWithInheritance(path);
-                if (verb) {
-                    // Cache the type for next time (read from verb.verb field)
-                    this.verbTypeCache.set(id, verb.verb);
-                    return verb;
-                }
-            }
-            catch (error) {
-                // Not in this type, continue
-            }
-        }
-        return null;
-    }
-    /**
-     * Get verbs by source
-     */
-    async getVerbsBySource_internal(sourceId) {
-        // v5.0.1 COW FIX: Use getVerbsWithPagination which is COW-aware
-        // Previous v4.8.1 implementation delegated to underlying storage, which bypasses COW!
-        // The underlying storage delegates to GraphAdjacencyIndex, which is shared between forks.
-        // This caused getRelations() to return 0 results for fork-created relationships.
-        //
-        // Now we use getVerbsWithPagination with sourceId filter, which:
-        // - Searches across all verb types using COW-aware listObjectsInBranch()
-        // - Reads verbs using COW-aware readWithInheritance()
-        // - Properly isolates fork data from parent
-        //
-        // Performance: Still efficient because sourceId filter reduces iteration
-        const result = await this.getVerbsWithPagination({
-            limit: 10000, // High limit to get all verbs for this source
-            offset: 0,
-            filter: { sourceId }
-        });
-        return result.items;
-    }
-    /**
-     * Get verbs by target
-     */
-    async getVerbsByTarget_internal(targetId) {
-        // v5.0.1 COW FIX: Use getVerbsWithPagination which is COW-aware
-        // Same fix as getVerbsBySource_internal - delegating to underlying bypasses COW
-        const result = await this.getVerbsWithPagination({
-            limit: 10000, // High limit to get all verbs for this target
-            offset: 0,
-            filter: { targetId }
-        });
-        return result.items;
-    }
-    /**
-     * Get verbs by type (O(1) with type-first paths!)
-     *
-     * v4.0.0: Load verbs and combine with metadata
-     */
-    async getVerbsByType_internal(verbType) {
-        const type = verbType;
-        const prefix = `entities/verbs/${type}/vectors/`;
-        // COW-aware list (v5.0.1): Use COW helper for branch isolation
-        const paths = await this.listObjectsInBranch(prefix);
-        const verbs = [];
-        for (const path of paths) {
-            try {
-                // COW-aware read (v5.0.1): Use COW helper for branch isolation
-                const hnswVerb = await this.readWithInheritance(path);
-                if (!hnswVerb)
-                    continue;
-                // Cache type from HNSWVerb for future O(1) retrievals
-                this.verbTypeCache.set(hnswVerb.id, hnswVerb.verb);
-                // Load metadata separately (optional in v4.0.0!)
-                // FIX: Don't skip verbs without metadata - metadata is optional!
-                const metadata = await this.getVerbMetadata(hnswVerb.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));
-                    }
-                }
-                // 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],
-                    connections: connectionsMap,
-                    verb: hnswVerb.verb,
-                    sourceId: hnswVerb.sourceId,
-                    targetId: hnswVerb.targetId,
-                    createdAt: createdAt || Date.now(),
-                    updatedAt: updatedAt || Date.now(),
-                    confidence: confidence,
-                    weight: weight,
-                    service: service,
-                    data: data,
-                    createdBy,
-                    metadata: customMetadata
-                };
-                verbs.push(verbWithMetadata);
-            }
-            catch (error) {
-                console.warn(`[TypeAwareStorage] Failed to load verb from ${path}:`, error);
-            }
-        }
-        return verbs;
-    }
-    /**
-     * Delete verb (type-first path)
-     */
-    async deleteVerb_internal(id) {
-        // Try cache first
-        const cachedType = this.verbTypeCache.get(id);
-        if (cachedType) {
-            const path = getVerbVectorPath(cachedType, id);
-            // COW-aware delete (v5.0.1): Use COW helper for branch isolation
-            await this.deleteObjectFromBranch(path);
-            const typeIndex = TypeUtils.getVerbIndex(cachedType);
-            if (this.verbCountsByType[typeIndex] > 0) {
-                this.verbCountsByType[typeIndex]--;
-            }
-            this.verbTypeCache.delete(id);
-            return;
-        }
-        // Search across all types
-        for (let i = 0; i < VERB_TYPE_COUNT; i++) {
-            const type = TypeUtils.getVerbFromIndex(i);
-            const path = getVerbVectorPath(type, id);
-            try {
-                // COW-aware delete (v5.0.1): Use COW helper for branch isolation
-                await this.deleteObjectFromBranch(path);
-                if (this.verbCountsByType[i] > 0) {
-                    this.verbCountsByType[i]--;
-                }
-                this.verbTypeCache.delete(id);
-                return;
-            }
-            catch (error) {
-                // Continue
-            }
-        }
-    }
-    /**
-     * Save noun metadata (override to cache type for type-aware routing)
-     *
-     * v4.0.0: Extract and cache noun type when metadata is saved
-     */
-    async saveNounMetadata(id, metadata) {
-        // Extract and cache the type
-        const type = (metadata.noun || 'thing');
-        this.nounTypeCache.set(id, type);
-        // COW-aware write (v5.0.1): Use COW helper for branch isolation
-        const path = getNounMetadataPath(type, id);
-        await this.writeObjectToBranch(path, metadata);
-    }
-    /**
-     * Get noun metadata (override to use type-aware paths)
-     */
-    async getNounMetadata(id) {
-        // Try cache first
-        const cachedType = this.nounTypeCache.get(id);
-        if (cachedType) {
-            const path = getNounMetadataPath(cachedType, id);
-            // COW-aware read (v5.0.1): Use COW helper for branch isolation
-            return await this.readWithInheritance(path);
-        }
-        // Search across all types
-        for (let i = 0; i < NOUN_TYPE_COUNT; i++) {
-            const type = TypeUtils.getNounFromIndex(i);
-            const path = getNounMetadataPath(type, id);
-            try {
-                // COW-aware read (v5.0.1): Use COW helper for branch isolation
-                const metadata = await this.readWithInheritance(path);
-                if (metadata) {
-                    // Cache the type for next time
-                    const metadataType = (metadata.noun || 'thing');
-                    this.nounTypeCache.set(id, metadataType);
-                    return metadata;
-                }
-            }
-            catch (error) {
-                // Not in this type, continue searching
-            }
-        }
-        return null;
-    }
-    /**
-     * Delete noun metadata (override to use type-aware paths)
-     */
-    async deleteNounMetadata(id) {
-        const cachedType = this.nounTypeCache.get(id);
-        if (cachedType) {
-            const path = getNounMetadataPath(cachedType, id);
-            // COW-aware delete (v5.0.1): Use COW helper for branch isolation
-            await this.deleteObjectFromBranch(path);
-            return;
-        }
-        // Search across all types
-        for (let i = 0; i < NOUN_TYPE_COUNT; i++) {
-            const type = TypeUtils.getNounFromIndex(i);
-            const path = getNounMetadataPath(type, id);
-            try {
-                // COW-aware delete (v5.0.1): Use COW helper for branch isolation
-                await this.deleteObjectFromBranch(path);
-                return;
-            }
-            catch (error) {
-                // Not in this type, continue
-            }
-        }
-    }
-    /**
-     * Save verb metadata (override to use type-aware paths)
-     *
-     * Note: Verb type comes from HNSWVerb.verb field, not metadata
-     * We need to read the verb to get the type for path routing
-     */
-    async saveVerbMetadata(id, metadata) {
-        // Get verb type from cache or by reading the verb
-        let type = this.verbTypeCache.get(id);
-        if (!type) {
-            // Need to read the verb to get its type
-            const verb = await this.getVerb_internal(id);
-            if (verb) {
-                type = verb.verb;
-                this.verbTypeCache.set(id, type);
-            }
-            else {
-                type = 'relatedTo';
-            }
-        }
-        // Save to type-aware path
-        const path = getVerbMetadataPath(type, id);
-        // COW-aware write (v5.0.1): Use COW helper for branch isolation
-        await this.writeObjectToBranch(path, metadata);
-    }
-    /**
-     * Get verb metadata (override to use type-aware paths)
-     */
-    async getVerbMetadata(id) {
-        // Try cache first
-        const cachedType = this.verbTypeCache.get(id);
-        if (cachedType) {
-            const path = getVerbMetadataPath(cachedType, id);
-            // COW-aware read (v5.0.1): Use COW helper for branch isolation
-            return await this.readWithInheritance(path);
-        }
-        // Search across all types
-        for (let i = 0; i < VERB_TYPE_COUNT; i++) {
-            const type = TypeUtils.getVerbFromIndex(i);
-            const path = getVerbMetadataPath(type, id);
-            try {
-                // COW-aware read (v5.0.1): Use COW helper for branch isolation
-                const metadata = await this.readWithInheritance(path);
-                if (metadata) {
-                    // Cache the type for next time
-                    this.verbTypeCache.set(id, type);
-                    return metadata;
-                }
-            }
-            catch (error) {
-                // Not in this type, continue
-            }
-        }
-        return null;
-    }
-    /**
-     * Delete verb metadata (override to use type-aware paths)
-     */
-    async deleteVerbMetadata(id) {
-        const cachedType = this.verbTypeCache.get(id);
-        if (cachedType) {
-            const path = getVerbMetadataPath(cachedType, id);
-            // COW-aware delete (v5.0.1): Use COW helper for branch isolation
-            await this.deleteObjectFromBranch(path);
-            return;
-        }
-        // Search across all types
-        for (let i = 0; i < VERB_TYPE_COUNT; i++) {
-            const type = TypeUtils.getVerbFromIndex(i);
-            const path = getVerbMetadataPath(type, id);
-            try {
-                // COW-aware delete (v5.0.1): Use COW helper for branch isolation
-                await this.deleteObjectFromBranch(path);
-                return;
-            }
-            catch (error) {
-                // Not in this type, continue
-            }
-        }
-    }
-    /**
-     * Write object to path (delegate to underlying storage)
-     */
-    async writeObjectToPath(path, data) {
-        return this.u.writeObjectToPath(path, data);
-    }
-    /**
-     * Read object from path (delegate to underlying storage)
-     */
-    async readObjectFromPath(path) {
-        return this.u.readObjectFromPath(path);
-    }
-    /**
-     * Delete object from path (delegate to underlying storage)
-     */
-    async deleteObjectFromPath(path) {
-        return this.u.deleteObjectFromPath(path);
-    }
-    /**
-     * List objects under path (delegate to underlying storage)
-     */
-    async listObjectsUnderPath(prefix) {
-        return this.u.listObjectsUnderPath(prefix);
-    }
-    /**
-     * Save statistics data
-     */
-    async saveStatisticsData(statistics) {
-        return this.u.writeObjectToPath(`${SYSTEM_DIR}/statistics.json`, statistics);
-    }
-    /**
-     * Get statistics data
-     */
-    async getStatisticsData() {
-        return this.u.readObjectFromPath(`${SYSTEM_DIR}/statistics.json`);
-    }
-    /**
-     * Clear all data
-     */
-    async clear() {
-        // Clear type tracking
-        this.nounCountsByType.fill(0);
-        this.verbCountsByType.fill(0);
-        this.nounTypeCache.clear();
-        this.verbTypeCache.clear();
-        // Delegate to underlying storage
-        if (typeof this.underlying.clear === 'function') {
-            await this.underlying.clear();
-        }
-    }
-    /**
-     * Get storage status
-     */
-    async getStorageStatus() {
-        const underlyingStatus = await this.underlying.getStorageStatus();
-        return {
-            ...underlyingStatus,
-            type: 'type-aware',
-            details: {
-                ...underlyingStatus.details,
-                typeTracking: {
-                    nounTypes: NOUN_TYPE_COUNT,
-                    verbTypes: VERB_TYPE_COUNT,
-                    memoryBytes: 284, // 124 + 160
-                    nounCounts: Array.from(this.nounCountsByType),
-                    verbCounts: Array.from(this.verbCountsByType),
-                    cacheSize: this.nounTypeCache.size + this.verbTypeCache.size
-                }
-            }
-        };
-    }
-    /**
-     * Initialize counts from storage
-     */
-    async initializeCounts() {
-        // TypeAwareStorageAdapter maintains its own type-based counts
-        // which are loaded in loadTypeStatistics()
-        // But we should also initialize the underlying storage's counts
-        if (this.u.initializeCounts) {
-            await this.u.initializeCounts();
-        }
-    }
-    /**
-     * Persist counts to storage
-     */
-    async persistCounts() {
-        // Persist our type statistics
-        await this.saveTypeStatistics();
-        // Also persist underlying storage counts
-        if (this.u.persistCounts) {
-            await this.u.persistCounts();
-        }
-    }
-    /**
-     * Get noun vector (delegate to underlying storage)
-     */
-    async getNounVector(id) {
-        const noun = await this.getNoun_internal(id);
-        return noun?.vector || null;
-    }
-    /**
-     * Save HNSW data for a noun
-     */
-    async saveHNSWData(nounId, hnswData) {
-        // Get noun type for type-first path
-        const cachedType = this.nounTypeCache.get(nounId);
-        const type = cachedType || 'thing'; // Default if not cached
-        const shard = getShardIdFromUuid(nounId);
-        const path = `entities/nouns/${type}/hnsw/${shard}/${nounId}.json`;
-        await this.u.writeObjectToPath(path, hnswData);
-    }
-    /**
-     * Get HNSW data for a noun
-     */
-    async getHNSWData(nounId) {
-        // Try cache first
-        const cachedType = this.nounTypeCache.get(nounId);
-        if (cachedType) {
-            const shard = getShardIdFromUuid(nounId);
-            const path = `entities/nouns/${cachedType}/hnsw/${shard}/${nounId}.json`;
-            return await this.u.readObjectFromPath(path);
-        }
-        // Search across all types
-        for (let i = 0; i < NOUN_TYPE_COUNT; i++) {
-            const type = TypeUtils.getNounFromIndex(i);
-            const shard = getShardIdFromUuid(nounId);
-            const path = `entities/nouns/${type}/hnsw/${shard}/${nounId}.json`;
-            try {
-                const data = await this.u.readObjectFromPath(path);
-                if (data) {
-                    return data;
-                }
-            }
-            catch (error) {
-                // Not in this type, continue
-            }
-        }
-        return null;
-    }
-    /**
-     * Get nouns with pagination (v5.0.1: COW-aware)
-     * Required for find() to work with TypeAwareStorage
-     */
-    async getNounsWithPagination(options) {
-        const limit = options.limit || 100;
-        const offset = options.offset || 0;
-        const filter = options.filter || {};
-        // Determine which types to search
-        let typesToSearch;
-        if (filter.nounType) {
-            typesToSearch = Array.isArray(filter.nounType) ? filter.nounType : [filter.nounType];
-        }
-        else {
-            // Search all 31 types
-            typesToSearch = [];
-            for (let i = 0; i < NOUN_TYPE_COUNT; i++) {
-                const type = TypeUtils.getNounFromIndex(i);
-                typesToSearch.push(type);
-            }
-        }
-        // Collect all matching nouns across types (COW-aware!)
-        const allNouns = [];
-        for (const type of typesToSearch) {
-            const prefix = `entities/nouns/${type}/vectors/`;
-            // COW-aware list with inheritance (v5.0.1): Fork sees parent's nouns too!
-            const paths = await this.listObjectsWithInheritance(prefix);
-            for (const path of paths) {
-                try {
-                    // COW-aware read with inheritance
-                    const noun = await this.readWithInheritance(path);
-                    if (!noun)
-                        continue;
-                    // Get metadata separately
-                    const metadata = await this.getNounMetadata(noun.id);
-                    if (!metadata)
-                        continue;
-                    // Filter by service if specified
-                    if (filter.service && metadata.service !== filter.service)
-                        continue;
-                    // Filter by custom metadata if specified
-                    if (filter.metadata) {
-                        let matches = true;
-                        for (const [key, value] of Object.entries(filter.metadata)) {
-                            if (metadata[key] !== value) {
-                                matches = false;
-                                break;
-                            }
-                        }
-                        if (!matches)
-                            continue;
-                    }
-                    // Extract standard fields from metadata
-                    const { noun: nounType, createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadata;
-                    // Create HNSWNounWithMetadata (v4.8.0 format)
-                    const nounWithMetadata = {
-                        id: noun.id,
-                        vector: noun.vector,
-                        connections: noun.connections,
-                        level: noun.level || 0,
-                        type: nounType || NounType.Thing,
-                        createdAt: createdAt || Date.now(),
-                        updatedAt: updatedAt || Date.now(),
-                        confidence,
-                        weight,
-                        service,
-                        data,
-                        createdBy,
-                        metadata: customMetadata
-                    };
-                    allNouns.push(nounWithMetadata);
-                }
-                catch (error) {
-                    // Skip entities with errors
-                    continue;
-                }
-            }
-        }
-        // Apply pagination
-        const totalCount = allNouns.length;
-        const paginatedNouns = allNouns.slice(offset, offset + limit);
-        const hasMore = offset + limit < totalCount;
-        // Generate cursor if more results exist
-        let nextCursor;
-        if (hasMore && paginatedNouns.length > 0) {
-            nextCursor = paginatedNouns[paginatedNouns.length - 1].id;
-        }
-        return {
-            items: paginatedNouns,
-            totalCount,
-            hasMore,
-            nextCursor
-        };
-    }
-    /**
-     * Get verbs with pagination (v5.0.1: COW-aware)
-     * Required for GraphAdjacencyIndex rebuild and find() to work
-     */
-    async getVerbsWithPagination(options) {
-        const limit = options.limit || 100;
-        const offset = options.offset || 0;
-        const filter = options.filter || {};
-        // Determine which types to search
-        let typesToSearch;
-        if (filter.verbType) {
-            typesToSearch = Array.isArray(filter.verbType) ? filter.verbType : [filter.verbType];
-        }
-        else {
-            // Search all 40 verb types
-            typesToSearch = [];
-            for (let i = 0; i < VERB_TYPE_COUNT; i++) {
-                const type = TypeUtils.getVerbFromIndex(i);
-                typesToSearch.push(type);
-            }
-        }
-        // Collect all matching verbs across types (COW-aware!)
-        const allVerbs = [];
-        for (const type of typesToSearch) {
-            const prefix = `entities/verbs/${type}/vectors/`;
-            // COW-aware list with inheritance (v5.0.1): Fork sees parent's verbs too!
-            const paths = await this.listObjectsWithInheritance(prefix);
-            for (const path of paths) {
-                try {
-                    // COW-aware read with inheritance
-                    const verb = await this.readWithInheritance(path);
-                    if (!verb)
-                        continue;
-                    // Filter by sourceId if specified
-                    if (filter.sourceId) {
-                        const sourceIds = Array.isArray(filter.sourceId) ? filter.sourceId : [filter.sourceId];
-                        if (!sourceIds.includes(verb.sourceId))
-                            continue;
-                    }
-                    // Filter by targetId if specified
-                    if (filter.targetId) {
-                        const targetIds = Array.isArray(filter.targetId) ? filter.targetId : [filter.targetId];
-                        if (!targetIds.includes(verb.targetId))
-                            continue;
-                    }
-                    // Get metadata separately
-                    const metadata = await this.getVerbMetadata(verb.id);
-                    // Filter by service if specified
-                    if (filter.service && metadata && metadata.service !== filter.service)
-                        continue;
-                    // Filter by custom metadata if specified
-                    if (filter.metadata && metadata) {
-                        let matches = true;
-                        for (const [key, value] of Object.entries(filter.metadata)) {
-                            if (metadata[key] !== value) {
-                                matches = false;
-                                break;
-                            }
-                        }
-                        if (!matches)
-                            continue;
-                    }
-                    // Extract standard fields from metadata
-                    const metadataObj = metadata || {};
-                    const { createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataObj;
-                    // Create HNSWVerbWithMetadata (v4.8.0 format)
-                    const verbWithMetadata = {
-                        id: verb.id,
-                        vector: verb.vector,
-                        connections: verb.connections,
-                        verb: verb.verb,
-                        sourceId: verb.sourceId,
-                        targetId: verb.targetId,
-                        createdAt: createdAt || Date.now(),
-                        updatedAt: updatedAt || Date.now(),
-                        confidence,
-                        weight,
-                        service,
-                        data,
-                        createdBy,
-                        metadata: customMetadata
-                    };
-                    allVerbs.push(verbWithMetadata);
-                }
-                catch (error) {
-                    // Skip verbs with errors
-                    continue;
-                }
-            }
-        }
-        // Apply pagination
-        const totalCount = allVerbs.length;
-        const paginatedVerbs = allVerbs.slice(offset, offset + limit);
-        const hasMore = offset + limit < totalCount;
-        // Generate cursor if more results exist
-        let nextCursor;
-        if (hasMore && paginatedVerbs.length > 0) {
-            nextCursor = paginatedVerbs[paginatedVerbs.length - 1].id;
-        }
-        return {
-            items: paginatedVerbs,
-            totalCount,
-            hasMore,
-            nextCursor
-        };
-    }
-    /**
-     * Save HNSW system data (entry point, max level)
-     */
-    async saveHNSWSystem(systemData) {
-        await this.u.writeObjectToPath(`${SYSTEM_DIR}/hnsw-system.json`, systemData);
-    }
-    /**
-     * Get HNSW system data
-     */
-    async getHNSWSystem() {
-        return await this.u.readObjectFromPath(`${SYSTEM_DIR}/hnsw-system.json`);
-    }
-    /**
-     * Get type statistics
-     * Useful for analytics and optimization
-     */
-    getTypeStatistics() {
-        const nouns = [];
-        for (let i = 0; i < NOUN_TYPE_COUNT; i++) {
-            const count = this.nounCountsByType[i];
-            if (count > 0) {
-                nouns.push({ type: TypeUtils.getNounFromIndex(i), count });
-            }
-        }
-        const verbs = [];
-        for (let i = 0; i < VERB_TYPE_COUNT; i++) {
-            const count = this.verbCountsByType[i];
-            if (count > 0) {
-                verbs.push({ type: TypeUtils.getVerbFromIndex(i), count });
-            }
-        }
-        return {
-            nouns: nouns.sort((a, b) => b.count - a.count),
-            verbs: verbs.sort((a, b) => b.count - a.count),
-            totalMemory: 284 // bytes
-        };
-    }
-}
-//# sourceMappingURL=typeAwareStorageAdapter.js.map