@soulcraft/brainy 3.17.0 → 3.19.0

package/dist/vfs/semantic/SemanticPathResolver.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Semantic Path Resolver
+ *
+ * Unified path resolver that handles BOTH:
+ * - Traditional hierarchical paths (/src/auth/login.ts)
+ * - Semantic projection paths (/by-concept/authentication/...)
+ *
+ * Uses EXISTING infrastructure:
+ * - PathResolver for traditional paths
+ * - ProjectionRegistry for semantic dimensions
+ * - SemanticPathParser for path type detection
+ */
+import { Brainy } from '../../brainy.js';
+import { VirtualFileSystem } from '../VirtualFileSystem.js';
+import { VFSEntity } from '../types.js';
+import { ProjectionRegistry } from './ProjectionRegistry.js';
+/**
+ * Semantic Path Resolver
+ * Handles both traditional and semantic paths transparently
+ *
+ * Uses Brainy's UnifiedCache for optimal memory management and performance
+ */
+export declare class SemanticPathResolver {
+    private brain;
+    private vfs;
+    private pathResolver;
+    private parser;
+    private registry;
+    private cache;
+    constructor(brain: Brainy, vfs: VirtualFileSystem, rootEntityId: string, registry: ProjectionRegistry);
+    /**
+     * Resolve a path to entity ID(s)
+     * Handles BOTH traditional and semantic paths
+     *
+     * For traditional paths: Returns single entity ID
+     * For semantic paths: Returns first matching entity ID
+     *
+     * Uses UnifiedCache with request coalescing to prevent stampede
+     *
+     * @param path - Path to resolve (traditional or semantic)
+     * @param options - Resolution options
+     * @returns Entity ID
+     */
+    resolve(path: string, options?: {
+        followSymlinks?: boolean;
+        cache?: boolean;
+    }): Promise<string>;
+    /**
+     * Resolve semantic path to multiple entity IDs
+     * This is the polymorphic resolution that returns ALL matches
+     *
+     * Uses UnifiedCache for performance
+     *
+     * @param path - Semantic path
+     * @param options - Resolution options
+     * @returns Array of entity IDs
+     */
+    resolveAll(path: string, options?: {
+        cache?: boolean;
+        limit?: number;
+    }): Promise<string[]>;
+    /**
+     * Internal semantic path resolution (called by cache)
+     * Estimates cost and size for UnifiedCache optimization
+     */
+    private resolveSemanticPathInternal;
+    /**
+     * Filter entity IDs by subpath (filename or partial path)
+     */
+    private filterBySubpath;
+    /**
+     * Get children of a directory
+     * Delegates to PathResolver for traditional directories
+     * For semantic paths, returns entities in that dimension
+     */
+    getChildren(dirIdOrPath: string): Promise<VFSEntity[]>;
+    /**
+     * List entities in a semantic dimension
+     */
+    private listSemanticDimension;
+    /**
+     * Create a path mapping (cache a path resolution)
+     * Only applies to traditional paths
+     */
+    createPath(path: string, entityId: string): Promise<void>;
+    /**
+     * Invalidate path cache
+     */
+    invalidatePath(path: string, recursive?: boolean): void;
+    /**
+     * Clear all semantic caches
+     * Uses UnifiedCache's clear method
+     */
+    invalidateSemanticCache(): void;
+    /**
+     * Cleanup resources
+     */
+    cleanup(): void;
+}

package/dist/vfs/semantic/SemanticPathResolver.js

