@soulcraft/brainy 4.6.0 → 4.7.0

package/dist/brainy.d.ts

@@ -545,18 +545,23 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      * // Returns only knowledge entities, VFS files excluded
      *
      * @example
-     * // Include VFS entities when needed
+     * // v4.7.0: VFS entities included by default
      * const everything = await brainy.find({
-     *   query: 'documentation',
-     *   includeVFS: true  // Opt-in to include VFS files
+     *   query: 'documentation'
      * })
      * // Returns both knowledge entities AND VFS files
      *
      * @example
      * // Search only VFS files
      * const files = await brainy.find({
-     *   where: { vfsType: 'file', extension: '.md' },
-     *   includeVFS: true  // Required to find VFS entities
+     *   where: { vfsType: 'file', extension: '.md' }
+     * })
+     *
+     * @example
+     * // Exclude VFS entities (if needed)
+     * const concepts = await brainy.find({
+     *   query: 'machine learning',
+     *   excludeVFS: true  // v4.7.0: Exclude VFS files
      * })
      */
     find(query: string | FindParams<T>): Promise<Result<T>[]>;

package/dist/brainy.js

@@ -852,13 +852,8 @@ export class Brainy {
         if (params.service) {
             filter.service = params.service;
         }
-        // v4.5.1: Exclude VFS relationships by default (same pattern as brain.find())
-        // VFS relationships have metadata.isVFS = true
-        // Only include VFS relationships if explicitly requested
-        if (params.includeVFS !== true) {
-            filter.metadata = filter.metadata || {};
-            filter.metadata.isVFS = { notEquals: true };
-        }
+        // v4.7.0: VFS relationships are no longer filtered
+        // VFS is part of the knowledge graph - users can filter explicitly if needed
         // Fetch from storage with pagination at storage layer (efficient!)
         const result = await this.storage.getVerbs({
             pagination: {
@@ -1033,18 +1028,23 @@ export class Brainy {
      * // Returns only knowledge entities, VFS files excluded
      *
      * @example
-     * // Include VFS entities when needed
+     * // v4.7.0: VFS entities included by default
      * const everything = await brainy.find({
-     *   query: 'documentation',
-     *   includeVFS: true  // Opt-in to include VFS files
+     *   query: 'documentation'
      * })
      * // Returns both knowledge entities AND VFS files
      *
      * @example
      * // Search only VFS files
      * const files = await brainy.find({
-     *   where: { vfsType: 'file', extension: '.md' },
-     *   includeVFS: true  // Required to find VFS entities
+     *   where: { vfsType: 'file', extension: '.md' }
+     * })
+     *
+     * @example
+     * // Exclude VFS entities (if needed)
+     * const concepts = await brainy.find({
+     *   query: 'machine learning',
+     *   excludeVFS: true  // v4.7.0: Exclude VFS files
      * })
      */
     async find(query) {
@@ -1090,11 +1090,10 @@ export class Brainy {
                     Object.assign(filter, params.where);
                 if (params.service)
                     filter.service = params.service;
-                // v4.3.3: Exclude VFS entities by default (Option 3C architecture)
-                // Only include VFS if explicitly requested via includeVFS: true
-                // BUT: Don't add automatic exclusion if user explicitly queries isVFS in where clause
-                if (params.includeVFS !== true && !params.where?.hasOwnProperty('isVFS')) {
-                    filter.isVFS = { notEquals: true };
+                // v4.7.0: excludeVFS helper for cleaner UX
+                // Use vfsType field (more semantic than isVFS)
+                if (params.excludeVFS === true) {
+                    filter.vfsType = { exists: false };
                 }
                 if (params.type) {
                     const types = Array.isArray(params.type) ? params.type : [params.type];
@@ -1137,12 +1136,12 @@ export class Brainy {
             if (!hasVectorSearchCriteria && !hasFilterCriteria && !hasGraphCriteria) {
                 const limit = params.limit || 20;
                 const offset = params.offset || 0;
-                // v4.3.3: Apply VFS filtering even for empty queries
+                // v4.7.0: excludeVFS helper
                 let filter = {};
-                if (params.includeVFS !== true) {
-                    filter.isVFS = { notEquals: true };
+                if (params.excludeVFS === true) {
+                    filter.vfsType = { exists: false };
                 }
-                // Use metadata index if we need to filter VFS
+                // Use metadata index if we need to filter
                 if (Object.keys(filter).length > 0) {
                     const filteredIds = await this.metadataIndex.getIdsForFilter(filter);
                     const pageIds = filteredIds.slice(offset, offset + limit);
@@ -1197,7 +1196,7 @@ export class Brainy {
                 results = Array.from(uniqueResults.values());
             }
             // Apply O(log n) metadata filtering using core MetadataIndexManager
-            if (params.where || params.type || params.service || params.includeVFS !== true) {
+            if (params.where || params.type || params.service || params.excludeVFS) {
                 // Build filter object for metadata index
                 let filter = {};
                 // Base filter from where and service
@@ -1205,10 +1204,9 @@ export class Brainy {
                     Object.assign(filter, params.where);
                 if (params.service)
                     filter.service = params.service;
-                // v4.3.3: Exclude VFS entities by default (Option 3C architecture)
-                // BUT: Don't add automatic exclusion if user explicitly queries isVFS in where clause
-                if (params.includeVFS !== true && !params.where?.hasOwnProperty('isVFS')) {
-                    filter.isVFS = { notEquals: true };
+                // v4.7.0: excludeVFS helper for cleaner UX
+                if (params.excludeVFS === true) {
+                    filter.vfsType = { exists: false };
                 }
                 if (params.type) {
                     const types = Array.isArray(params.type) ? params.type : [params.type];
@@ -1480,7 +1478,7 @@ export class Brainy {
             type: params.type,
             where: params.where,
             service: params.service,
-            includeVFS: params.includeVFS // v4.4.0: Pass through VFS filtering
+            excludeVFS: params.excludeVFS // v4.7.0: Pass through VFS filtering
         });
     }
     // ============= BATCH OPERATIONS =============

package/dist/cli/commands/core.js

@@ -274,10 +274,8 @@ export const coreCommands = {
             if (options.includeRelations) {
                 searchParams.includeRelations = true;
             }
-            // Include VFS files (v4.4.0 - find excludes VFS by default)
-            if (options.includeVfs) {
-                searchParams.includeVFS = true;
-            }
+            // v4.7.0: VFS is now part of the knowledge graph (included by default)
+            // Users can exclude VFS with --where vfsType exists:false if needed
             // Triple Intelligence Fusion - custom weighting
             if (options.fusion || options.vectorWeight || options.graphWeight || options.fieldWeight) {
                 searchParams.fusion = {

package/dist/types/brainy.types.d.ts

@@ -148,7 +148,7 @@ export interface FindParams<T = any> {
     mode?: SearchMode;
     explain?: boolean;
     includeRelations?: boolean;
-    includeVFS?: boolean;
+    excludeVFS?: boolean;
     service?: string;
     fusion?: {
         strategy?: 'adaptive' | 'weighted' | 'progressive';
@@ -186,7 +186,7 @@ export interface SimilarParams<T = any> {
     type?: NounType | NounType[];
     where?: Partial<T>;
     service?: string;
-    includeVFS?: boolean;
+    excludeVFS?: boolean;
 }
 /**
  * Parameters for getting relationships
@@ -268,16 +268,6 @@ export interface GetRelationsParams {
      * Only return relationships belonging to this service.
      */
     service?: string;
-    /**
-     * Include VFS relationships (v4.5.1)
-     *
-     * By default, getRelations() excludes VFS relationships (since v4.4.0).
-     * Set this to true when you need to traverse VFS structure.
-     *
-     * @default false
-     * @since v4.5.1
-     */
-    includeVFS?: boolean;
 }
 /**
  * Batch add parameters

package/dist/vfs/PathResolver.js

@@ -131,12 +131,11 @@ export class PathResolver {
             // Use cached knowledge to quickly find the child
             // Still need to verify it exists
         }
-        // Use proper graph traversal to find children
-        // Get all relationships where parentId contains other entities
+        // v4.7.0: Use proper graph traversal to find children
+        // VFS relationships are now part of the knowledge graph
         const relations = await this.brain.getRelations({
             from: parentId,
-            type: VerbType.Contains,
-            includeVFS: true // v4.5.1: Required to see VFS relationships
+            type: VerbType.Contains
         });
         // Find the child with matching name
         for (const relation of relations) {
@@ -157,11 +156,11 @@ export class PathResolver {
      * Uses proper graph relationships to traverse the tree
      */
     async getChildren(dirId) {
-        // Production-ready: Use graph relationships (VFS creates these in mkdir/writeFile)
+        // v4.7.0: Use O(1) graph relationships (VFS creates these in mkdir/writeFile)
+        // VFS relationships are now part of the knowledge graph (no special filtering needed)
         const relations = await this.brain.getRelations({
             from: dirId,
-            type: VerbType.Contains,
-            includeVFS: true // v4.5.1: Required to see VFS relationships
+            type: VerbType.Contains
         });
         const validChildren = [];
         const childNames = new Set();

package/dist/vfs/VirtualFileSystem.js

@@ -98,8 +98,7 @@ export class VirtualFileSystem {
                 path: '/', // ✅ Correct field name
                 vfsType: 'directory' // ✅ Correct field name
             },
-            limit: 10,
-            includeVFS: true // v4.4.0: CRITICAL - Must find VFS root entity!
+            limit: 10
         });
         if (existing.length > 0) {
             // Handle duplicate roots (Workshop team reported ~10 duplicates!)
@@ -780,9 +779,8 @@ export class VirtualFileSystem {
             limit: options?.limit || 10,
             offset: options?.offset,
             explain: options?.explain,
-            includeVFS: true, // v4.4.0: VFS search must include VFS entities!
             where: {
-                vfsType: 'file' // v4.4.0: Only search VFS files, not knowledge documents
+                vfsType: 'file' // v4.7.0: Search VFS files
             }
         };
         // Add path filter if specified
@@ -824,9 +822,8 @@ export class VirtualFileSystem {
             limit: options?.limit || 10,
             threshold: options?.threshold || 0.7,
             type: [NounType.File, NounType.Document, NounType.Media],
-            includeVFS: true, // v4.4.0: VFS similarity search must include VFS entities!
             where: {
-                vfsType: 'file' // v4.4.0: Only find similar VFS files, not knowledge documents
+                vfsType: 'file' // v4.7.0: Find similar VFS files
             }
         });
         return results.map(r => {
@@ -1969,8 +1966,7 @@ export class VirtualFileSystem {
                 ...query.where,
                 vfsType: 'entity'
             },
-            limit: query.limit || 100,
-            includeVFS: true // v4.4.0: VFS entity search must include VFS entities!
+            limit: query.limit || 100
         };
         if (query.type) {
             searchQuery.where.entityType = query.type;

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

@@ -27,8 +27,7 @@ export class AuthorProjection extends BaseProjectionStrategy {
                 vfsType: 'file',
                 owner: authorName
             },
-            limit: 1000,
-            includeVFS: true // v4.4.0: Must include VFS entities!
+            limit: 1000
         };
         // Filter by filename if subpath specified
         if (subpath) {
@@ -46,14 +45,13 @@ export class AuthorProjection extends BaseProjectionStrategy {
      * Resolve author to entity IDs using REAL Brainy.find()
      */
     async resolve(brain, vfs, authorName) {
-        // Use REAL Brainy metadata filtering
+        // v4.7.0: VFS entities are part of the knowledge graph
         const results = await brain.find({
             where: {
                 vfsType: 'file',
                 owner: authorName
             },
-            limit: 1000,
-            includeVFS: true // v4.4.0: Must include VFS entities!
+            limit: 1000
         });
         return this.extractIds(results);
     }
@@ -66,10 +64,9 @@ export class AuthorProjection extends BaseProjectionStrategy {
         const results = await brain.find({
             where: {
                 vfsType: 'file',
-                owner: { $exists: true }
+                owner: { exists: true }
             },
-            limit,
-            includeVFS: true // v4.4.0: Must include VFS entities!
+            limit
         });
         return results.map(r => r.entity);
     }

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

@@ -25,10 +25,9 @@ export class TagProjection extends BaseProjectionStrategy {
         const query = {
             where: {
                 vfsType: 'file',
-                tags: { contains: tagName } // BFO operator for array contains
+                tags: { contains: tagName } // contains operator for array search
             },
-            limit: 1000,
-            includeVFS: true // v4.4.0: Must include VFS entities!
+            limit: 1000
         };
         // Filter by filename if subpath specified
         if (subpath) {
@@ -46,14 +45,13 @@ export class TagProjection extends BaseProjectionStrategy {
      * Resolve tag to entity IDs using REAL Brainy.find()
      */
     async resolve(brain, vfs, tagName) {
-        // Use REAL Brainy metadata filtering
+        // v4.7.0: VFS entities are part of the knowledge graph
         const results = await brain.find({
             where: {
                 vfsType: 'file',
-                tags: { contains: tagName } // BFO operator
+                tags: { contains: tagName }
             },
-            limit: 1000,
-            includeVFS: true // v4.4.0: Must include VFS entities!
+            limit: 1000
         });
         return this.extractIds(results);
     }
@@ -65,10 +63,9 @@ export class TagProjection extends BaseProjectionStrategy {
         const results = await brain.find({
             where: {
                 vfsType: 'file',
-                tags: { exists: true } // BFO operator
+                tags: { exists: true } // exists operator
             },
-            limit,
-            includeVFS: true // v4.4.0: Must include VFS entities!
+            limit
         });
         return results.map(r => r.entity);
     }

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

@@ -58,17 +58,16 @@ export class TemporalProjection extends BaseProjectionStrategy {
         startOfDay.setHours(0, 0, 0, 0);
         const endOfDay = new Date(date);
         endOfDay.setHours(23, 59, 59, 999);
-        // Use REAL Brainy metadata filtering with range operators
+        // v4.7.0: VFS entities are part of the knowledge graph
         const results = await brain.find({
             where: {
                 vfsType: 'file',
                 modified: {
-                    greaterEqual: startOfDay.getTime(), // BFO operator
-                    lessEqual: endOfDay.getTime() // BFO operator
+                    greaterEqual: startOfDay.getTime(),
+                    lessEqual: endOfDay.getTime()
                 }
             },
-            limit: 1000,
-            includeVFS: true // v4.4.0: Must include VFS entities!
+            limit: 1000
         });
         return this.extractIds(results);
     }
@@ -80,10 +79,9 @@ export class TemporalProjection extends BaseProjectionStrategy {
         const results = await brain.find({
             where: {
                 vfsType: 'file',
-                modified: { greaterEqual: oneDayAgo } // BFO operator
+                modified: { greaterEqual: oneDayAgo }
             },
-            limit,
-            includeVFS: true // v4.4.0: Must include VFS entities!
+            limit
         });
         return results.map(r => r.entity);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "4.6.0",
+  "version": "4.7.0",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. 31 nouns × 40 verbs for infinite expressiveness.",
   "main": "dist/index.js",
   "module": "dist/index.js",