@soulcraft/brainy 3.17.0 → 3.19.0

package/dist/vfs/index.js

@@ -15,12 +15,6 @@ export { DirectoryImporter } from './importers/DirectoryImporter.js';
 // Streaming
 export { VFSReadStream } from './streams/VFSReadStream.js';
 export { VFSWriteStream } from './streams/VFSWriteStream.js';
-// Knowledge Layer Components (optional via augmentation)
-export { EventRecorder } from './EventRecorder.js';
-export { SemanticVersioning } from './SemanticVersioning.js';
-export { PersistentEntitySystem } from './PersistentEntitySystem.js';
-export { ConceptSystem } from './ConceptSystem.js';
-export { GitBridge } from './GitBridge.js';
 // Convenience alias
 export { VirtualFileSystem as VFS } from './VirtualFileSystem.js';
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,84 @@
+/**
+ * Projection Registry
+ *
+ * Central registry for all projection strategies
+ * Manages strategy lookup and execution
+ */
+import { ProjectionStrategy } from './ProjectionStrategy.js';
+import { Brainy } from '../../brainy.js';
+import { VirtualFileSystem } from '../VirtualFileSystem.js';
+import { VFSEntity } from '../types.js';
+/**
+ * Registry for projection strategies
+ * Allows dynamic registration and lookup of strategies
+ */
+export declare class ProjectionRegistry {
+    private strategies;
+    /**
+     * Register a projection strategy
+     * @param strategy - The strategy to register
+     * @throws Error if strategy with same name already registered
+     */
+    register(strategy: ProjectionStrategy): void;
+    /**
+     * Get a projection strategy by name
+     * @param name - Strategy name
+     * @returns The strategy or undefined if not found
+     */
+    get(name: string): ProjectionStrategy | undefined;
+    /**
+     * Check if a strategy is registered
+     * @param name - Strategy name
+     */
+    has(name: string): boolean;
+    /**
+     * List all registered strategy names
+     */
+    listDimensions(): string[];
+    /**
+     * Get count of registered strategies
+     */
+    count(): number;
+    /**
+     * Resolve a dimension value to entity IDs
+     * Convenience method that looks up strategy and calls resolve()
+     *
+     * @param dimension - The semantic dimension
+     * @param value - The value to resolve
+     * @param brain - REAL Brainy instance
+     * @param vfs - REAL VirtualFileSystem instance
+     * @returns Array of entity IDs
+     * @throws Error if dimension not registered
+     */
+    resolve(dimension: string, value: any, brain: Brainy, vfs: VirtualFileSystem): Promise<string[]>;
+    /**
+     * List entities in a dimension
+     * Convenience method for strategies that support listing
+     *
+     * @param dimension - The semantic dimension
+     * @param brain - REAL Brainy instance
+     * @param vfs - REAL VirtualFileSystem instance
+     * @param limit - Max results
+     * @returns Array of VFSEntity
+     * @throws Error if dimension not registered or doesn't support listing
+     */
+    list(dimension: string, brain: Brainy, vfs: VirtualFileSystem, limit?: number): Promise<VFSEntity[]>;
+    /**
+     * Unregister a strategy
+     * Useful for testing or dynamic strategy management
+     *
+     * @param name - Strategy name to remove
+     * @returns true if removed, false if not found
+     */
+    unregister(name: string): boolean;
+    /**
+     * Clear all registered strategies
+     * Useful for testing
+     */
+    clear(): void;
+    /**
+     * Get all registered strategies
+     * Returns a copy to prevent external modification
+     */
+    getAll(): ProjectionStrategy[];
+}

package/dist/vfs/semantic/ProjectionRegistry.js