@@ -0,0 +1,242 @@
+/**
+ * Semantic Path Resolver
+ *
+ * Unified path resolver that handles BOTH:
+ * - Traditional hierarchical paths (/src/auth/login.ts)
+ * - Semantic projection paths (/by-concept/authentication/...)
+ *
+ * Uses EXISTING infrastructure:
+ * - PathResolver for traditional paths
+ * - ProjectionRegistry for semantic dimensions
+ * - SemanticPathParser for path type detection
+ */
+import { PathResolver } from '../PathResolver.js';
+import { VFSError, VFSErrorCode } from '../types.js';
+import { SemanticPathParser } from './SemanticPathParser.js';
+import { UnifiedCache } from '../../utils/unifiedCache.js';
+/**
+ * Semantic Path Resolver
+ * Handles both traditional and semantic paths transparently
+ *
+ * Uses Brainy's UnifiedCache for optimal memory management and performance
+ */
+export class SemanticPathResolver {
+    constructor(brain, vfs, rootEntityId, registry) {
+        this.brain = brain;
+        this.vfs = vfs;
+        this.registry = registry;
+        this.parser = new SemanticPathParser();
+        // Use Brainy's UnifiedCache for semantic path caching
+        // Zero-config: Uses 2GB default from UnifiedCache
+        this.cache = new UnifiedCache({
+            enableRequestCoalescing: true,
+            enableFairnessCheck: true
+        });
+        // Create traditional path resolver (uses its own optimized cache with defaults)
+        this.pathResolver = new PathResolver(brain, rootEntityId);
+    }
+    /**
+     * Resolve a path to entity ID(s)
+     * Handles BOTH traditional and semantic paths
+     *
+     * For traditional paths: Returns single entity ID
+     * For semantic paths: Returns first matching entity ID
+     *
+     * Uses UnifiedCache with request coalescing to prevent stampede
+     *
+     * @param path - Path to resolve (traditional or semantic)
+     * @param options - Resolution options
+     * @returns Entity ID
+     */
+    async resolve(path, options) {
+        // Parse the path to determine dimension
+        const parsed = this.parser.parse(path);
+        // Handle based on path dimension
+        if (parsed.dimension === 'traditional') {
+            // Use existing PathResolver for traditional paths
+            return await this.pathResolver.resolve(path, options);
+        }
+        // Semantic path - use UnifiedCache with request coalescing
+        const cacheKey = `semantic:${path}`;
+        if (options?.cache === false) {
+            // Skip cache if requested
+            const entityIds = await this.resolveSemanticPathInternal(parsed);
+            if (entityIds.length === 0) {
+                throw new VFSError(VFSErrorCode.ENOENT, `No entities found for semantic path: ${path}`, path, 'resolve');
+            }
+            return entityIds[0];
+        }
+        // Use UnifiedCache - automatically handles stampede prevention
+        const entityIds = await this.cache.get(cacheKey, async () => {
+            return await this.resolveSemanticPathInternal(parsed);
+        });
+        if (!entityIds || entityIds.length === 0) {
+            throw new VFSError(VFSErrorCode.ENOENT, `No entities found for semantic path: ${path}`, path, 'resolve');
+        }
+        return entityIds[0];
+    }
+    /**
+     * Resolve semantic path to multiple entity IDs
+     * This is the polymorphic resolution that returns ALL matches
+     *
+     * Uses UnifiedCache for performance
+     *
+     * @param path - Semantic path
+     * @param options - Resolution options
+     * @returns Array of entity IDs
+     */
+    async resolveAll(path, options) {
+        const parsed = this.parser.parse(path);
+        if (parsed.dimension === 'traditional') {
+            // Traditional paths resolve to single entity
+            const id = await this.pathResolver.resolve(path, options);
+            return [id];
+        }
+        // Use cache if enabled
+        const cacheKey = `semantic:${path}`;
+        if (options?.cache === false) {
+            return await this.resolveSemanticPathInternal(parsed, options?.limit);
+        }
+        // UnifiedCache with automatic stampede prevention
+        return await this.cache.get(cacheKey, async () => {
+            return await this.resolveSemanticPathInternal(parsed, options?.limit);
+        });
+    }
+    /**
+     * Internal semantic path resolution (called by cache)
+     * Estimates cost and size for UnifiedCache optimization
+     */
+    async resolveSemanticPathInternal(parsed, limit) {
+        // Resolve based on dimension
+        let entityIds = [];
+        switch (parsed.dimension) {
+            case 'concept':
+                entityIds = await this.registry.resolve('concept', parsed.value, this.brain, this.vfs);
+                break;
+            case 'author':
+                entityIds = await this.registry.resolve('author', parsed.value, this.brain, this.vfs);
+                break;
+            case 'time':
+                entityIds = await this.registry.resolve('time', parsed.value, this.brain, this.vfs);
+                break;
+            case 'relationship':
+                entityIds = await this.registry.resolve('relationship', parsed.value, this.brain, this.vfs);
+                break;
+            case 'similar':
+                entityIds = await this.registry.resolve('similar', parsed.value, this.brain, this.vfs);
+                break;
+            case 'tag':
+                // Tags use metadata filtering (concept-like)
+                entityIds = await this.registry.resolve('tag', parsed.value, this.brain, this.vfs);
+                break;
+            case 'traditional':
+                // Shouldn't reach here, but handle it gracefully
+                return [];
+            default:
+                throw new VFSError(VFSErrorCode.ENOTDIR, // Use existing error code
+                `Unsupported semantic path dimension: ${parsed.dimension}`, '', 'resolve');
+        }
+        // Apply subpath filter if specified
+        if (parsed.subpath) {
+            entityIds = await this.filterBySubpath(entityIds, parsed.subpath);
+        }
+        // Apply limit
+        if (limit && limit > 0) {
+            entityIds = entityIds.slice(0, limit);
+        }
+        // Result will be cached by UnifiedCache.get() automatically
+        return entityIds;
+    }
+    /**
+     * Filter entity IDs by subpath (filename or partial path)
+     */
+    async filterBySubpath(entityIds, subpath) {
+        const filtered = [];
+        for (const id of entityIds) {
+            const entity = await this.brain.get(id);
+            if (!entity)
+                continue;
+            const name = entity.metadata?.name;
+            const path = entity.metadata?.path;
+            // Check if name or path matches subpath
+            if (name === subpath || path?.endsWith(subpath)) {
+                filtered.push(id);
+            }
+        }
+        return filtered;
+    }
+    /**
+     * Get children of a directory
+     * Delegates to PathResolver for traditional directories
+     * For semantic paths, returns entities in that dimension
+     */
+    async getChildren(dirIdOrPath) {
+        // If it looks like a path, parse it
+        if (dirIdOrPath.startsWith('/')) {
+            const parsed = this.parser.parse(dirIdOrPath);
+            if (parsed.dimension !== 'traditional') {
+                // For semantic paths, list entities in that dimension
+                return await this.listSemanticDimension(parsed);
+            }
+        }
+        // Traditional directory - use PathResolver
+        return await this.pathResolver.getChildren(dirIdOrPath);
+    }
+    /**
+     * List entities in a semantic dimension
+     */
+    async listSemanticDimension(parsed) {
+        switch (parsed.dimension) {
+            case 'concept':
+                return await this.registry.list('concept', this.brain, this.vfs);
+            case 'author':
+                return await this.registry.list('author', this.brain, this.vfs);
+            case 'time':
+                return await this.registry.list('time', this.brain, this.vfs);
+            case 'tag':
+                return await this.registry.list('tag', this.brain, this.vfs);
+            default:
+                return [];
+        }
+    }
+    /**
+     * Create a path mapping (cache a path resolution)
+     * Only applies to traditional paths
+     */
+    async createPath(path, entityId) {
+        const parsed = this.parser.parse(path);
+        if (parsed.dimension === 'traditional') {
+            await this.pathResolver.createPath(path, entityId);
+        }
+        // Semantic paths are not cached via createPath
+    }
+    /**
+     * Invalidate path cache
+     */
+    invalidatePath(path, recursive = false) {
+        const parsed = this.parser.parse(path);
+        if (parsed.dimension === 'traditional') {
+            this.pathResolver.invalidatePath(path, recursive);
+        }
+        else {
+            // Invalidate semantic cache via UnifiedCache
+            const cacheKey = `semantic:${path}`;
+            this.cache.delete(cacheKey);
+        }
+    }
+    /**
+     * Clear all semantic caches
+     * Uses UnifiedCache's clear method
+     */
+    invalidateSemanticCache() {
+        this.cache.clear();
+    }
+    /**
+     * Cleanup resources
+     */
+    cleanup() {
+        this.pathResolver.cleanup();
+        this.cache.clear();
+    }
+}
+//# sourceMappingURL=SemanticPathResolver.js.map

