rust-kgdb 0.6.38 → 0.6.40

package/DESIGN.md

@@ -0,0 +1,361 @@
+# HyperMind Design Document
+
+## Architecture Overview
+
+HyperMind is a neuro-symbolic AI framework that combines LLM planning with deterministic database execution. Unlike traditional AI agents that rely entirely on LLM outputs, HyperMind uses the LLM as a **planner** while executing queries against real data.
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         HYPERMIND ARCHITECTURE                               │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │
+│  │   User      │    │   Schema    │    │    LLM      │    │   Typed     │  │
+│  │   Query     │ -> │   Context   │ -> │   Planner   │ -> │   Tools     │  │
+│  └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘  │
+│                            │                                     │          │
+│                            │                                     ▼          │
+│                            │                            ┌─────────────┐     │
+│                            │                            │  Database   │     │
+│                            │                            │  Execution  │     │
+│                            │                            └─────────────┘     │
+│                            │                                     │          │
+│                            ▼                                     ▼          │
+│                     ┌─────────────────────────────────────────────────┐     │
+│                     │              Reasoning Trace                    │     │
+│                     │  (Every step recorded with cryptographic hash)  │     │
+│                     └─────────────────────────────────────────────────┘     │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Core Components
+
+### 1. Schema Context (Auto-Extracted)
+
+HyperMind automatically extracts schema from your data:
+
+```javascript
+// SchemaContext is a live object, not a string
+SchemaContext = {
+  classes: Set(['Professor', 'Student', 'Course', 'Department']),
+  properties: Map({
+    'teacherOf': { domain: 'Professor', range: 'Course' },
+    'emailAddress': { domain: 'Person', range: 'string' },
+    'worksFor': { domain: 'Professor', range: 'Department' }
+  }),
+  aliases: Map({
+    'teacher': 'teacherOf',
+    'email': 'emailAddress',
+    'works_for': 'worksFor'
+  })
+}
+```
+
+**Why this matters:** The LLM sees your actual data structure, not a generic prompt.
+
+### 2. Predicate Resolver (Grammar-Based)
+
+When LLM generates incorrect predicates, the resolver fixes them:
+
+```
+LLM Output: SELECT ?x WHERE { ?x teacher ?y }
+                               ↑
+                        Wrong predicate!
+
+Resolver Process:
+1. Parse with pest SPARQL grammar (not regex)
+2. Extract predicate: "teacher"
+3. Check schema: "teacher" not found
+4. Ensemble similarity matching:
+   - Jaro-Winkler("teacher", "teacherOf") = 0.89
+   - N-gram overlap = 0.75
+   - Porter stem match = true
+5. Resolve: "teacher" → "teacherOf"
+
+Fixed Output: SELECT ?x WHERE { ?x teacherOf ?y }
+                                   ↑
+                            Correct predicate!
+```
+
+**Benchmark result:** This adds +14.3 percentage points accuracy (71.4% → 85.7%)
+
+### 3. Typed Tool Registry
+
+Every tool has typed input/output signatures:
+
+```javascript
+TOOL_REGISTRY = {
+  'kg.sparql.query': {
+    input: 'SPARQLQuery',
+    output: 'BindingSet',
+    validate: (query) => parseAndValidate(query, schema)
+  },
+  'kg.datalog.apply': {
+    input: 'DatalogRules',
+    output: 'InferredFacts',
+    validate: (rules) => checkPredicatesExist(rules, schema)
+  },
+  'kg.motif.find': {
+    input: 'MotifPattern',
+    output: 'MatchSet',
+    validate: (pattern) => parseMotifSyntax(pattern)
+  }
+}
+```
+
+**Why this matters:** Invalid tool combinations are rejected before execution.
+
+### 4. Reasoning Trace (Audit Trail)
+
+Every answer includes a complete derivation:
+
+```javascript
+{
+  answer: "Provider PROV-2847 has risk score 0.91",
+  reasoningTrace: [
+    {
+      step: 1,
+      tool: "kg.sparql.query",
+      input: "SELECT ?p ?s WHERE { ?p :riskScore ?s . FILTER(?s > 0.8) }",
+      output: [{ p: "PROV-2847", s: 0.91 }],
+      duration: "2.3ms"
+    }
+  ],
+  hash: "sha256:8f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c"
+}
+```
+
+**Why this matters:** Same question = Same answer = Same hash. Auditable and reproducible.
+
+---
+
+## Mathematical Foundations
+
+### Spivak's Ologs (Category Theory)
+
+Schema represented as a category:
+- **Objects** = Classes (Professor, Course, Student)
+- **Morphisms** = Properties (teacherOf, enrolledIn)
+- **Composition** = Property paths (Professor → Course → Department)
+
+```
+Professor ──teacherOf──▶ Course ──offeredBy──▶ Department
+    │                                              │
+    └────────────worksFor──────────────────────────┘
+```
+
+### Metric Space Similarity
+
+Predicate resolution uses proper metric space distances:
+
+```
+d(x, y) ≥ 0                    (non-negativity)
+d(x, y) = 0 ⟺ x = y           (identity)
+d(x, y) = d(y, x)              (symmetry)
+d(x, z) ≤ d(x, y) + d(y, z)    (triangle inequality)
+
+Ensemble similarity combines:
+- Jaro-Winkler distance (character-level)
+- N-gram overlap (substring-level)
+- Jaccard coefficient (token-level)
+- Porter stemming (morphological)
+```
+
+### Curry-Howard Correspondence
+
+Proofs are programs, types are propositions:
+
+```
+Query : SPARQLQuery           (type = proposition)
+Result : BindingSet           (type = proposition)
+Execution : Query → Result    (proof = program)
+
+The reasoning trace IS the proof that the answer is correct.
+```
+
+---
+
+## Benchmark Methodology
+
+### Test Setup
+
+- **Dataset:** LUBM (Lehigh University Benchmark)
+- **Size:** 3,272 triples, 30 OWL classes, 23 properties
+- **Model:** GPT-4o
+- **Queries:** 7 natural language questions
+- **Validation:** Regex patterns checking for correct predicates
+
+### Test Queries
+
+```python
+TEST_QUERIES = [
+  {"id": "A1", "question": "Find all teachers", "correct": "teacherOf"},
+  {"id": "A2", "question": "Get student emails", "correct": "emailAddress"},
+  {"id": "A3", "question": "Find faculty members", "correct": "Professor"},
+  {"id": "S1", "question": "Count professors"},
+  {"id": "S2", "question": "Find graduate students"},
+  {"id": "M1", "question": "Find professors who work for departments"},
+  {"id": "E1", "question": "Find professors with no publications"}
+]
+```
+
+### Results (Verified December 2025)
+
+| Stage | Accuracy | Tests Passed | Improvement |
+|-------|----------|--------------|-------------|
+| No Schema | 0-14% | 0-1/7 | Baseline |
+| With Schema | 71.4% | 5/7 | +66.7 pp |
+| With HyperMind | 85.7% | 6/7 | +14.3 pp |
+
+**Specific fix:** Query A1 used "teacher" instead of "teacherOf". Predicate resolver corrected this.
+
+**Remaining failure:** Query S2 - LLM adds "Here is..." text (formatting issue, not predicate issue).
+
+---
+
+## Comparison with Other Frameworks
+
+### LangChain
+
+```
+Architecture: Prompt Template → LLM → Text Output
+Execution: None (LLM output is final answer)
+Validation: None
+Audit Trail: None
+```
+
+### DSPy
+
+```
+Architecture: Signature → LLM → Structured Output
+Execution: None (LLM output is final answer)
+Validation: Output structure only
+Audit Trail: None
+```
+
+### HyperMind
+
+```
+Architecture: Schema → LLM Planner → Typed Tools → Database → Verified Answer
+Execution: Real SPARQL/Datalog on actual data
+Validation: Schema + Type + Predicate resolution
+Audit Trail: Full reasoning trace with hash
+```
+
+---
+
+## API Reference
+
+### HyperMindAgent
+
+```typescript
+class HyperMindAgent {
+  constructor(options: {
+    kg: GraphDB,              // Your knowledge graph
+    model?: string,           // 'gpt-4o' | 'claude-3-opus'
+    apiKey?: string,          // LLM API key
+    threshold?: number        // Predicate similarity threshold (default: 0.6)
+  })
+
+  async call(prompt: string): Promise<{
+    answer: string,
+    reasoningTrace: Step[],
+    hash: string
+  }>
+}
+```
+
+### OlogSchema
+
+```typescript
+class OlogSchema {
+  constructor()
+  withNamespace(ns: string): void
+  addClass(name: string): void
+  addProperty(name: string, domain: string, range: string, aliases?: string[]): void
+  build(): void
+  hasClass(name: string): boolean
+  hasPredicate(name: string): boolean
+}
+```
+
+### PredicateResolverService
+
+```typescript
+class PredicateResolverService {
+  constructor(schema: OlogSchema, threshold?: number)
+  resolve(userPredicate: string): string      // Returns corrected predicate
+  resolveQuery(sparql: string): string        // Resolves all predicates in query
+}
+```
+
+---
+
+## Performance Characteristics
+
+| Metric | Value | Notes |
+|--------|-------|-------|
+| Triple Lookup | 2.78 µs | Measured with Criterion |
+| Predicate Resolution | <1 ms | Per predicate |
+| Query Execution | <100 ms | Typical SPARQL query |
+| Memory per Triple | 24 bytes | Best-in-class |
+
+---
+
+## Security Model
+
+### Capability-Based Sandbox
+
+```javascript
+const agent = new HyperMindAgent({
+  kg: db,
+  sandbox: {
+    capabilities: ['ReadKG', 'ExecuteTool'],  // No WriteKG = read-only
+    fuelLimit: 1_000_000,                     // CPU budget
+    allowedGraphs: ['http://insurance.org/']  // Graph-level access control
+  }
+})
+```
+
+### What's Prevented
+
+- SQL injection (typed tools, not string concatenation)
+- Prompt injection (schema limits what can be queried)
+- Runaway execution (fuel metering)
+- Unauthorized access (capability-based)
+
+---
+
+## Limitations
+
+1. **Predicate resolver is not magic:** Only fixes predicates similar to schema terms
+2. **LLM formatting issues:** Can't fix when LLM adds explanatory text
+3. **Schema required:** Must have schema to validate against
+4. **Single database:** Currently supports one knowledge graph per agent
+
+---
+
+## Roadmap
+
+- [ ] Multi-database federation
+- [ ] Custom similarity functions
+- [ ] Streaming results
+- [ ] Fine-tuned predicate resolution model
+
+---
+
+## References
+
+1. Spivak, D. (2012). "Ologs: A Categorical Framework for Knowledge Representation"
+2. Jaro, M. (1989). "Advances in Record-Linkage Methodology"
+3. Porter, M. (1980). "An Algorithm for Suffix Stripping"
+4. Curry-Howard Correspondence (1969)
+
+---
+
+## License
+
+Apache 2.0