@@ -0,0 +1,118 @@
+/**
+ * Projection Registry
+ *
+ * Central registry for all projection strategies
+ * Manages strategy lookup and execution
+ */
+/**
+ * Registry for projection strategies
+ * Allows dynamic registration and lookup of strategies
+ */
+export class ProjectionRegistry {
+    constructor() {
+        this.strategies = new Map();
+    }
+    /**
+     * Register a projection strategy
+     * @param strategy - The strategy to register
+     * @throws Error if strategy with same name already registered
+     */
+    register(strategy) {
+        if (this.strategies.has(strategy.name)) {
+            throw new Error(`Projection strategy '${strategy.name}' is already registered`);
+        }
+        this.strategies.set(strategy.name, strategy);
+    }
+    /**
+     * Get a projection strategy by name
+     * @param name - Strategy name
+     * @returns The strategy or undefined if not found
+     */
+    get(name) {
+        return this.strategies.get(name);
+    }
+    /**
+     * Check if a strategy is registered
+     * @param name - Strategy name
+     */
+    has(name) {
+        return this.strategies.has(name);
+    }
+    /**
+     * List all registered strategy names
+     */
+    listDimensions() {
+        return Array.from(this.strategies.keys());
+    }
+    /**
+     * Get count of registered strategies
+     */
+    count() {
+        return this.strategies.size;
+    }
+    /**
+     * Resolve a dimension value to entity IDs
+     * Convenience method that looks up strategy and calls resolve()
+     *
+     * @param dimension - The semantic dimension
+     * @param value - The value to resolve
+     * @param brain - REAL Brainy instance
+     * @param vfs - REAL VirtualFileSystem instance
+     * @returns Array of entity IDs
+     * @throws Error if dimension not registered
+     */
+    async resolve(dimension, value, brain, vfs) {
+        const strategy = this.get(dimension);
+        if (!strategy) {
+            throw new Error(`Unknown projection dimension: ${dimension}. Registered dimensions: ${this.listDimensions().join(', ')}`);
+        }
+        // Call REAL strategy resolve method
+        return await strategy.resolve(brain, vfs, value);
+    }
+    /**
+     * List entities in a dimension
+     * Convenience method for strategies that support listing
+     *
+     * @param dimension - The semantic dimension
+     * @param brain - REAL Brainy instance
+     * @param vfs - REAL VirtualFileSystem instance
+     * @param limit - Max results
+     * @returns Array of VFSEntity
+     * @throws Error if dimension not registered or doesn't support listing
+     */
+    async list(dimension, brain, vfs, limit) {
+        const strategy = this.get(dimension);
+        if (!strategy) {
+            throw new Error(`Unknown projection dimension: ${dimension}`);
+        }
+        if (!strategy.list) {
+            throw new Error(`Projection '${dimension}' does not support listing`);
+        }
+        return await strategy.list(brain, vfs, limit);
+    }
+    /**
+     * Unregister a strategy
+     * Useful for testing or dynamic strategy management
+     *
+     * @param name - Strategy name to remove
+     * @returns true if removed, false if not found
+     */
+    unregister(name) {
+        return this.strategies.delete(name);
+    }
+    /**
+     * Clear all registered strategies
+     * Useful for testing
+     */
+    clear() {
+        this.strategies.clear();
+    }
+    /**
+     * Get all registered strategies
+     * Returns a copy to prevent external modification
+     */
+    getAll() {
+        return Array.from(this.strategies.values());
+    }
+}
+//# sourceMappingURL=ProjectionRegistry.js.map

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