package/dist/vfs/semantic/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Semantic VFS - Index
+ *
+ * Central export point for all semantic VFS components
+ */
+export { SemanticPathParser } from './SemanticPathParser.js';
+export type { SemanticDimension, ParsedSemanticPath, RelationshipValue, SimilarityValue } from './SemanticPathParser.js';
+export { ProjectionRegistry } from './ProjectionRegistry.js';
+export type { ProjectionStrategy } from './ProjectionStrategy.js';
+export { BaseProjectionStrategy } from './ProjectionStrategy.js';
+export { SemanticPathResolver } from './SemanticPathResolver.js';
+export { ConceptProjection } from './projections/ConceptProjection.js';
+export { AuthorProjection } from './projections/AuthorProjection.js';
+export { TemporalProjection } from './projections/TemporalProjection.js';
+export { RelationshipProjection } from './projections/RelationshipProjection.js';
+export { SimilarityProjection } from './projections/SimilarityProjection.js';
+export { TagProjection } from './projections/TagProjection.js';

package/dist/vfs/semantic/index.js

@@ -0,0 +1,18 @@
+/**
+ * Semantic VFS - Index
+ *
+ * Central export point for all semantic VFS components
+ */
+// Core components
+export { SemanticPathParser } from './SemanticPathParser.js';
+export { ProjectionRegistry } from './ProjectionRegistry.js';
+export { BaseProjectionStrategy } from './ProjectionStrategy.js';
+export { SemanticPathResolver } from './SemanticPathResolver.js';
+// Built-in projections
+export { ConceptProjection } from './projections/ConceptProjection.js';
+export { AuthorProjection } from './projections/AuthorProjection.js';
+export { TemporalProjection } from './projections/TemporalProjection.js';
+export { RelationshipProjection } from './projections/RelationshipProjection.js';
+export { SimilarityProjection } from './projections/SimilarityProjection.js';
+export { TagProjection } from './projections/TagProjection.js';
+//# sourceMappingURL=index.js.map