package/IMPLEMENTATION_GUIDE.md

@@ -0,0 +1,404 @@
+# TypeScript SDK Implementation Guide (v0.6.17)
+
+## Plain English Summary
+
+**What this SDK does**: Lets you build AI agents that query your data and give verifiable answers.
+
+**Key components**:
+- **GraphDB** - Store and query your data (like a database)
+- **HyperMindAgent** - AI that answers questions about your data
+- **Reasoning Trace** - Shows exactly how each answer was derived
+
+**Why it matters**: Unlike vanilla LLMs that hallucinate, this gives you answers you can trust and audit.
+
+---
+
+## Overview
+
+The TypeScript SDK uses **NAPI-RS** for native Rust bindings with zero-copy performance. Version 0.6.17 includes the complete HyperMind AI framework for building agents that give verifiable answers.
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          ARCHITECTURE OVERVIEW                               │
+│                                                                              │
+│  YOUR APPLICATION (Node.js / TypeScript)                                    │
+│      │                                                                       │
+│      ▼                                                                       │
+│  ┌───────────────────────────────────────────────────────────────────────┐  │
+│  │  index.js - Entry Point                                                │  │
+│  │  • Platform detection (darwin/linux/win32 × x64/arm64)                │  │
+│  │  • Native binding loader                                               │  │
+│  │  • HyperMind framework exports                                         │  │
+│  └───────────────────────────────────────────────────────────────────────┘  │
+│      │                           │                                          │
+│      ▼                           ▼                                          │
+│  ┌─────────────────────┐    ┌─────────────────────────────────────────┐    │
+│  │  Native NAPI-RS     │    │  hypermind-agent.js                      │    │
+│  │  (Rust → Node.js)   │    │  (Pure JavaScript Framework)             │    │
+│  │                     │    │                                          │    │
+│  │  • GraphDb          │    │  • HyperMindAgent                        │    │
+│  │  • GraphFrame       │    │  • LLMPlanner                            │    │
+│  │  • EmbeddingService │    │  • SchemaAwareGraphDB                    │    │
+│  │  • DatalogProgram   │    │  • SchemaContext                         │    │
+│  │  • pregelShortestPaths│  │  • MemoryManager                         │    │
+│  │                     │    │  • WasmSandbox                           │    │
+│  │  ~47MB native addon │    │  • ProofDAG                              │    │
+│  └─────────────────────┘    └─────────────────────────────────────────┘    │
+│                                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Core Components
+
+### 1. Native NAPI-RS Layer (`native/rust-kgdb-napi/`)
+
+**Location**: `native/rust-kgdb-napi/src/lib.rs`
+
+The Rust layer provides high-performance database operations:
+
+```rust
+// Core exports
+#[napi]
+pub struct GraphDb { /* ... */ }
+
+#[napi]
+impl GraphDb {
+    #[napi(constructor)]
+    pub fn new(base_uri: String) -> Self { /* ... */ }
+
+    #[napi]
+    pub fn load_ttl(&mut self, ttl: String, graph: Option<String>) -> Result<()> { /* ... */ }
+
+    #[napi]
+    pub fn query_select(&self, sparql: String) -> Result<Vec<QueryResult>> { /* ... */ }
+
+    #[napi]
+    pub fn count_triples(&self) -> Result<u32> { /* ... */ }
+}
+```
+
+**Exported Classes**:
+- `GraphDb` - Core RDF/SPARQL database
+- `GraphFrame` - Graph analytics with DataFusion
+- `EmbeddingService` - Vector similarity with HNSW
+- `DatalogProgram` - Rule-based reasoning
+- `pregelShortestPaths` - Pregel BSP algorithm
+
+### 2. HyperMind Framework Layer (`hypermind-agent.js`)
+
+**Location**: `hypermind-agent.js` (~4000 lines)
+
+Pure JavaScript implementation of the neuro-symbolic AI framework:
+
+```javascript
+// Key classes and their roles
+class HyperMindAgent {
+  constructor({ kg, name, model, scope, memory }) { /* ... */ }
+  async call(prompt) { /* Returns ProofDAG-backed response */ }
+}
+
+class LLMPlanner {
+  constructor(kg, options) { /* ... */ }
+  extractSchema() { /* Returns schema as category */ }
+  async plan(prompt) { /* Returns typed execution plan */ }
+}
+
+class SchemaContext {
+  // Auto-extracts your data structure
+  // Knows what classes and properties exist
+}
+
+class ProofDAG {
+  // Records how each answer was derived
+  // Includes hash for reproducibility
+}
+```
+
+### 3. Entry Point (`index.js`)
+
+**Location**: `index.js` (~167 lines)
+
+Platform detection and unified exports:
+
+```javascript
+function loadNativeBinding() {
+  const platform = os.platform()  // darwin, linux, win32
+  const arch = os.arch()          // x64, arm64
+
+  // Load correct .node file for platform
+  if (platform === 'darwin' && arch === 'x64') {
+    return require('./rust-kgdb-napi.darwin-x64.node')
+  }
+  // ... other platforms
+}
+
+module.exports = {
+  // Native exports
+  GraphDB, GraphDb, GraphFrame, EmbeddingService, DatalogProgram,
+
+  // HyperMind exports
+  HyperMindAgent, LLMPlanner, SchemaContext, ProofDAG,
+  SchemaAwareGraphDB, MemoryManager, WasmSandbox, AgentScope,
+}
+```
+
+### 4. Type Definitions (`index.d.ts`)
+
+**Location**: `index.d.ts` (~425 lines)
+
+Complete TypeScript types for all APIs:
+
+```typescript
+export class GraphDB {
+  constructor(baseUri: string)
+  loadTtl(ttl: string, graph?: string | null): void
+  querySelect(sparql: string): QueryResult[]
+  countTriples(): number
+}
+
+export class HyperMindAgent {
+  constructor(options: HyperMindAgentOptions)
+  call(prompt: string): Promise<AgentResponse>
+}
+
+export interface ProofDAG {
+  root: string
+  derivations: Derivation[]
+  hash: string
+  timestamp: string
+}
+```
+
+## Technical Foundations
+
+> **Plain English**: This section explains WHY HyperMind gives reliable answers. Skip to "Adding New Features" if you just want to use the SDK.
+
+### Schema Awareness (How the system knows your data structure)
+
+The SDK automatically extracts your data structure:
+- **Classes** = Types of things in your data (Person, Claim, Provider)
+- **Properties** = Relationships between things (hasName, belongsTo)
+- **Validation** = Ensures queries only reference things that exist
+
+```javascript
+class SchemaContext {
+  constructor() {
+    this.classes = new Set()      // Objects in category
+    this.properties = new Map()   // Morphisms: predicate → {domain, range}
+  }
+
+  // Functor: Transform between schemas
+  static merge(schema1, schema2) { /* ... */ }
+
+  // Natural transformation: BYOO ontology loading
+  static fromOntology(ttl) { /* ... */ }
+}
+```
+
+### Typed Tools (How tools validate inputs/outputs)
+
+Every tool has a defined input and output type:
+
+```javascript
+const TOOL_REGISTRY = {
+  'kg.sparql.query': {
+    input: 'Query',
+    output: 'BindingSet',
+    description: 'Execute SPARQL SELECT query'
+  },
+  'kg.datalog.apply': {
+    input: 'RuleSet',
+    output: 'InferredFacts',
+    description: 'Apply Datalog rules'
+  },
+  'kg.embeddings.search': {
+    input: 'Entity',
+    output: 'SimilarEntities',
+    description: 'Find semantically similar entities'
+  }
+}
+
+class TypeId {
+  static isCompatible(output, input) {
+    // Validates morphism composition
+    return typeGraph[output]?.includes(input)
+  }
+}
+```
+
+### Reasoning Trace (How answers are verified)
+
+Every answer includes a record of how it was derived:
+
+```javascript
+class ProofDAG {
+  constructor() {
+    this.nodes = []     // Derivation steps
+    this.edges = []     // Dependency links
+    this.root = null    // Final conclusion
+  }
+
+  addDerivation(tool, input, output, result) {
+    // Γ ⊢ tool(input) : output
+    this.nodes.push({ tool, input, output, result, timestamp: Date.now() })
+  }
+
+  computeHash() {
+    // Deterministic hash for reproducibility
+    return crypto.createHash('sha256')
+      .update(JSON.stringify(this.nodes))
+      .digest('hex')
+  }
+}
+```
+
+## Adding New Features
+
+### Adding a New Native Function
+
+1. **Add Rust implementation** in `native/rust-kgdb-napi/src/lib.rs`:
+
+```rust
+#[napi]
+pub fn my_new_function(arg: String) -> Result<String> {
+    // Implementation
+    Ok(format!("Result: {}", arg))
+}
+```
+
+2. **Add TypeScript types** in `index.d.ts`:
+
+```typescript
+export function myNewFunction(arg: string): string
+```
+
+3. **Export in `index.js`**:
+
+```javascript
+const { myNewFunction } = loadNativeBinding()
+module.exports = { myNewFunction }
+```
+
+4. **Add tests** in `test-all-features.js`:
+
+```javascript
+test('myNewFunction works correctly', () => {
+  const result = myNewFunction('test')
+  assert.strictEqual(result, 'Result: test')
+})
+```
+
+### Adding a New HyperMind Tool
+
+1. **Register in TOOL_REGISTRY** (`hypermind-agent.js`):
+
+```javascript
+const TOOL_REGISTRY = {
+  // ... existing tools
+  'kg.custom.myTool': {
+    input: 'InputType',
+    output: 'OutputType',
+    description: 'What this tool does'
+  }
+}
+```
+
+2. **Implement execution** in HyperMindAgent:
+
+```javascript
+async _executeTool(toolName, args) {
+  switch (toolName) {
+    case 'kg.custom.myTool':
+      return this._executeMyTool(args)
+    // ... other tools
+  }
+}
+
+_executeMyTool(args) {
+  // Implementation
+  return { result: /* ... */ }
+}
+```
+
+3. **Add to ProofDAG derivation**:
+
+```javascript
+this.proofDAG.addDerivation('kg.custom.myTool', args, result)
+```
+
+## Testing
+
+### Run All Tests
+
+```bash
+# 42 feature tests
+npm test
+
+# 217 Jest tests (includes HyperMind tests)
+npm run test:jest
+```
+
+### Test Structure
+
+```
+tests/
+├── regression.test.ts    # Core GraphDB tests (28 tests)
+├── graphframes.test.ts   # GraphFrame tests
+├── embeddings.test.ts    # EmbeddingService tests
+├── datalog.test.ts       # Datalog tests
+├── pregel.test.ts        # Pregel tests
+└── hypermind-agent.test.ts # HyperMind framework tests (59 tests)
+```
+
+## Build Commands
+
+```bash
+# Build native addon (produces .node file)
+npm run build
+
+# Build debug version
+npm run build:debug
+
+# Under the hood:
+napi build --platform --release native/rust-kgdb-napi
+```
+
+## Platform Support
+
+| Platform | Architecture | File |
+|----------|--------------|------|
+| macOS | Intel (x64) | `rust-kgdb-napi.darwin-x64.node` |
+| macOS | Apple Silicon (arm64) | `rust-kgdb-napi.darwin-arm64.node` |
+| Linux | x64 | `rust-kgdb-napi.linux-x64-gnu.node` |
+| Linux | ARM64 | `rust-kgdb-napi.linux-arm64-gnu.node` |
+| Windows | x64 | `rust-kgdb-napi.win32-x64-msvc.node` |
+
+## Performance Characteristics
+
+| Operation | Time | Notes |
+|-----------|------|-------|
+| Triple lookup | 2.78 µs | 35x faster than RDFox |
+| Bulk insert | 146K/sec | Zero-copy semantics |
+| SPARQL query | <100 µs | Cost-based optimizer |
+| Schema extraction | 10-50 ms | Cached 5 minutes |
+| ProofDAG hash | <1 ms | SHA-256 |
+
+## Version History
+
+- **v0.6.16**: "Power of Abstraction" introduction, mathematical foundations diagram
+- **v0.6.15**: ProofDAG visualization, LLM evaluation solution, deep dives
+- **v0.6.14**: Industry benchmarks, control plane architecture
+- **v0.6.13**: Schema-Aware GraphDB, Context Theory, BYOO
+- **v0.6.12**: Schema Caching with TTL
+- **v0.6.11**: Context Theory foundation
+
+## Key Files Reference
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| `native/rust-kgdb-napi/src/lib.rs` | ~700 | NAPI-RS Rust bindings |
+| `hypermind-agent.js` | ~4050 | HyperMind framework |
+| `index.js` | ~167 | Entry point + loader |
+| `index.d.ts` | ~425 | TypeScript definitions |
+| `test-all-features.js` | ~500 | 42 feature tests |
+| `tests/*.test.ts` | ~2000 | 217 Jest tests |