@@ -0,0 +1,69 @@
+/**
+ * Projection Strategy Interface
+ *
+ * Defines how to map semantic path dimensions to Brainy queries
+ * Each strategy uses EXISTING Brainy indexes and methods
+ */
+import { Brainy } from '../../brainy.js';
+import { VirtualFileSystem } from '../VirtualFileSystem.js';
+import { FindParams } from '../../types/brainy.types.js';
+import { VFSEntity } from '../types.js';
+/**
+ * Strategy for projecting semantic paths into entity queries
+ * All implementations MUST use real Brainy methods (no stubs!)
+ */
+export interface ProjectionStrategy {
+    /**
+     * Strategy name (used for registration)
+     */
+    readonly name: string;
+    /**
+     * Convert semantic value to Brainy FindParams
+     * Uses EXISTING FindParams type from brainy.types.ts
+     */
+    toQuery(value: any, subpath?: string): FindParams;
+    /**
+     * Resolve semantic value to entity IDs
+     * Uses REAL Brainy.find() method
+     *
+     * @param brain - REAL Brainy instance
+     * @param vfs - REAL VirtualFileSystem instance
+     * @param value - The semantic value to resolve
+     * @returns Array of entity IDs that match
+     */
+    resolve(brain: Brainy, vfs: VirtualFileSystem, value: any): Promise<string[]>;
+    /**
+     * List all entities in this dimension
+     * Optional - not all strategies need to implement
+     *
+     * @param brain - REAL Brainy instance
+     * @param vfs - REAL VirtualFileSystem instance
+     * @param limit - Max results to return
+     */
+    list?(brain: Brainy, vfs: VirtualFileSystem, limit?: number): Promise<VFSEntity[]>;
+}
+/**
+ * Base class for projection strategies with common utilities
+ */
+export declare abstract class BaseProjectionStrategy implements ProjectionStrategy {
+    abstract readonly name: string;
+    abstract toQuery(value: any, subpath?: string): FindParams;
+    abstract resolve(brain: Brainy, vfs: VirtualFileSystem, value: any): Promise<string[]>;
+    /**
+     * Convert Brainy Results to entity IDs
+     * Helper method for subclasses
+     */
+    protected extractIds(results: Array<{
+        id: string;
+    }>): string[];
+    /**
+     * Verify that an entity is a file (not directory)
+     * Uses REAL Brainy.get() method
+     */
+    protected isFile(brain: Brainy, entityId: string): Promise<boolean>;
+    /**
+     * Filter entity IDs to only include files
+     * Uses REAL Brainy.get() for each entity
+     */
+    protected filterFiles(brain: Brainy, entityIds: string[]): Promise<string[]>;
+}

package/dist/vfs/semantic/ProjectionStrategy.js

@@ -0,0 +1,40 @@
+/**
+ * Projection Strategy Interface
+ *
+ * Defines how to map semantic path dimensions to Brainy queries
+ * Each strategy uses EXISTING Brainy indexes and methods
+ */
+/**
+ * Base class for projection strategies with common utilities
+ */
+export class BaseProjectionStrategy {
+    /**
+     * Convert Brainy Results to entity IDs
+     * Helper method for subclasses
+     */
+    extractIds(results) {
+        return results.map(r => r.id);
+    }
+    /**
+     * Verify that an entity is a file (not directory)
+     * Uses REAL Brainy.get() method
+     */
+    async isFile(brain, entityId) {
+        const entity = await brain.get(entityId);
+        return entity?.metadata?.vfsType === 'file';
+    }
+    /**
+     * Filter entity IDs to only include files
+     * Uses REAL Brainy.get() for each entity
+     */
+    async filterFiles(brain, entityIds) {
+        const files = [];
+        for (const id of entityIds) {
+            if (await this.isFile(brain, id)) {
+                files.push(id);
+            }
+        }
+        return files;
+    }
+}
+//# sourceMappingURL=ProjectionStrategy.js.map

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