package/dist/vfs/semantic/projections/AuthorProjection.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Author Projection Strategy
+ *
+ * Maps author-based paths to files owned by that author
+ * Uses EXISTING MetadataIndexManager for O(log n) queries
+ */
+import { Brainy } from '../../../brainy.js';
+import { VirtualFileSystem } from '../../VirtualFileSystem.js';
+import { FindParams } from '../../../types/brainy.types.js';
+import { BaseProjectionStrategy } from '../ProjectionStrategy.js';
+import { VFSEntity } from '../../types.js';
+/**
+ * Author Projection: /by-author/<authorName>/<subpath>
+ *
+ * Uses EXISTING infrastructure:
+ * - Brainy.find() with metadata filters (REAL)
+ * - MetadataIndexManager for O(log n) owner queries (REAL)
+ * - VFSMetadata.owner field (REAL - types.ts line 44)
+ */
+export declare class AuthorProjection extends BaseProjectionStrategy {
+    readonly name = "author";
+    /**
+     * Convert author name to Brainy FindParams
+     */
+    toQuery(authorName: string, subpath?: string): FindParams;
+    /**
+     * Resolve author to entity IDs using REAL Brainy.find()
+     */
+    resolve(brain: Brainy, vfs: VirtualFileSystem, authorName: string): Promise<string[]>;
+    /**
+     * List all unique authors
+     * Uses aggregation over metadata
+     */
+    list(brain: Brainy, vfs: VirtualFileSystem, limit?: number): Promise<VFSEntity[]>;
+}

package/dist/vfs/semantic/projections/AuthorProjection.js