package/README.md

@@ -234,7 +234,7 @@ OUR APPROACH:       User → Proxied Objects → WASM Sandbox → RPC → Real S
                     │   └── Full audit log: every action traced
                     │
                     ├── rust-kgdb via NAPI-RS (Native RPC)
-                    │   └── 2.78µs lookups (not HTTP round-trips)
+                    │   └── 449ns lookups (not HTTP round-trips)
                     │   └── Zero-copy data transfer
                     │
                     └── ProofDAG (Proof Theory)
@@ -251,7 +251,7 @@ OUR APPROACH:       User → Proxied Objects → WASM Sandbox → RPC → Real S
 
 **Why Proxied Objects + WASM Sandbox**:
 - **Proxied Objects**: SchemaContext, TOOL_REGISTRY are live objects with methods, not serialized JSON
-- **RPC to Real Systems**: Queries execute on rust-kgdb (2.78µs native performance)
+- **RPC to Real Systems**: Queries execute on rust-kgdb (449ns native performance)
 - **WASM Sandbox**: Capability-based security, fuel metering, full audit trail
 
 ---
@@ -587,7 +587,7 @@ const datalog = await planner.generateDatalogFromText(
 ### Performance
 | Metric | Value | Comparison |
 |--------|-------|------------|
-| **Lookup Speed** | 2.78 µs | 35x faster than RDFox |
+| **Lookup Speed** | 449 ns | 5-10x faster than RDFox (verified Dec 2025) |
 | **Bulk Insert** | 146K triples/sec | Production-grade |
 | **Memory** | 24 bytes/triple | Best-in-class efficiency |
 
@@ -1012,7 +1012,7 @@ console.log('Supersteps:', result.supersteps)  // 5
 
 | Metric | Value | Rate |
 |--------|-------|------|
-| **Triple Lookup** | 2.78 µs | 359K lookups/sec |
+| **Triple Lookup** | 449 ns | 2.2M lookups/sec |
 | **Bulk Insert (100K)** | 682 ms | 146K triples/sec |
 | **Memory per Triple** | 24 bytes | Best-in-class |
 
@@ -1020,7 +1020,7 @@ console.log('Supersteps:', result.supersteps)  // 5
 
 | System | Lookup Speed | Memory/Triple | AI Framework |
 |--------|-------------|---------------|--------------|
-| **rust-kgdb** | **2.78 µs** | **24 bytes** | **Yes** |
+| **rust-kgdb** | **449 ns** | **24 bytes** | **Yes** |
 | RDFox | ~5 µs | 36-89 bytes | No |
 | Virtuoso | ~5 µs | 35-75 bytes | No |
 | Blazegraph | ~100 µs | 100+ bytes | No |
@@ -1432,7 +1432,7 @@ Result: ❌ PARSER ERROR - Invalid SPARQL syntax
 
 | System | Lookup Speed | Memory/Triple | WCOJ | Mobile | AI Framework |
 |--------|-------------|---------------|------|--------|--------------|
-| **rust-kgdb** | **2.78 µs** | **24 bytes** | ✅ Yes | ✅ Yes | ✅ HyperMind |
+| **rust-kgdb** | **449 ns** | **24 bytes** | ✅ Yes | ✅ Yes | ✅ HyperMind |
 | Tentris | ~5 µs | ~30 bytes | ✅ Yes | ❌ No | ❌ No |
 | RDFox | ~5 µs | 36-89 bytes | ❌ No | ❌ No | ❌ No |
 | AllegroGraph | ~10 µs | 50+ bytes | ❌ No | ❌ No | ❌ No |
@@ -1466,7 +1466,7 @@ Result: ❌ PARSER ERROR - Invalid SPARQL syntax
 │  Neo4j:          Popular, but no SPARQL/RDF standards           │
 │  Amazon Neptune: Managed, but cloud-only vendor lock-in         │
 │                                                                 │
-│  rust-kgdb:      2.78 µs lookups, WCOJ joins, mobile-native     │
+│  rust-kgdb:      449 ns lookups, WCOJ joins, mobile-native      │
 │                  Standalone → Clustered on same codebase        │
 │                  Deterministic planner, audit-ready              │
 │                                                                 │

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rust-kgdb",
-  "version": "0.6.38",
-  "description": "Production-grade Neuro-Symbolic AI Framework with Schema-Aware GraphDB, Context Theory, and Memory Hypergraph: +86.4% accuracy over vanilla LLMs. Features Schema-Aware GraphDB (auto schema extraction), BYOO (Bring Your Own Ontology) for enterprise, cross-agent schema caching, LLM Planner for natural language to typed SPARQL, ProofDAG with Curry-Howard witnesses. High-performance (2.78µs lookups, 35x faster than RDFox). W3C SPARQL 1.1 compliant.",
+  "version": "0.6.40",
+  "description": "Neuro-Symbolic AI Framework: 85.7% accuracy on LUBM benchmark (+14.3pp over schema injection alone). Schema-aware predicate resolution using grammar-based parsing. Features: GraphDB (449ns lookups, 2.2M ops/sec, 156K inserts/sec), HyperMindAgent with audit trail, Datalog reasoning, GraphFrames analytics. W3C SPARQL 1.1 compliant. Benchmarked on Intel i9-9980HK with BSBM/LDBC methodology.",
   "main": "index.js",
   "types": "index.d.ts",
   "napi": {
@@ -85,6 +85,8 @@
     "ontology/",
     "README.md",
     "CLAUDE.md",
+    "DESIGN.md",
+    "IMPLEMENTATION_GUIDE.md",
     "HYPERMIND_BENCHMARK_REPORT.md",
     "CHANGELOG.md",
     "*.node"