@@ -0,0 +1,73 @@
+/**
+ * Semantic Path Parser
+ *
+ * Parses semantic filesystem paths into structured queries
+ * PURE LOGIC - No external dependencies, no async operations
+ *
+ * Supported path formats:
+ * - Traditional: /src/auth.ts
+ * - By Concept: /by-concept/authentication/login.ts
+ * - By Author: /by-author/alice/file.ts
+ * - By Time: /as-of/2024-03-15/file.ts
+ * - By Relationship: /related-to/src/auth.ts/depth-2
+ * - By Similarity: /similar-to/src/auth.ts/threshold-0.8
+ * - By Tag: /by-tag/security/file.ts
+ */
+export type SemanticDimension = 'traditional' | 'concept' | 'author' | 'time' | 'relationship' | 'similar' | 'tag';
+export interface ParsedSemanticPath {
+    dimension: SemanticDimension;
+    value: string | Date | RelationshipValue | SimilarityValue;
+    subpath?: string;
+    filters?: Record<string, any>;
+}
+export interface RelationshipValue {
+    targetPath: string;
+    depth?: number;
+    relationshipTypes?: string[];
+}
+export interface SimilarityValue {
+    targetPath: string;
+    threshold?: number;
+}
+/**
+ * Semantic Path Parser
+ * Parses various semantic path formats into structured data
+ */
+export declare class SemanticPathParser {
+    private static readonly PATTERNS;
+    /**
+     * Parse a path into semantic components
+     * PURE FUNCTION - no external calls, no async
+     */
+    parse(path: string): ParsedSemanticPath;
+    /**
+     * Check if a path is semantic (non-traditional)
+     */
+    isSemanticPath(path: string): boolean;
+    /**
+     * Get the dimension type from a path
+     */
+    getDimension(path: string): SemanticDimension;
+    /**
+     * Normalize a path - remove trailing slashes, collapse multiple slashes
+     * PURE FUNCTION
+     */
+    private normalizePath;
+    /**
+     * Parse date string (YYYY-MM-DD) into Date object
+     * PURE FUNCTION
+     */
+    private parseDate;
+    /**
+     * Validate parsed path structure
+     */
+    validate(parsed: ParsedSemanticPath): boolean;
+    /**
+     * Parse relationship paths: /related-to/<path>/depth-N/types-X,Y/<subpath>
+     */
+    private parseRelationshipPath;
+    /**
+     * Parse similarity paths: /similar-to/<path>/threshold-N/<subpath>
+     */
+    private parseSimilarityPath;
+}

package/dist/vfs/semantic/SemanticPathParser.js