@@ -0,0 +1,74 @@
+/**
+ * Author Projection Strategy
+ *
+ * Maps author-based paths to files owned by that author
+ * Uses EXISTING MetadataIndexManager for O(log n) queries
+ */
+import { BaseProjectionStrategy } from '../ProjectionStrategy.js';
+/**
+ * Author Projection: /by-author/<authorName>/<subpath>
+ *
+ * Uses EXISTING infrastructure:
+ * - Brainy.find() with metadata filters (REAL)
+ * - MetadataIndexManager for O(log n) owner queries (REAL)
+ * - VFSMetadata.owner field (REAL - types.ts line 44)
+ */
+export class AuthorProjection extends BaseProjectionStrategy {
+    constructor() {
+        super(...arguments);
+        this.name = 'author';
+    }
+    /**
+     * Convert author name to Brainy FindParams
+     */
+    toQuery(authorName, subpath) {
+        const query = {
+            where: {
+                vfsType: 'file',
+                owner: authorName
+            },
+            limit: 1000
+        };
+        // Filter by filename if subpath specified
+        if (subpath) {
+            query.where = {
+                ...query.where,
+                anyOf: [
+                    { name: subpath },
+                    { path: { endsWith: subpath } } // BFO operator (not $regex)
+                ]
+            };
+        }
+        return query;
+    }
+    /**
+     * Resolve author to entity IDs using REAL Brainy.find()
+     */
+    async resolve(brain, vfs, authorName) {
+        // Use REAL Brainy metadata filtering
+        const results = await brain.find({
+            where: {
+                vfsType: 'file',
+                owner: authorName
+            },
+            limit: 1000
+        });
+        return this.extractIds(results);
+    }
+    /**
+     * List all unique authors
+     * Uses aggregation over metadata
+     */
+    async list(brain, vfs, limit = 100) {
+        // Get all files with owner metadata
+        const results = await brain.find({
+            where: {
+                vfsType: 'file',
+                owner: { $exists: true }
+            },
+            limit
+        });
+        return results.map(r => r.entity);
+    }
+}
+//# sourceMappingURL=AuthorProjection.js.map

package/dist/vfs/semantic/projections/ConceptProjection.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Concept Projection Strategy
+ *
+ * Maps concept-based paths to files containing those concepts
+ * Uses EXISTING ConceptSystem and MetadataIndexManager
+ */
+import { Brainy } from '../../../brainy.js';
+import { VirtualFileSystem } from '../../VirtualFileSystem.js';
+import { FindParams } from '../../../types/brainy.types.js';
+import { BaseProjectionStrategy } from '../ProjectionStrategy.js';
+import { VFSEntity } from '../../types.js';
+/**
+ * Concept Projection: /by-concept/<conceptName>/<subpath>
+ *
+ * Uses EXISTING infrastructure:
+ * - Brainy.find() with metadata filters (REAL - line 580 in brainy.ts)
+ * - MetadataIndexManager for O(log n) concept queries (REAL)
+ * - ConceptSystem for concept extraction (REAL - ConceptSystem.ts)
+ */
+export declare class ConceptProjection extends BaseProjectionStrategy {
+    readonly name = "concept";
+    /**
+     * Convert concept name to Brainy FindParams
+     * Uses EXISTING FindParams.where for metadata filtering
+     *
+     * Now uses flattened conceptNames array for O(log n) performance!
+     */
+    toQuery(conceptName: string, subpath?: string): FindParams;
+    /**
+     * Resolve concept to entity IDs using REAL Brainy.find()
+     * VERIFIED: brain.find() exists at line 580 in brainy.ts
+     *
+     * NOW OPTIMIZED: Uses flattened conceptNames for O(log n) indexed queries!
+     * No more post-filtering - direct index lookup
+     */
+    resolve(brain: Brainy, vfs: VirtualFileSystem, conceptName: string): Promise<string[]>;
+    /**
+     * List all files with concept metadata
+     * Uses REAL Brainy.find() with metadata filter
+     */
+    list(brain: Brainy, vfs: VirtualFileSystem, limit?: number): Promise<VFSEntity[]>;
+}

package/dist/vfs/semantic/projections/ConceptProjection.js

