@soulcraft/brainy 4.5.3 → 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

@@ -446,7 +446,13 @@ export class Brainy {
             id: noun.id,
             vector: noun.vector,
             type: nounType || NounType.Thing,
-            metadata: userMetadata,
+            // Preserve timestamps in metadata for indexing (v4.5.4 fix)
+            // Metadata index needs these fields to enable sorting and range queries
+            metadata: {
+                ...userMetadata,
+                ...(createdAt !== undefined && { createdAt }),
+                ...(updatedAt !== undefined && { updatedAt })
+            },
             service: service,
             createdAt: createdAt || Date.now(),
             updatedAt: updatedAt
@@ -846,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: {
@@ -1027,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) {
@@ -1084,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];
@@ -1104,8 +1109,17 @@ export class Brainy {
                         };
                     }
                 }
-                // Get filtered IDs and paginate BEFORE loading entities
-                const filteredIds = await this.metadataIndex.getIdsForFilter(filter);
+                // v4.5.4: Apply sorting if requested, otherwise just filter
+                let filteredIds;
+                if (params.orderBy) {
+                    // Get sorted IDs using production-scale sorted filtering
+                    filteredIds = await this.metadataIndex.getSortedIdsForFilter(filter, params.orderBy, params.order || 'asc');
+                }
+                else {
+                    // Just filter without sorting
+                    filteredIds = await this.metadataIndex.getIdsForFilter(filter);
+                }
+                // Paginate BEFORE loading entities (production-scale!)
                 const limit = params.limit || 10;
                 const offset = params.offset || 0;
                 const pageIds = filteredIds.slice(offset, offset + limit);
@@ -1122,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);
@@ -1182,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
@@ -1190,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];
@@ -1252,6 +1265,23 @@ export class Brainy {
                     }
                     // Early return for metadata-only queries with pagination applied
                     if (!params.query && !params.connected) {
+                        // v4.5.4: Apply sorting if requested for metadata-only queries
+                        if (params.orderBy) {
+                            const sortedIds = await this.metadataIndex.getSortedIdsForFilter(filter, params.orderBy, params.order || 'asc');
+                            // Paginate sorted IDs BEFORE loading entities (production-scale!)
+                            const limit = params.limit || 10;
+                            const offset = params.offset || 0;
+                            const pageIds = sortedIds.slice(offset, offset + limit);
+                            // Load entities for paginated results only
+                            const sortedResults = [];
+                            for (const id of pageIds) {
+                                const entity = await this.get(id);
+                                if (entity) {
+                                    sortedResults.push(this.createResult(id, 1.0, entity));
+                                }
+                            }
+                            return sortedResults;
+                        }
                         return results;
                     }
                 }
@@ -1265,7 +1295,35 @@ export class Brainy {
                 results = this.applyFusionScoring(results, params.fusion);
             }
             // OPTIMIZED: Sort first, then apply efficient pagination
-            results.sort((a, b) => b.score - a.score);
+            // v4.5.4: Support custom orderBy for vector + metadata queries
+            if (params.orderBy && results.length > 0) {
+                // For vector + metadata queries, sort by specified field instead of score
+                // Load sort field values for all results (small set, already filtered)
+                const resultsWithValues = await Promise.all(results.map(async (r) => ({
+                    result: r,
+                    value: await this.metadataIndex.getFieldValueForEntity(r.id, params.orderBy)
+                })));
+                // Sort by field value
+                resultsWithValues.sort((a, b) => {
+                    // Handle null/undefined
+                    if (a.value == null && b.value == null)
+                        return 0;
+                    if (a.value == null)
+                        return (params.order || 'asc') === 'asc' ? 1 : -1;
+                    if (b.value == null)
+                        return (params.order || 'asc') === 'asc' ? -1 : 1;
+                    // Compare values
+                    if (a.value === b.value)
+                        return 0;
+                    const comparison = a.value < b.value ? -1 : 1;
+                    return (params.order || 'asc') === 'asc' ? comparison : -comparison;
+                });
+                results = resultsWithValues.map(({ result }) => result);
+            }
+            else {
+                // Default: sort by relevance score
+                results.sort((a, b) => b.score - a.score);
+            }
             const limit = params.limit || 10;
             const offset = params.offset || 0;
             // Efficient pagination - only slice what we need