@@ -0,0 +1,285 @@
+/**
+ * Semantic Path Parser
+ *
+ * Parses semantic filesystem paths into structured queries
+ * PURE LOGIC - No external dependencies, no async operations
+ *
+ * Supported path formats:
+ * - Traditional: /src/auth.ts
+ * - By Concept: /by-concept/authentication/login.ts
+ * - By Author: /by-author/alice/file.ts
+ * - By Time: /as-of/2024-03-15/file.ts
+ * - By Relationship: /related-to/src/auth.ts/depth-2
+ * - By Similarity: /similar-to/src/auth.ts/threshold-0.8
+ * - By Tag: /by-tag/security/file.ts
+ */
+/**
+ * Semantic Path Parser
+ * Parses various semantic path formats into structured data
+ */
+export class SemanticPathParser {
+    /**
+     * Parse a path into semantic components
+     * PURE FUNCTION - no external calls, no async
+     */
+    parse(path) {
+        if (!path || typeof path !== 'string') {
+            throw new Error('Path must be a non-empty string');
+        }
+        // Normalize path
+        const normalized = this.normalizePath(path);
+        // Try concept dimension
+        const conceptMatch = normalized.match(SemanticPathParser.PATTERNS.concept);
+        if (conceptMatch) {
+            return {
+                dimension: 'concept',
+                value: conceptMatch[1],
+                subpath: conceptMatch[2]
+            };
+        }
+        // Try author dimension
+        const authorMatch = normalized.match(SemanticPathParser.PATTERNS.author);
+        if (authorMatch) {
+            return {
+                dimension: 'author',
+                value: authorMatch[1],
+                subpath: authorMatch[2]
+            };
+        }
+        // Try time dimension
+        const timeMatch = normalized.match(SemanticPathParser.PATTERNS.time);
+        if (timeMatch) {
+            const dateStr = timeMatch[1];
+            const date = this.parseDate(dateStr);
+            return {
+                dimension: 'time',
+                value: date,
+                subpath: timeMatch[2]
+            };
+        }
+        // Try relationship dimension
+        if (normalized.startsWith('/related-to/')) {
+            return this.parseRelationshipPath(normalized);
+        }
+        // Try similarity dimension
+        if (normalized.startsWith('/similar-to/')) {
+            return this.parseSimilarityPath(normalized);
+        }
+        // Try tag dimension
+        const tagMatch = normalized.match(SemanticPathParser.PATTERNS.tag);
+        if (tagMatch) {
+            return {
+                dimension: 'tag',
+                value: tagMatch[1],
+                subpath: tagMatch[2]
+            };
+        }
+        // Default to traditional path
+        return {
+            dimension: 'traditional',
+            value: normalized
+        };
+    }
+    /**
+     * Check if a path is semantic (non-traditional)
+     */
+    isSemanticPath(path) {
+        if (!path || typeof path !== 'string') {
+            return false;
+        }
+        const normalized = this.normalizePath(path);
+        // Check if matches any semantic pattern
+        return (normalized.startsWith('/by-concept/') ||
+            normalized.startsWith('/by-author/') ||
+            normalized.startsWith('/as-of/') ||
+            normalized.startsWith('/related-to/') ||
+            normalized.startsWith('/similar-to/') ||
+            normalized.startsWith('/by-tag/'));
+    }
+    /**
+     * Get the dimension type from a path
+     */
+    getDimension(path) {
+        return this.parse(path).dimension;
+    }
+    /**
+     * Normalize a path - remove trailing slashes, collapse multiple slashes
+     * PURE FUNCTION
+     */
+    normalizePath(path) {
+        // Remove trailing slash (except for root)
+        let normalized = path.replace(/\/+$/, '');
+        // Collapse multiple slashes
+        normalized = normalized.replace(/\/+/g, '/');
+        // Ensure starts with /
+        if (!normalized.startsWith('/')) {
+            normalized = '/' + normalized;
+        }
+        // Special case: empty path becomes /
+        if (normalized === '') {
+            normalized = '/';
+        }
+        return normalized;
+    }
+    /**
+     * Parse date string (YYYY-MM-DD) into Date object
+     * PURE FUNCTION
+     */
+    parseDate(dateStr) {
+        const parts = dateStr.split('-');
+        if (parts.length !== 3) {
+            throw new Error(`Invalid date format: ${dateStr}. Expected YYYY-MM-DD`);
+        }
+        const year = parseInt(parts[0], 10);
+        const month = parseInt(parts[1], 10) - 1; // Months are 0-indexed in JS
+        const day = parseInt(parts[2], 10);
+        if (isNaN(year) || isNaN(month) || isNaN(day)) {
+            throw new Error(`Invalid date format: ${dateStr}. Expected YYYY-MM-DD`);
+        }
+        if (year < 1900 || year > 2100) {
+            throw new Error(`Invalid year: ${year}. Expected 1900-2100`);
+        }
+        if (month < 0 || month > 11) {
+            throw new Error(`Invalid month: ${month + 1}. Expected 1-12`);
+        }
+        if (day < 1 || day > 31) {
+            throw new Error(`Invalid day: ${day}. Expected 1-31`);
+        }
+        return new Date(year, month, day);
+    }
+    /**
+     * Validate parsed path structure
+     */
+    validate(parsed) {
+        if (!parsed || typeof parsed !== 'object') {
+            return false;
+        }
+        if (!parsed.dimension) {
+            return false;
+        }
+        if (parsed.value === undefined || parsed.value === null) {
+            return false;
+        }
+        // Dimension-specific validation
+        switch (parsed.dimension) {
+            case 'time':
+                return parsed.value instanceof Date && !isNaN(parsed.value.getTime());
+            case 'relationship':
+                const relValue = parsed.value;
+                return typeof relValue.targetPath === 'string' && relValue.targetPath.length > 0;
+            case 'similar':
+                const simValue = parsed.value;
+                return typeof simValue.targetPath === 'string' && simValue.targetPath.length > 0;
+            default:
+                return typeof parsed.value === 'string' && parsed.value.length > 0;
+        }
+    }
+    /**
+     * Parse relationship paths: /related-to/<path>/depth-N/types-X,Y/<subpath>
+     */
+    parseRelationshipPath(path) {
+        // Remove /related-to/ prefix
+        const withoutPrefix = path.substring('/related-to/'.length);
+        // Split into segments
+        const segments = withoutPrefix.split('/');
+        let targetPath = '';
+        let depth;
+        let types;
+        let subpath;
+        let i = 0;
+        // Collect path segments until we hit depth-, types-, or end
+        while (i < segments.length) {
+            const segment = segments[i];
+            if (segment.startsWith('depth-')) {
+                depth = parseInt(segment.substring('depth-'.length), 10);
+                i++;
+                continue;
+            }
+            if (segment.startsWith('types-')) {
+                types = segment.substring('types-'.length).split(',');
+                i++;
+                continue;
+            }
+            // If we've already collected the target path and found depth/types,
+            // rest is subpath
+            if (targetPath && (depth !== undefined || types !== undefined)) {
+                subpath = segments.slice(i).join('/');
+                break;
+            }
+            // Add to target path
+            if (targetPath) {
+                targetPath += '/' + segment;
+            }
+            else {
+                targetPath = segment;
+            }
+            i++;
+        }
+        const value = {
+            targetPath,
+            depth,
+            relationshipTypes: types
+        };
+        return {
+            dimension: 'relationship',
+            value,
+            subpath
+        };
+    }
+    /**
+     * Parse similarity paths: /similar-to/<path>/threshold-N/<subpath>
+     */
+    parseSimilarityPath(path) {
+        // Remove /similar-to/ prefix
+        const withoutPrefix = path.substring('/similar-to/'.length);
+        // Split into segments
+        const segments = withoutPrefix.split('/');
+        let targetPath = '';
+        let threshold;
+        let subpath;
+        let i = 0;
+        // Collect path segments until we hit threshold- or end
+        while (i < segments.length) {
+            const segment = segments[i];
+            if (segment.startsWith('threshold-')) {
+                threshold = parseFloat(segment.substring('threshold-'.length));
+                i++;
+                // Rest is subpath
+                if (i < segments.length) {
+                    subpath = segments.slice(i).join('/');
+                }
+                break;
+            }
+            // Add to target path
+            if (targetPath) {
+                targetPath += '/' + segment;
+            }
+            else {
+                targetPath = segment;
+            }
+            i++;
+        }
+        const value = {
+            targetPath,
+            threshold
+        };
+        return {
+            dimension: 'similar',
+            value,
+            subpath
+        };
+    }
+}
+// Regex patterns for each dimension
+SemanticPathParser.PATTERNS = {
+    concept: /^\/by-concept\/([^\/]+)(?:\/(.+))?$/,
+    author: /^\/by-author\/([^\/]+)(?:\/(.+))?$/,
+    time: /^\/as-of\/(\d{4}-\d{2}-\d{2})(?:\/(.+))?$/,
+    // Relationship: /related-to/<path>/depth-N/types-X,Y/<subpath>
+    // Must handle paths with slashes, so capture everything before /depth- or /types-
+    relationship: /^\/related-to\/(.+?)(?:\/depth-(\d+)|\/types-([^\/]+)|\/(.+))*$/,
+    // Similarity: /similar-to/<path>/threshold-N/<subpath>
+    similar: /^\/similar-to\/(.+?)(?:\/threshold-([\d.]+)|\/(.+))*$/,
+    tag: /^\/by-tag\/([^\/]+)(?:\/(.+))?$/
+};
+//# sourceMappingURL=SemanticPathParser.js.map