@@ -0,0 +1,87 @@
+/**
+ * Concept Projection Strategy
+ *
+ * Maps concept-based paths to files containing those concepts
+ * Uses EXISTING ConceptSystem and MetadataIndexManager
+ */
+import { BaseProjectionStrategy } from '../ProjectionStrategy.js';
+/**
+ * Concept Projection: /by-concept/<conceptName>/<subpath>
+ *
+ * Uses EXISTING infrastructure:
+ * - Brainy.find() with metadata filters (REAL - line 580 in brainy.ts)
+ * - MetadataIndexManager for O(log n) concept queries (REAL)
+ * - ConceptSystem for concept extraction (REAL - ConceptSystem.ts)
+ */
+export class ConceptProjection extends BaseProjectionStrategy {
+    constructor() {
+        super(...arguments);
+        this.name = 'concept';
+    }
+    /**
+     * Convert concept name to Brainy FindParams
+     * Uses EXISTING FindParams.where for metadata filtering
+     *
+     * Now uses flattened conceptNames array for O(log n) performance!
+     */
+    toQuery(conceptName, subpath) {
+        const query = {
+            where: {
+                vfsType: 'file',
+                conceptNames: { contains: conceptName } // O(log n) indexed query
+            },
+            limit: 1000
+        };
+        // If subpath specified, also filter by filename
+        if (subpath) {
+            query.where = {
+                ...query.where,
+                anyOf: [
+                    { name: subpath },
+                    { path: { endsWith: subpath } } // BFO operator
+                ]
+            };
+        }
+        return query;
+    }
+    /**
+     * Resolve concept to entity IDs using REAL Brainy.find()
+     * VERIFIED: brain.find() exists at line 580 in brainy.ts
+     *
+     * NOW OPTIMIZED: Uses flattened conceptNames for O(log n) indexed queries!
+     * No more post-filtering - direct index lookup
+     */
+    async resolve(brain, vfs, conceptName) {
+        // Verify brain.find is a function (safety check)
+        if (typeof brain.find !== 'function') {
+            throw new Error('VERIFICATION FAILED: brain.find is not a function');
+        }
+        // Direct O(log n) query using flattened conceptNames array
+        // VFS automatically flattens concepts to conceptNames on write
+        const results = await brain.find({
+            where: {
+                vfsType: 'file',
+                conceptNames: { contains: conceptName } // Indexed array query
+            },
+            limit: 1000
+        });
+        return this.extractIds(results);
+    }
+    /**
+     * List all files with concept metadata
+     * Uses REAL Brainy.find() with metadata filter
+     */
+    async list(brain, vfs, limit = 100) {
+        const results = await brain.find({
+            where: {
+                vfsType: 'file',
+                conceptNames: { exists: true } // Use flattened field
+            },
+            limit
+        });
+        // Convert to VFSEntity array
+        // VERIFIED: Result.entity exists in brainy.types.ts
+        return results.map(r => r.entity);
+    }
+}
+//# sourceMappingURL=ConceptProjection.js.map

package/dist/vfs/semantic/projections/RelationshipProjection.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Relationship Projection Strategy
+ *
+ * Maps relationship-based paths to files connected in the knowledge graph
+ * Uses EXISTING GraphAdjacencyIndex for O(1) traversal
+ */
+import { Brainy } from '../../../brainy.js';
+import { VirtualFileSystem } from '../../VirtualFileSystem.js';
+import { FindParams } from '../../../types/brainy.types.js';
+import { BaseProjectionStrategy } from '../ProjectionStrategy.js';
+import { RelationshipValue } from '../SemanticPathParser.js';
+/**
+ * Relationship Projection: /related-to/<path>/depth-N/types-X,Y
+ *
+ * Uses EXISTING infrastructure:
+ * - Brainy.getRelations() for graph traversal (REAL - line 803 in brainy.ts)
+ * - GraphAdjacencyIndex for O(1) neighbor lookups (REAL)
+ * - VerbType enum for relationship types (REAL - graphTypes.ts)
+ */
+export declare class RelationshipProjection extends BaseProjectionStrategy {
+    readonly name = "relationship";
+    /**
+     * Convert relationship value to Brainy FindParams
+     * Note: Graph queries don't use FindParams, but we provide this for consistency
+     */
+    toQuery(value: RelationshipValue, subpath?: string): FindParams;
+    /**
+     * Resolve relationships using REAL Brainy.getRelations()
+     * Uses GraphAdjacencyIndex for O(1) graph traversal
+     */
+    resolve(brain: Brainy, vfs: VirtualFileSystem, value: RelationshipValue): Promise<string[]>;
+    /**
+     * Recursive graph traversal using REAL Brainy.getRelations()
+     */
+    private traverseRelationships;
+    /**
+     * Resolve path to entity ID
+     * Helper to convert traditional path to entity ID
+     */
+    private resolvePathToId;
+}