@soulcraft/brainy 5.6.1 → 5.6.3

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [5.6.3](https://github.com/soulcraftlabs/brainy/compare/v5.6.2...v5.6.3) (2025-11-11)
+
+- docs: add entity versioning to fork section (3e81fd8)
+- docs: add asOf() time-travel to fork section (5706b71)
+
+
+### [5.6.2](https://github.com/soulcraftlabs/brainy/compare/v5.6.1...v5.6.2) (2025-11-11)
+
+- fix: update tests for Stage 3 CANONICAL taxonomy (42 nouns, 127 verbs) (c5dcdf6)
+- docs: restructure README for better new user flow (2d3f59e)
+
+
 ## [5.6.1](https://github.com/soulcraftlabs/brainy/compare/v5.6.0...v5.6.1) (2025-11-11)
 
 ### 🐛 Bug Fixes

package/README.md

@@ -32,6 +32,25 @@ await brain.init()
 
 ---
 
+## 👉 Choose Your Path
+
+**New to Brainy? Pick your starting point:**
+
+### 🚀 Path 1: I want to build something NOW
+**→ [Complete API Reference](docs/api/README.md)** ⭐ **Most developers start here** ⭐
+- Every method documented with examples
+- Quick start in 60 seconds
+- 1,870 lines of copy-paste ready code
+- **This is your primary resource**
+
+### 🧠 Path 2: I want to understand the big picture first
+**→ Keep reading below** for demos, architecture, and use cases
+
+### 📊 Path 3: I'm evaluating database options
+**→ Jump to [Why Revolutionary](#why-brainy-is-revolutionary)** or **[Benchmarks](#benchmarks)**
+
+---
+
 ## See It In Action
 
 **30 seconds to understand why Brainy is different:**
@@ -72,98 +91,96 @@ const results = await brain.find({
 
 ---
 
-## From Prototype to Planet Scale
+## Quick Start
 
-**The same API. Zero rewrites. Any scale.**
+```bash
+npm install @soulcraft/brainy
+```
 
-### 👤 **Individual Developer** → Weekend Prototype
+### Your First Knowledge Graph (60 seconds)
 
 ```javascript
-// Zero configuration - starts in memory
+import { Brainy, NounType, VerbType } from '@soulcraft/brainy'
+
 const brain = new Brainy()
 await brain.init()
 
-// Build your prototype in minutes
-// Change nothing when ready to scale
-```
+// Add knowledge
+const jsId = await brain.add({
+    data: "JavaScript is a programming language",
+    type: NounType.Concept,
+    metadata: { category: "language", year: 1995 }
+})
 
-**Perfect for:** Hackathons, side projects, rapid prototyping, learning AI concepts
+const nodeId = await brain.add({
+    data: "Node.js runtime environment",
+    type: NounType.Concept,
+    metadata: { category: "runtime", year: 2009 }
+})
 
-### 👥 **Small Team** → Production MVP (Thousands of Entities)
+// Create relationships
+await brain.relate({ from: nodeId, to: jsId, type: VerbType.Executes })
 
-```javascript
-// Add persistence - one line
-const brain = new Brainy({
-  storage: {
-    type: 'filesystem',
-    path: './brainy-data',
-    compression: true  // 60-80% space savings
-  }
+// Query with Triple Intelligence
+const results = await brain.find({
+    query: "JavaScript",                     // 🔍 Vector
+    where: { category: "language" },         // 📊 Document
+    connected: { from: nodeId, depth: 1 }    // 🕸️ Graph
 })
 ```
 
-**Perfect for:** Startups, MVPs, internal tools, team knowledge bases
-**Scale:** Thousands to hundreds of thousands of entities
-**Performance:** <5ms queries, sub-second imports
+**Done.** No configuration. No complexity. Production-ready from day one.
+
+**→ Ready to dive deeper? [Complete API Documentation](docs/api/README.md)** has every method with examples.
 
-### 🏢 **Growing Company** → Multi-Million Entity Scale
+---
+
+## From Prototype to Planet Scale
+
+**The same API. Zero rewrites. Any scale.**
+
+### 👤 Individual Developer → Weekend Prototype
+```javascript
+const brain = new Brainy()  // Zero config, starts in memory
+await brain.init()
+```
+**Perfect for:** Hackathons, side projects, prototyping, learning
 
+### 👥 Small Team → Production MVP
 ```javascript
-// Scale to cloud - same API
 const brain = new Brainy({
-  storage: {
-    type: 's3',
-    s3Storage: {
-      bucketName: 'my-knowledge-base',
-      region: 'us-east-1'
-    }
-  },
-  hnsw: { typeAware: true }  // 87% memory reduction
+  storage: { type: 'filesystem', path: './data', compression: true }
 })
 ```
+**Scale:** Thousands to hundreds of thousands • **Performance:** <5ms queries
 
-**Perfect for:** SaaS products, e-commerce, content platforms, enterprise apps
-**Scale:** Millions of entities
-**Performance:** <10ms queries, 12GB memory @ 10M entities
-**Features:** Auto-scaling, distributed storage, cost optimization (96% savings)
-
-### 🌍 **Enterprise / Planet Scale** → Billion+ Entities
-
+### 🏢 Growing Company → Multi-Million Scale
 ```javascript
-// Billion-scale - STILL the same API
 const brain = new Brainy({
-  storage: {
-    type: 'gcs',
-    gcsStorage: { bucketName: 'global-knowledge' }
-  },
-  hnsw: {
-    typeAware: true,
-    M: 32,
-    efConstruction: 400
-  }
+  storage: { type: 's3', s3Storage: { bucketName: 'my-kb', region: 'us-east-1' } },
+  hnsw: { typeAware: true }  // 87% memory reduction
 })
+```
+**Scale:** Millions of entities • **Performance:** <10ms queries, 12GB @ 10M entities
 
-// Enable intelligent archival
-await brain.storage.enableAutoclass({
-  terminalStorageClass: 'ARCHIVE'
+### 🌍 Enterprise → Billion+ Scale
+```javascript
+const brain = new Brainy({
+  storage: { type: 'gcs', gcsStorage: { bucketName: 'global-kb' } },
+  hnsw: { typeAware: true, M: 32, efConstruction: 400 }
 })
 ```
-
-**Perfect for:** Fortune 500, global platforms, research institutions, government
-**Scale:** Billions of entities (tested at 1B+)
-**Performance:** 18ms queries @ 1B scale, 50GB memory (87% reduction)
+**Scale:** Billions (tested @ 1B+) • **Performance:** 18ms queries, 50GB memory
 **Cost:** $138k/year → $6k/year with intelligent tiering (96% savings)
-**Features:** Sharding, replication, monitoring, enterprise SLAs
 
-### 🎯 **The Point**
+**→ [Capacity Planning Guide](docs/operations/capacity-planning.md)** | **[Cost Optimization](docs/operations/)**
 
-**Start simple. Scale infinitely. Never rewrite.**
+### 🎯 The Point
 
-Most systems force you to choose:
-- Simple but doesn't scale (SQLite, Redis)
-- Scales but complex (Kubernetes + 7 databases)
+**Start simple. Scale infinitely. Never rewrite.**
 
-**Brainy gives you both:** Starts simple as SQLite. Scales like Google.
+Most systems make you choose: Simple (SQLite) OR Scalable (Kubernetes + 7 databases).
+**Brainy gives you both.** Starts simple as SQLite. Scales like Google.
 
 ---
 
@@ -219,9 +236,9 @@ Brainy automatically:
 
 **You write business logic. Brainy handles infrastructure.**
 
-### 🚀 **Instant Fork™** — Git for Databases (v5.0.0)
+### 🚀 **Git-Style Version Control** — Database & Entity Level (v5.0.0+)
 
-**Clone your entire database in <100ms. Merge back when ready. Full Git-style workflow.**
+**Clone your entire database in <100ms. Track every entity change. Full Git-style workflow.**
 
 ```javascript
 // Fork instantly - Snowflake-style copy-on-write
@@ -240,19 +257,44 @@ const result = await brain.merge('test-migration', 'main', {
 })
 
 console.log(result)  // { added: 1, modified: 0, conflicts: 0 }
+
+// Time-travel: Query database at any past commit (read-only)
+const commits = await brain.getHistory({ limit: 10 })
+const snapshot = await brain.asOf(commits[5].id)
+const pastResults = await snapshot.find({ query: 'historical data' })
+await snapshot.close()
+
+// Entity versioning: Track changes to individual entities (v5.3.0+)
+const userId = await brain.add({ type: 'user', data: { name: 'Alice' } })
+await brain.versions.save(userId, { tag: 'v1.0', description: 'Initial profile' })
+
+await brain.update(userId, { data: { name: 'Alice Smith', role: 'admin' } })
+await brain.versions.save(userId, { tag: 'v2.0', description: 'Added role' })
+
+// Compare versions or restore previous state
+const diff = await brain.versions.compare(userId, 1, 2)  // See what changed
+await brain.versions.restore(userId, 1)  // Restore v1.0
 ```
 
-**NEW in v5.0.0:**
+**Database-level version control (v5.0.0):**
 - ✅ `fork()` - Instant clone in <100ms
 - ✅ `merge()` - Merge with conflict resolution
 - ✅ `commit()` - Snapshot state
+- ✅ `asOf()` - Time-travel queries (query at any commit)
 - ✅ `getHistory()` - View commit history
 - ✅ `checkout()`, `listBranches()` - Full branch management
 - ✅ CLI support for all features
 
+**Entity-level version control (v5.3.0):**
+- ✅ `versions.save()` - Save entity snapshots with tags
+- ✅ `versions.restore()` - Restore previous versions
+- ✅ `versions.compare()` - Diff between versions
+- ✅ `versions.list()` - View version history
+- ✅ Automatic deduplication (content-addressable storage)
+
 **How it works:** Snowflake-style COW shares HNSW index structures, copying only modified nodes (10-20% memory overhead).
 
-**Perfect for:** Safe migrations, A/B testing, feature branches, distributed development
+**Perfect for:** Safe migrations, A/B testing, feature branches, distributed development, time-travel debugging, audit trails, document versioning, compliance tracking
 
 [→ See Full Documentation](docs/features/instant-fork.md)
 
@@ -296,48 +338,6 @@ Every asset knows its relationships. Intelligent tagging, similarity-based disco
 
 ---
 
-## Quick Start
-
-```bash
-npm install @soulcraft/brainy
-```
-
-### Your First Knowledge Graph (60 seconds)
-
-```javascript
-import { Brainy, NounType, VerbType } from '@soulcraft/brainy'
-
-const brain = new Brainy()
-await brain.init()
-
-// Add knowledge
-const jsId = await brain.add({
-    data: "JavaScript is a programming language",
-    type: NounType.Concept,
-    metadata: { category: "language", year: 1995 }
-})
-
-const nodeId = await brain.add({
-    data: "Node.js runtime environment",
-    type: NounType.Concept,
-    metadata: { category: "runtime", year: 2009 }
-})
-
-// Create relationships
-await brain.relate({ from: nodeId, to: jsId, type: VerbType.Executes })
-
-// Query with Triple Intelligence
-const results = await brain.find({
-    query: "JavaScript",                     // 🔍 Vector
-    where: { category: "language" },         // 📊 Document
-    connected: { from: nodeId, depth: 1 }    // 🕸️ Graph
-})
-```
-
-**Done.** No configuration. No complexity. Production-ready from day one.
-
----
-
 ## Core Features
 
 ### 🧠 **Natural Language Queries**
@@ -355,6 +355,8 @@ await brain.find({
 })
 ```
 
+**→ [See all query methods in API Reference](docs/api/README.md#search--query)**
+
 ### 🌐 **Virtual Filesystem** — Intelligent File Management
 
 Build file explorers and IDEs that never crash:
@@ -566,40 +568,60 @@ brainy search "programming"
 
 ---
 
-## Documentation
+## 📖 Complete Documentation
 
-### 🚀 Getting Started
-- **[API Reference](docs/api/README.md)** — Complete API documentation for all features
-- **[v4.0.0 Migration Guide](docs/MIGRATION-V3-TO-V4.md)** — Upgrade from v3 (backward compatible)
+**For most developers:** Start with the **[Complete API Reference](docs/api/README.md)** ⭐
 
-### 🧠 Core Concepts
-- **[Triple Intelligence Architecture](docs/architecture/triple-intelligence.md)** — How vector + graph + document work together
-- **[Natural Language Queries](docs/guides/natural-language.md)** — Using find() effectively
-- **[API Reference](docs/api/README.md)** — Complete API documentation
-- **[Noun-Verb Taxonomy](docs/architecture/noun-verb-taxonomy.md)** — The universal type system
+This comprehensive guide includes:
+- ✅ Every method with parameters, returns, and examples
+- ✅ Quick start in 60 seconds
+- ✅ Core CRUD → Advanced features (branching, versioning, time-travel)
+- ✅ TypeScript types and patterns
+- ✅ 1,870 lines of copy-paste ready code
+
+---
+
+### 🎯 Essential Reading (Start Here)
+
+1. **[📖 Complete API Reference](docs/api/README.md)** ⭐ **START HERE** ⭐
+   - Your primary resource for building with Brainy
+   - Every method documented with working examples
 
-### 🏗️ Architecture & Scaling
+2. **[Natural Language Queries](docs/guides/natural-language.md)**
+   - Master the `find()` method and Triple Intelligence queries
+
+3. **[v4.0.0 Migration Guide](docs/MIGRATION-V3-TO-V4.md)**
+   - Upgrading from v3 (100% backward compatible)
+
+### 🧠 Core Concepts & Architecture
+
+- **[Triple Intelligence Architecture](docs/architecture/triple-intelligence.md)** — How vector + graph + document work together
+- **[Noun-Verb Taxonomy](docs/architecture/noun-verb-taxonomy.md)** — The universal type system (42 nouns × 127 verbs)
 - **[Architecture Overview](docs/architecture/overview.md)** — System design and components
 - **[Data Storage Architecture](docs/architecture/data-storage-architecture.md)** — Type-aware indexing and HNSW
-- **[Capacity Planning](docs/operations/capacity-planning.md)** — Memory, storage, and scaling guidelines
 
 ### ☁️ Production & Operations
+
 - **[Cloud Deployment Guide](docs/deployment/CLOUD_DEPLOYMENT_GUIDE.md)** — Deploy to AWS, GCS, Azure
-- **[AWS Cost Optimization](docs/operations/cost-optimization-aws-s3.md)** | **[GCS](docs/operations/cost-optimization-gcs.md)** | **[Azure](docs/operations/cost-optimization-azure.md)** | **[Cloudflare R2](docs/operations/cost-optimization-cloudflare-r2.md)**
+- **[Capacity Planning](docs/operations/capacity-planning.md)** — Memory, storage, and scaling to billions
+- **Cost Optimization:** **[AWS S3](docs/operations/cost-optimization-aws-s3.md)** | **[GCS](docs/operations/cost-optimization-gcs.md)** | **[Azure](docs/operations/cost-optimization-azure.md)** | **[Cloudflare R2](docs/operations/cost-optimization-cloudflare-r2.md)**
 
 ### 🌐 Framework Integration
+
 - **[Framework Integration Guide](docs/guides/framework-integration.md)** — React, Vue, Angular, Svelte
 - **[Next.js Integration](docs/guides/nextjs-integration.md)**
 - **[Vue.js Integration](docs/guides/vue-integration.md)**
 
-### 🌳 Virtual Filesystem
+### 🌳 Virtual Filesystem (VFS)
+
 - **[VFS Quick Start](docs/vfs/QUICK_START.md)** — Build file explorers that never crash
 - **[VFS Core Documentation](docs/vfs/VFS_CORE.md)**
-- **[Semantic VFS Guide](docs/vfs/SEMANTIC_VFS.md)**
+- **[Semantic VFS Guide](docs/vfs/SEMANTIC_VFS.md)** — AI-powered file navigation
 - **[Neural Extraction API](docs/vfs/NEURAL_EXTRACTION.md)**
 
-### 📦 Data Import
-- **[Import Anything Guide](docs/guides/import-anything.md)** — CSV, Excel, PDF, URLs
+### 📦 Data Import & Processing
+
+- **[Import Anything Guide](docs/guides/import-anything.md)** — CSV, Excel, PDF, URLs with auto-detection
 
 ---
 

package/dist/augmentations/typeMatching/brainyTypes.js

@@ -31,6 +31,14 @@ const NOUN_TYPE_DESCRIPTIONS = {
     [NounType.Organism]: 'organism animal plant bacteria fungi species living biological life creature being microorganism',
     // Material Types (1) - Stage 3
     [NounType.Substance]: 'substance material matter chemical element compound liquid gas solid molecule atom material',
+    // Property & Quality Types (1) - Stage 3
+    [NounType.Quality]: 'quality property attribute characteristic feature aspect trait dimension parameter value',
+    // Temporal Types (1) - Stage 3
+    [NounType.TimeInterval]: 'timeInterval period duration span range epoch era season quarter interval window',
+    // Functional Types (1) - Stage 3
+    [NounType.Function]: 'function purpose role capability capacity utility objective goal aim intent',
+    // Informational Types (1) - Stage 3
+    [NounType.Proposition]: 'proposition statement claim assertion declaration premise conclusion hypothesis theory',
     // Digital/Content Types
     [NounType.Document]: 'document file report article paper text pdf word contract agreement record documentation',
     [NounType.Media]: 'media image photo video audio music podcast multimedia graphic visualization animation',
@@ -59,7 +67,18 @@ const NOUN_TYPE_DESCRIPTIONS = {
     [NounType.Regulation]: 'regulation law rule policy standard compliance requirement guideline ordinance statute',
     // Technical Infrastructure Types
     [NounType.Interface]: 'interface API endpoint protocol specification contract schema definition connection',
-    [NounType.Resource]: 'resource infrastructure server database storage compute memory bandwidth capacity asset'
+    [NounType.Resource]: 'resource infrastructure server database storage compute memory bandwidth capacity asset',
+    // Custom/Extensible (1) - Stage 3
+    [NounType.Custom]: 'custom special unique particular specific domain-specific specialized tailored bespoke',
+    // Social Structures (3) - Stage 3
+    [NounType.SocialGroup]: 'socialGroup community tribe clan network circle collective society crowd gathering',
+    [NounType.Institution]: 'institution establishment foundation organization system structure framework tradition practice',
+    [NounType.Norm]: 'norm convention standard custom tradition protocol etiquette rule practice expectation',
+    // Information Theory (2) - Stage 3
+    [NounType.InformationContent]: 'informationContent story narrative knowledge data schema pattern model structure',
+    [NounType.InformationBearer]: 'informationBearer carrier medium vehicle signal token representation document',
+    // Meta-Level (1) - Stage 3
+    [NounType.Relationship]: 'relationship connection relation association link bond tie interaction dynamic'
 };
 const VERB_TYPE_DESCRIPTIONS = {
     // Core Relationship Types
@@ -389,6 +408,16 @@ export class BrainyTypes {
     generateReasoning(obj, selectedType, typeKind) {
         const descriptions = typeKind === 'noun' ? NOUN_TYPE_DESCRIPTIONS : VERB_TYPE_DESCRIPTIONS;
         const typeDesc = descriptions[selectedType];
+        // Handle missing descriptions gracefully
+        if (!typeDesc) {
+            if (typeKind === 'noun') {
+                const fields = Object.keys(obj).slice(0, 3).join(', ');
+                return `Matched to ${selectedType} based on semantic similarity and object fields: ${fields}`;
+            }
+            else {
+                return `Matched to ${selectedType} based on semantic similarity and relationship context`;
+            }
+        }
         if (typeKind === 'noun') {
             const fields = Object.keys(obj).slice(0, 3).join(', ');
             return `Matched to ${selectedType} based on semantic similarity to "${typeDesc.split(' ').slice(0, 5).join(' ')}..." and object fields: ${fields}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "5.6.1",
+  "version": "5.6.3",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. Stage 3 CANONICAL: 42 nouns × 127 verbs covering 96-97% of all human knowledge.",
   "main": "dist/index.js",
   "module": "dist/index.js",