@@ -1420,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

@@ -143,10 +143,12 @@ export interface FindParams<T = any> {
     limit?: number;
     offset?: number;
     cursor?: string;
+    orderBy?: string;
+    order?: 'asc' | 'desc';
     mode?: SearchMode;
     explain?: boolean;
     includeRelations?: boolean;
-    includeVFS?: boolean;
+    excludeVFS?: boolean;
     service?: string;
     fusion?: {
         strategy?: 'adaptive' | 'weighted' | 'progressive';
@@ -184,7 +186,7 @@ export interface SimilarParams<T = any> {
     type?: NounType | NounType[];
     where?: Partial<T>;
     service?: string;
-    includeVFS?: boolean;
+    excludeVFS?: boolean;
 }
 /**
  * Parameters for getting relationships
@@ -266,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/utils/metadataIndex.d.ts

@@ -155,6 +155,7 @@ export declare class MetadataIndexManager {
     /**
      * Get IDs for a range using chunked sparse index with zone maps and roaring bitmaps (v3.43.0)
      * v3.44.1: Now fully lazy-loaded via UnifiedCache (no local sparseIndices Map)
+     * v4.5.4: Normalize min/max for timestamp bucketing before comparison
      */
     private getIdsFromChunksForRange;
     /**
@@ -271,6 +272,87 @@ export declare class MetadataIndexManager {
      * Get IDs matching Brainy Field Operator metadata filter using indexes where possible
      */
     getIdsForFilter(filter: any): Promise<string[]>;
+    /**
+     * Get filtered IDs sorted by a field (production-scale sorting)
+     *
+     * **Performance Characteristics** (designed for billions of entities):
+     * - **Filtering**: O(log n) using roaring bitmaps with SIMD acceleration
+     * - **Field Loading**: O(k) where k = filtered result count (NOT O(n))
+     * - **Sorting**: O(k log k) in-memory (IDs + sort values only, NOT full entities)
+     * - **Memory**: O(k) for k filtered results, independent of total entity count
+     *
+     * **Scalability**:
+     * - Total entities: Billions (memory usage unaffected)
+     * - Filtered set: Up to 10M (reasonable for in-memory sort of ID+value pairs)
+     * - Pagination: Happens AFTER sorting, so only page entities are loaded
+     *
+     * **Example**:
+     * ```typescript
+     * // Production-scale: 1B entities, 100K match filter, sort by createdAt
+     * const sortedIds = await metadataIndex.getSortedIdsForFilter(
+     *   { status: 'published', category: 'AI' },
+     *   'createdAt',
+     *   'desc'
+     * )
+     * // Returns: 100K sorted IDs
+     * // Memory: ~5MB (100K IDs + 100K timestamps)
+     * // Then caller paginates: sortedIds.slice(0, 20) and loads only 20 entities
+     * ```
+     *
+     * @param filter - Metadata filter criteria (uses roaring bitmaps)
+     * @param orderBy - Field name to sort by (e.g., 'createdAt', 'title')
+     * @param order - Sort direction: 'asc' (default) or 'desc'
+     * @returns Promise<string[]> - Entity IDs sorted by specified field
+     *
+     * @since v4.5.4
+     */
+    getSortedIdsForFilter(filter: any, orderBy: string, order?: 'asc' | 'desc'): Promise<string[]>;
+    /**
+     * Get field value for a specific entity (helper for sorted queries)
+     *
+     * **IMPORTANT**: For timestamp fields (createdAt, updatedAt), this loads
+     * the ACTUAL value from entity metadata, NOT the bucketed index value.
+     * This is required because timestamp bucketing (1-minute precision) loses
+     * precision needed for accurate sorting.
+     *
+     * For non-timestamp fields, loads from the chunked sparse index without
+     * loading the full entity. This is critical for production-scale sorting.
+     *
+     * **Performance**:
+     * - Timestamp fields: O(1) metadata load from storage (cached)
+     * - Other fields: O(chunks) roaring bitmap lookup (typically 1-10 chunks)
+     *
+     * @param entityId - Entity UUID to get field value for
+     * @param field - Field name to retrieve (e.g., 'createdAt', 'title')
+     * @returns Promise<any> - Field value or undefined if not found
+     *
+     * @public (called from brainy.ts for sorted queries)
+     * @since v4.5.4
+     */
+    getFieldValueForEntity(entityId: string, field: string): Promise<any>;
+    /**
+     * Denormalize a value (reverse of normalizeValue)
+     *
+     * Converts normalized/stringified values back to their original type.
+     * For most fields, this just parses numbers or returns strings as-is.
+     *
+     * **NOTE**: This is NOT used for timestamp sorting! Timestamp fields
+     * (createdAt, updatedAt) are loaded directly from entity metadata by
+     * getFieldValueForEntity() to avoid precision loss from bucketing.
+     *
+     * **Timestamp Bucketing (for range queries only)**:
+     * - Indexed as: Math.floor(timestamp / 60000) * 60000
+     * - Used for: Range queries (gte, lte) where 1-minute precision is acceptable
+     * - NOT used for: Sorting (requires exact millisecond precision)
+     *
+     * @param normalized - Normalized value string from index
+     * @param field - Field name (used for type inference)
+     * @returns Denormalized value in original type
+     *
+     * @private
+     * @since v4.5.4
+     */
+    private denormalizeValue;
     /**
      * DEPRECATED - Old implementation for backward compatibility
      */

package/dist/utils/metadataIndex.js

@@ -463,6 +463,7 @@ export class MetadataIndexManager {
     /**
      * Get IDs for a range using chunked sparse index with zone maps and roaring bitmaps (v3.43.0)
      * v3.44.1: Now fully lazy-loaded via UnifiedCache (no local sparseIndices Map)
+     * v4.5.4: Normalize min/max for timestamp bucketing before comparison
      */
     async getIdsFromChunksForRange(field, min, max, includeMin = true, includeMax = true) {
         // Load sparse index via UnifiedCache (lazy loading)
@@ -470,8 +471,12 @@ export class MetadataIndexManager {
         if (!sparseIndex) {
             return []; // No chunked index exists yet
         }
+        // v4.5.4: Normalize min/max for consistent comparison with indexed values
+        // (indexed values are bucketed for timestamps, so we must bucket the query bounds too)
+        const normalizedMin = min !== undefined ? this.normalizeValue(min, field) : undefined;
+        const normalizedMax = max !== undefined ? this.normalizeValue(max, field) : undefined;
         // Find candidate chunks using zone maps
-        const candidateChunkIds = sparseIndex.findChunksForRange(min, max);
+        const candidateChunkIds = sparseIndex.findChunksForRange(normalizedMin, normalizedMax);
         if (candidateChunkIds.length === 0) {
             return [];
         }
@@ -481,13 +486,13 @@ export class MetadataIndexManager {
             const chunk = await this.chunkManager.loadChunk(field, chunkId);
             if (chunk) {
                 for (const [value, bitmap] of chunk.entries) {
-                    // Check if value is in range
+                    // Check if value is in range (both value and normalized bounds are now bucketed)
                     let inRange = true;
-                    if (min !== undefined) {
-                        inRange = inRange && (includeMin ? value >= min : value > min);
+                    if (normalizedMin !== undefined) {
+                        inRange = inRange && (includeMin ? value >= normalizedMin : value > normalizedMin);
                     }
-                    if (max !== undefined) {
-                        inRange = inRange && (includeMax ? value <= max : value < max);
+                    if (normalizedMax !== undefined) {
+                        inRange = inRange && (includeMax ? value <= normalizedMax : value < normalizedMax);
                     }
                     if (inRange) {
                         // Iterate through roaring bitmap integers
@@ -1204,17 +1209,36 @@ export class MetadataIndexManager {
                 continue;
             let fieldResults = [];
             if (condition && typeof condition === 'object' && !Array.isArray(condition)) {
-                // Handle Brainy Field Operators
+                // Handle Brainy Field Operators (v4.5.4: canonical operators defined)
+                // See docs/api/README.md for complete operator reference
                 for (const [op, operand] of Object.entries(condition)) {
                     switch (op) {
-                        // Exact match operators
-                        case 'equals':
-                        case 'is':
+                        // ===== EQUALITY OPERATORS =====
+                        // Canonical: 'eq' | Alias: 'equals' | Deprecated: 'is' (remove in v5.0.0)
+                        case 'is': // DEPRECATED (v4.5.4): Use 'eq' instead
+                        case 'equals': // Alias for 'eq'
                         case 'eq':
                             fieldResults = await this.getIds(field, operand);
                             break;
-                        // Multiple value operators
-                        case 'oneOf':
+                        // ===== NEGATION OPERATORS =====
+                        // Canonical: 'ne' | Alias: 'notEquals' | Deprecated: 'isNot' (remove in v5.0.0)
+                        case 'isNot': // DEPRECATED (v4.5.4): Use 'ne' instead
+                        case 'notEquals': // Alias for 'ne'
+                        case 'ne':
+                            // For notEquals, we need all IDs EXCEPT those matching the value
+                            // This is especially important for soft delete: deleted !== true
+                            // should include items without a deleted field
+                            // First, get all IDs in the database
+                            const allItemIds = await this.getAllIds();
+                            // Then get IDs that match the value we want to exclude
+                            const excludeIds = await this.getIds(field, operand);
+                            const excludeSet = new Set(excludeIds);
+                            // Return all IDs except those to exclude
+                            fieldResults = allItemIds.filter(id => !excludeSet.has(id));
+                            break;
+                        // ===== MULTI-VALUE OPERATORS =====
+                        // Canonical: 'in' | Alias: 'oneOf'
+                        case 'oneOf': // Alias for 'in'
                         case 'in':
                             if (Array.isArray(operand)) {
                                 const unionIds = new Set();
@@ -1225,35 +1249,46 @@ export class MetadataIndexManager {
                                 fieldResults = Array.from(unionIds);
                             }
                             break;
-                        // Range operators
-                        case 'greaterThan':
+                        // ===== GREATER THAN OPERATORS =====
+                        // Canonical: 'gt' | Alias: 'greaterThan'
+                        case 'greaterThan': // Alias for 'gt'
                         case 'gt':
                             fieldResults = await this.getIdsForRange(field, operand, undefined, false, true);
                             break;
-                        case 'greaterEqual':
+                        // ===== GREATER THAN OR EQUAL OPERATORS =====
+                        // Canonical: 'gte' | Alias: 'greaterThanOrEqual' | Deprecated: 'greaterEqual' (remove in v5.0.0)
+                        case 'greaterEqual': // DEPRECATED (v4.5.4): Use 'gte' instead
+                        case 'greaterThanOrEqual': // Alias for 'gte'
                         case 'gte':
-                        case 'greaterThanOrEqual':
                             fieldResults = await this.getIdsForRange(field, operand, undefined, true, true);
                             break;
-                        case 'lessThan':
+                        // ===== LESS THAN OPERATORS =====
+                        // Canonical: 'lt' | Alias: 'lessThan'
+                        case 'lessThan': // Alias for 'lt'
                         case 'lt':
                             fieldResults = await this.getIdsForRange(field, undefined, operand, true, false);
                             break;
-                        case 'lessEqual':
+                        // ===== LESS THAN OR EQUAL OPERATORS =====
+                        // Canonical: 'lte' | Alias: 'lessThanOrEqual' | Deprecated: 'lessEqual' (remove in v5.0.0)
+                        case 'lessEqual': // DEPRECATED (v4.5.4): Use 'lte' instead
+                        case 'lessThanOrEqual': // Alias for 'lte'
                         case 'lte':
-                        case 'lessThanOrEqual':
                             fieldResults = await this.getIdsForRange(field, undefined, operand, true, true);
                             break;
+                        // ===== RANGE OPERATOR =====
+                        // between: [min, max] - inclusive range query
                         case 'between':
                             if (Array.isArray(operand) && operand.length === 2) {
                                 fieldResults = await this.getIdsForRange(field, operand[0], operand[1], true, true);
                             }
                             break;
-                        // Array contains operator
+                        // ===== ARRAY CONTAINS OPERATOR =====
+                        // contains: value - check if array field contains value
                         case 'contains':
                             fieldResults = await this.getIds(field, operand);
                             break;
-                        // Existence operator
+                        // ===== EXISTENCE OPERATOR =====
+                        // exists: boolean - check if field exists (any value)
                         case 'exists':
                             if (operand) {
                                 // Get all IDs that have this field (any value) from chunked sparse index with roaring bitmaps (v3.43.0)
@@ -1279,26 +1314,11 @@ export class MetadataIndexManager {
                                 fieldResults = this.idMapper.intsIterableToUuids(allIntIds);
                             }
                             break;
-                        // Negation operators
-                        case 'notEquals':
-                        case 'isNot':
-                        case 'ne':
-                            // For notEquals, we need all IDs EXCEPT those matching the value
-                            // This is especially important for soft delete: deleted !== true
-                            // should include items without a deleted field
-                            // First, get all IDs in the database
-                            const allItemIds = await this.getAllIds();
-                            // Then get IDs that match the value we want to exclude
-                            const excludeIds = await this.getIds(field, operand);
-                            const excludeSet = new Set(excludeIds);
-                            // Return all IDs except those to exclude
-                            fieldResults = allItemIds.filter(id => !excludeSet.has(id));
-                            break;
                     }
                 }
             }
             else {
-                // Direct value match (shorthand for equals)
+                // Direct value match (shorthand for 'eq' operator)
                 fieldResults = await this.getIds(field, condition);
             }
             if (fieldResults.length > 0) {
@@ -1316,6 +1336,169 @@ export class MetadataIndexManager {
         // Intersection of all field criteria (implicit AND)
         return idSets.reduce((intersection, currentSet) => intersection.filter(id => currentSet.includes(id)));
     }
+    /**
+     * Get filtered IDs sorted by a field (production-scale sorting)
+     *
+     * **Performance Characteristics** (designed for billions of entities):
+     * - **Filtering**: O(log n) using roaring bitmaps with SIMD acceleration
+     * - **Field Loading**: O(k) where k = filtered result count (NOT O(n))
+     * - **Sorting**: O(k log k) in-memory (IDs + sort values only, NOT full entities)
+     * - **Memory**: O(k) for k filtered results, independent of total entity count
+     *
+     * **Scalability**:
+     * - Total entities: Billions (memory usage unaffected)
+     * - Filtered set: Up to 10M (reasonable for in-memory sort of ID+value pairs)
+     * - Pagination: Happens AFTER sorting, so only page entities are loaded
+     *
+     * **Example**:
+     * ```typescript
+     * // Production-scale: 1B entities, 100K match filter, sort by createdAt
+     * const sortedIds = await metadataIndex.getSortedIdsForFilter(
+     *   { status: 'published', category: 'AI' },
+     *   'createdAt',
+     *   'desc'
+     * )
+     * // Returns: 100K sorted IDs
+     * // Memory: ~5MB (100K IDs + 100K timestamps)
+     * // Then caller paginates: sortedIds.slice(0, 20) and loads only 20 entities
+     * ```
+     *
+     * @param filter - Metadata filter criteria (uses roaring bitmaps)
+     * @param orderBy - Field name to sort by (e.g., 'createdAt', 'title')
+     * @param order - Sort direction: 'asc' (default) or 'desc'
+     * @returns Promise<string[]> - Entity IDs sorted by specified field
+     *
+     * @since v4.5.4
+     */
+    async getSortedIdsForFilter(filter, orderBy, order = 'asc') {
+        // 1. Get filtered IDs using existing roaring bitmap implementation (fast!)
+        const filteredIds = await this.getIdsForFilter(filter);
+        if (filteredIds.length === 0) {
+            return [];
+        }
+        // 2. Load sort field values for filtered IDs ONLY
+        // This is O(k) not O(n) where k = filtered count
+        // We only load the ONE field needed for sorting, not full entities
+        const idValuePairs = [];
+        for (const id of filteredIds) {
+            const value = await this.getFieldValueForEntity(id, orderBy);
+            idValuePairs.push({ id, value });
+        }
+        // 3. Sort by value (in-memory BUT only IDs + sort values)
+        // This is acceptable because we're sorting the FILTERED set, not all entities
+        // Even 1M filtered results = ~50MB (IDs + values), manageable in-memory
+        idValuePairs.sort((a, b) => {
+            // Handle null/undefined (always sort to end)
+            if (a.value == null && b.value == null)
+                return 0;
+            if (a.value == null)
+                return order === 'asc' ? 1 : -1;
+            if (b.value == null)
+                return order === 'asc' ? -1 : 1;
+            // Compare values
+            if (a.value === b.value)
+                return 0;
+            const comparison = a.value < b.value ? -1 : 1;
+            return order === 'asc' ? comparison : -comparison;
+        });
+        // 4. Return sorted IDs (caller handles pagination BEFORE loading entities)
+        return idValuePairs.map(p => p.id);
+    }
+    /**
+     * Get field value for a specific entity (helper for sorted queries)
+     *
+     * **IMPORTANT**: For timestamp fields (createdAt, updatedAt), this loads
+     * the ACTUAL value from entity metadata, NOT the bucketed index value.
+     * This is required because timestamp bucketing (1-minute precision) loses
+     * precision needed for accurate sorting.
+     *
+     * For non-timestamp fields, loads from the chunked sparse index without
+     * loading the full entity. This is critical for production-scale sorting.
+     *
+     * **Performance**:
+     * - Timestamp fields: O(1) metadata load from storage (cached)
+     * - Other fields: O(chunks) roaring bitmap lookup (typically 1-10 chunks)
+     *
+     * @param entityId - Entity UUID to get field value for
+     * @param field - Field name to retrieve (e.g., 'createdAt', 'title')
+     * @returns Promise<any> - Field value or undefined if not found
+     *
+     * @public (called from brainy.ts for sorted queries)
+     * @since v4.5.4
+     */
+    async getFieldValueForEntity(entityId, field) {
+        // For timestamp fields, load ACTUAL value from entity metadata
+        // (index has bucketed values which lose precision for sorting)
+        if (field === 'createdAt' || field === 'updatedAt' || field === 'accessed' || field === 'modified') {
+            try {
+                const noun = await this.storage.getNoun(entityId);
+                if (noun && noun.metadata) {
+                    return noun.metadata[field];
+                }
+            }
+            catch (err) {
+                // If metadata load fails, fall back to index (bucketed value)
+                console.warn(`[MetadataIndex] Failed to load ${field} from metadata for ${entityId}, using bucketed value`);
+            }
+        }
+        // For non-timestamp fields, use the sparse index (no bucketing issues)
+        const intId = this.idMapper.getInt(entityId);
+        if (intId === undefined) {
+            return undefined;
+        }
+        // Load sparse index for this field (cached via UnifiedCache)
+        const sparseIndex = await this.loadSparseIndex(field);
+        if (!sparseIndex) {
+            return undefined;
+        }
+        // Search through chunks to find which value this entity has
+        // Typically 1-10 chunks per field, so this is fast
+        for (const chunkId of sparseIndex.getAllChunkIds()) {
+            const chunk = await this.chunkManager.loadChunk(field, chunkId);
+            if (!chunk)
+                continue;
+            // Check each value's roaring bitmap for our entity ID
+            // Roaring bitmap .has() is O(1) with SIMD optimization
+            for (const [value, bitmap] of chunk.entries) {
+                if (bitmap.has(intId)) {
+                    // Found it! Denormalize the value (no bucketing for non-timestamps)
+                    return this.denormalizeValue(value, field);
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Denormalize a value (reverse of normalizeValue)
+     *
+     * Converts normalized/stringified values back to their original type.
+     * For most fields, this just parses numbers or returns strings as-is.
+     *
+     * **NOTE**: This is NOT used for timestamp sorting! Timestamp fields
+     * (createdAt, updatedAt) are loaded directly from entity metadata by
+     * getFieldValueForEntity() to avoid precision loss from bucketing.
+     *
+     * **Timestamp Bucketing (for range queries only)**:
+     * - Indexed as: Math.floor(timestamp / 60000) * 60000
+     * - Used for: Range queries (gte, lte) where 1-minute precision is acceptable
+     * - NOT used for: Sorting (requires exact millisecond precision)
+     *
+     * @param normalized - Normalized value string from index
+     * @param field - Field name (used for type inference)
+     * @returns Denormalized value in original type
+     *
+     * @private
+     * @since v4.5.4
+     */
+    denormalizeValue(normalized, field) {
+        // Try parsing as number (timestamps, integers, floats)
+        const asNumber = Number(normalized);
+        if (!isNaN(asNumber)) {
+            return asNumber;
+        }
+        // For strings, return as-is (already denormalized)
+        return normalized;
+    }
     /**
      * DEPRECATED - Old implementation for backward compatibility
      */

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.5.3",
+  "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",