rust-kgdb 0.1.9 → 0.1.11

package/README.md

@@ -1,237 +1,469 @@
-# rust-kgdb - High-Performance RDF/SPARQL Database
+# rust-kgdb
 
 [![npm version](https://badge.fury.io/js/rust-kgdb.svg)](https://www.npmjs.com/package/rust-kgdb)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-**Production-ready mobile-first RDF/hypergraph database with complete SPARQL 1.1 support and worst-case optimal join (WCOJ) execution.**
+**Production-ready RDF/hypergraph database with 100% W3C SPARQL 1.1 + RDF 1.2 compliance, worst-case optimal joins (WCOJ), and pluggable storage backends.**
 
-## 🚀 Key Features
+---
 
-- **100% W3C SPARQL 1.1 Compliance** - Complete query and update support
-- **100% W3C RDF 1.2 Compliance** - Full standard implementation
-- **WCOJ Execution** (v0.1.8) - LeapFrog TrieJoin for optimal multi-way joins
-- **Zero-Copy Semantics** - Minimal allocations, maximum performance
-- **Blazing Fast** - 2.78 µs triple lookups, 146K triples/sec bulk insert
-- **Memory Efficient** - 24 bytes/triple (25% better than RDFox)
-- **Native Rust** - Safe, reliable, production-ready
+## Why rust-kgdb?
 
-## 📊 Performance (v0.1.8 - WCOJ Execution)
+| Feature | rust-kgdb | Apache Jena | RDFox |
+|---------|-----------|-------------|-------|
+| **Lookup Speed** | 2.78 µs | ~50 µs | 50-100 µs |
+| **Memory/Triple** | 24 bytes | 50-60 bytes | 32 bytes |
+| **SPARQL 1.1** | 100% | 100% | 95% |
+| **RDF 1.2** | 100% | Partial | No |
+| **WCOJ** | ✅ LeapFrog | ❌ | ❌ |
+| **Mobile-Ready** | ✅ iOS/Android | ❌ | ❌ |
 
-### Query Performance Improvements
+---
 
-| Query Type | Before (Nested Loop) | After (WCOJ) | Expected Speedup |
-|------------|---------------------|--------------|------------------|
-| **Star Queries** (3+ patterns) | O(n³) | O(n log n) | **50-100x** |
-| **Complex Joins** (4+ patterns) | O(n⁴) | O(n log n) | **100-1000x** |
-| **Chain Queries** | O(n²) | O(n log n) | **10-20x** |
+## Core Technical Innovations
 
-### Benchmark Results (Apple Silicon)
+### 1. Worst-Case Optimal Joins (WCOJ)
 
-| Metric | Result | Rate | vs RDFox |
-|--------|--------|------|----------|
-| **Lookup** | 2.78 µs | 359K/sec | ✅ **35-180x faster** |
-| **Bulk Insert** | 682 ms (100K) | 146K/sec | ⚠️ 73% speed (gap closing) |
-| **Memory** | 24 bytes/triple | - | ✅ **25% better** |
+Traditional databases use **nested-loop joins** with O(n²) to O(n⁴) complexity. rust-kgdb implements the **LeapFrog TrieJoin** algorithm—a worst-case optimal join that achieves O(n log n) for multi-way joins.
 
-### SIMD + PGO Optimizations (v0.1.8)
+**How it works:**
+- **Trie Data Structure**: Triples indexed hierarchically (S→P→O) using BTreeMap for sorted access
+- **Variable Ordering**: Frequency-based analysis orders variables for optimal intersection
+- **LeapFrog Iterator**: Binary search across sorted iterators finds intersections without materializing intermediate results
 
-**Compiler-Level Performance Gains** - Zero code changes, pure optimization!
+```
+Query: SELECT ?x ?y ?z WHERE { ?x :p ?y . ?y :q ?z . ?x :r ?z }
 
-| Query | Before (No SIMD) | After (SIMD+PGO) | Improvement | Category |
-|-------|------------------|------------------|-------------|----------|
-| **Q1: 4-way star** | 283ms | **258ms** | ✅ **9% faster** | Good |
-| **Q2: 5-way star** | 234ms | **183ms** | ✅ **22% faster** | Strong |
-| **Q3: 3-way star** | 177ms | **62ms** | 🔥 **65% faster** | Exceptional |
-| **Q4: 3-hop chain** | 254ms | **101ms** | 🔥 **60% faster** | Exceptional |
-| **Q5: 2-hop chain** | 230ms | **53ms** | 🔥 **77% faster** | **BEST** |
-| **Q6: 6-way complex** | 641ms | **464ms** | ✅ **28% faster** | Good |
-| **Q7: Hierarchy** | 343ms | **198ms** | ✅ **42% faster** | Strong |
-| **Q8: Triangle** | 410ms | **193ms** | ✅ **53% faster** | Strong |
+Nested Loop: O(n³) - examines every combination
+WCOJ:        O(n log n) - iterates in sorted order, seeks forward on mismatch
+```
 
-**Key Results:**
-- **Average Speedup**: **44.5%** across all 8 LUBM queries
-- **Best Speedup**: **77%** (Q5 - 2-hop chain query)
-- **Range**: 9% to 77% improvement (all queries faster!)
-- **Distribution**: 3 exceptional (60%+), 2 strong (40-59%), 2 good (20-39%), 1 modest (9%)
+| Query Pattern | Before (Nested Loop) | After (WCOJ) | Speedup |
+|---------------|---------------------|--------------|---------|
+| 3-way star | O(n³) | O(n log n) | **50-100x** |
+| 4+ way complex | O(n⁴) | O(n log n) | **100-1000x** |
+| Chain queries | O(n²) | O(n log n) | **10-20x** |
 
-**How PGO Works:**
-1. **Instrumentation Build**: Compiler adds profiling hooks
-2. **Profile Collection**: Run real workload (23 runtime profiles collected)
-3. **Profile Merging**: Combine profiles into 5.9M merged dataset
-4. **Optimized Rebuild**: Compiler uses runtime data for:
-   - Optimized hot paths (loops, function calls)
-   - Improved branch prediction
-   - Enhanced instruction cache locality
-   - Better CPU pipelining
+### 2. Sparse Matrix Engine (CSR Format)
 
-**Hardware:** Tested on Intel Skylake with AVX2, BMI2, POPCNT optimizations.
+Binary relations (e.g., `foaf:knows`, `rdfs:subClassOf`) are converted to **Compressed Sparse Row (CSR)** matrices for cache-efficient join evaluation:
 
-## 📦 Installation
+- **Memory**: O(nnz) where nnz = number of edges (not O(n²))
+- **Matrix Multiplication**: Replaces nested-loop joins
+- **Transitive Closure**: Semi-naive Δ-matrix evaluation (not iterated powers)
 
-```bash
-npm install rust-kgdb
+```rust
+// Traditional: O(n²) nested loops
+for (s, p, o) in triples { ... }
+
+// CSR Matrix: O(nnz) cache-friendly iteration
+row_ptr[i] → col_indices[j] → values[j]
 ```
 
-### Prerequisites
+**Used for**: RDFS/OWL reasoning, transitive closure, Datalog evaluation.
+
+### 3. SIMD + PGO Compiler Optimizations
+
+**Zero code changes—pure compiler-level performance gains.**
+
+| Optimization | Technology | Effect |
+|--------------|------------|--------|
+| **SIMD Vectorization** | AVX2/BMI2 (Intel), NEON (ARM) | 8-wide parallel operations |
+| **Profile-Guided Optimization** | LLVM PGO | Hot path optimization, branch prediction |
+| **Link-Time Optimization** | LTO (fat) | Cross-crate inlining, dead code elimination |
+
+**Benchmark Results (LUBM, Intel Skylake):**
+
+| Query | Before | After (SIMD+PGO) | Improvement |
+|-------|--------|------------------|-------------|
+| Q5: 2-hop chain | 230ms | 53ms | **77% faster** |
+| Q3: 3-way star | 177ms | 62ms | **65% faster** |
+| Q4: 3-hop chain | 254ms | 101ms | **60% faster** |
+| Q8: Triangle | 410ms | 193ms | **53% faster** |
+| Q7: Hierarchy | 343ms | 198ms | **42% faster** |
+| Q6: 6-way complex | 641ms | 464ms | **28% faster** |
+| Q2: 5-way star | 234ms | 183ms | **22% faster** |
+| Q1: 4-way star | 283ms | 258ms | **9% faster** |
+
+**Average speedup: 44.5%** across all queries.
+
+### 4. Quad Indexing (SPOC)
+
+Four complementary indexes enable O(1) pattern matching regardless of query shape:
+
+| Index | Pattern | Use Case |
+|-------|---------|----------|
+| **SPOC** | `(?s, ?p, ?o, ?g)` | Subject-centric queries |
+| **POCS** | `(?p, ?o, ?c, ?s)` | Property enumeration |
+| **OCSP** | `(?o, ?c, ?s, ?p)` | Object lookups (reverse links) |
+| **CSPO** | `(?c, ?s, ?p, ?o)` | Named graph iteration |
+
+---
+
+## Storage Backends
+
+rust-kgdb uses a pluggable storage architecture. **Default is in-memory** (zero configuration). For persistence, enable RocksDB.
+
+| Backend | Feature Flag | Use Case | Status |
+|---------|--------------|----------|--------|
+| **InMemory** | `default` | Development, testing, embedded | ✅ **Production Ready** |
+| **RocksDB** | `rocksdb-backend` | Production, large datasets | ✅ **61 tests passing** |
+| **LMDB** | `lmdb-backend` | Read-heavy workloads | ⏳ Planned v0.2.0 |
+
+### InMemory (Default)
+
+Zero configuration, maximum performance. Data is volatile (lost on process exit).
+
+**High-Performance Data Structures:**
+
+| Component | Structure | Why |
+|-----------|-----------|-----|
+| **Triple Store** | `DashMap` | Lock-free concurrent hash map, 100K pre-allocation |
+| **WCOJ Trie** | `BTreeMap` | Sorted iteration for LeapFrog intersection |
+| **Dictionary** | `FxHashSet` | String interning with rustc-optimized hashing |
+| **Hypergraph** | `FxHashMap` | Fast node→edge adjacency lists |
+| **Reasoning** | `AHashMap` | RDFS/OWL inference with DoS-resistant hashing |
+| **Datalog** | `FxHashMap` | Semi-naive evaluation with delta propagation |
+
+**Why these structures enable sub-microsecond performance:**
+- **DashMap**: Sharded locks (16 shards default) → near-linear scaling on multi-core
+- **FxHashMap**: Rust compiler's hash function → 30% faster than std HashMap
+- **BTreeMap**: O(log n) ordered iteration → enables binary search in LeapFrog
+- **Pre-allocation**: 100K capacity avoids rehashing during bulk inserts
+
+```rust
+use storage::{QuadStore, InMemoryBackend};
+
+let store = QuadStore::new(InMemoryBackend::new());
+// Ultra-fast: 2.78 µs lookups, zero disk I/O
+```
+
+### RocksDB (Persistent)
+
+LSM-tree based storage with ACID transactions. Tested with **61 comprehensive tests**.
+
+```toml
+# Cargo.toml - Enable RocksDB backend
+[dependencies]
+storage = { version = "0.1.10", features = ["rocksdb-backend"] }
+```
+
+```rust
+use storage::{QuadStore, RocksDbBackend};
+
+// Create persistent database
+let backend = RocksDbBackend::new("/path/to/data")?;
+let store = QuadStore::new(backend);
+
+// Features:
+// - ACID transactions
+// - Snappy compression (automatic)
+// - Crash recovery
+// - Range & prefix scanning
+// - 1MB+ value support
+
+// Force sync to disk
+store.flush()?;
+```
+
+**RocksDB Test Coverage:**
+- Basic CRUD operations (14 tests)
+- Range scanning (8 tests)
+- Prefix scanning (6 tests)
+- Batch operations (8 tests)
+- Transactions (8 tests)
+- Concurrent access (5 tests)
+- Unicode & binary data (4 tests)
+- Large key/value handling (8 tests)
+
+### TypeScript SDK
+
+The npm package uses the in-memory backend—ideal for:
+- Knowledge graph queries
+- SPARQL execution
+- Data transformation pipelines
+- Embedded applications
+
+```typescript
+import { GraphDB } from 'rust-kgdb'
 
-- Node.js >= 14
-- No additional dependencies required (native bindings included)
+// In-memory database (default, no configuration needed)
+const db = new GraphDB('http://example.org/app')
+
+// For persistence, export via CONSTRUCT:
+const ntriples = db.queryConstruct('CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o }')
+fs.writeFileSync('backup.nt', ntriples)
+```
+
+---
+
+## Installation
+
+```bash
+npm install rust-kgdb
+```
 
 ### Platform Support
 
-| Platform | Architecture | Status | Notes |
-|----------|-------------|--------|-------|
-| **macOS** | x64 (Intel) | ✅ Fully Supported | SIMD+PGO optimized (AVX2) |
-| **macOS** | arm64 (Apple Silicon) | ✅ Fully Supported | SIMD+PGO optimized (NEON) |
-| **Linux** | x64 | ✅ Fully Supported | SIMD+PGO optimized (AVX2) |
-| **Linux** | arm64 | ✅ Fully Supported | SIMD+PGO optimized (NEON) |
-| **Windows** | x64 | ✅ Fully Supported | SIMD+PGO optimized (AVX2) |
-| **Windows** | arm64 | ⏳ Coming Soon | Planned for v0.2.0 |
+| Platform | Architecture | Status | SIMD |
+|----------|-------------|--------|------|
+| **macOS** | Intel (x64) | ✅ | AVX2, BMI2, POPCNT |
+| **macOS** | Apple Silicon (arm64) | ✅ | NEON |
+| **Linux** | x64 | ✅ | AVX2, BMI2, POPCNT |
+| **Linux** | arm64 | ✅ | NEON |
+| **Windows** | x64 | ✅ | AVX2, BMI2, POPCNT |
+| **Windows** | arm64 | ⏳ v0.2.0 | — |
 
-**SIMD Optimizations** (v0.1.8):
-- **Intel/AMD (x64)**: AVX2, BMI2, POPCNT auto-vectorization
-- **Apple Silicon (arm64)**: NEON auto-vectorization
-- **Profile-Guided Optimization (PGO)**: Runtime profile-based code generation
+**No compilation required**—pre-built native binaries included.
+
+---
 
-**Native Bindings**: Pre-compiled binaries included for all platforms. No compilation required during `npm install`.
+## Quick Start
 
-## 🎯 Quick Start
+### Complete Working Example
 
 ```typescript
-import { GraphDB, Node } from 'rust-kgdb'
+import { GraphDB } from 'rust-kgdb'
 
-// Create in-memory database
-const db = new GraphDB('http://example.org/my-app')
+// 1. Create database
+const db = new GraphDB('http://example.org/myapp')
 
-// Insert triples
+// 2. Load data (Turtle format)
 db.loadTtl(`
   @prefix foaf: <http://xmlns.com/foaf/0.1/> .
+  @prefix ex: <http://example.org/> .
 
-  <http://example.org/alice> foaf:name "Alice" ;
-                             foaf:age 30 ;
-                             foaf:knows <http://example.org/bob> .
+  ex:alice a foaf:Person ;
+           foaf:name "Alice" ;
+           foaf:age 30 ;
+           foaf:knows ex:bob, ex:charlie .
 
-  <http://example.org/bob> foaf:name "Bob" ;
-                           foaf:age 25 .
+  ex:bob a foaf:Person ;
+         foaf:name "Bob" ;
+         foaf:age 25 ;
+         foaf:knows ex:charlie .
+
+  ex:charlie a foaf:Person ;
+             foaf:name "Charlie" ;
+             foaf:age 35 .
 `, null)
 
-// SPARQL SELECT query
-const results = db.querySelect(`
+// 3. Query: Find friends-of-friends (WCOJ optimized!)
+const fof = db.querySelect(`
   PREFIX foaf: <http://xmlns.com/foaf/0.1/>
+  PREFIX ex: <http://example.org/>
 
-  SELECT ?person ?name ?age WHERE {
-    ?person foaf:name ?name ;
-            foaf:age ?age .
+  SELECT ?person ?friend ?fof WHERE {
+    ?person foaf:knows ?friend .
+    ?friend foaf:knows ?fof .
+    FILTER(?person != ?fof)
   }
-  ORDER BY DESC(?age)
 `)
+console.log('Friends of Friends:', fof)
+// [{ person: 'ex:alice', friend: 'ex:bob', fof: 'ex:charlie' }]
+
+// 4. Aggregation: Average age
+const stats = db.querySelect(`
+  PREFIX foaf: <http://xmlns.com/foaf/0.1/>
 
-console.log(results)
-// [
-//   { person: '<http://example.org/alice>', name: '"Alice"', age: '30' },
-//   { person: '<http://example.org/bob>', name: '"Bob"', age: '25' }
-// ]
+  SELECT (COUNT(?p) AS ?count) (AVG(?age) AS ?avgAge) WHERE {
+    ?p a foaf:Person ; foaf:age ?age .
+  }
+`)
+console.log('Stats:', stats)
+// [{ count: '3', avgAge: '30.0' }]
 
-// SPARQL ASK query
+// 5. ASK query
 const hasAlice = db.queryAsk(`
-  ASK { <http://example.org/alice> foaf:name "Alice" }
+  PREFIX ex: <http://example.org/>
+  ASK { ex:alice a <http://xmlns.com/foaf/0.1/Person> }
 `)
-console.log(hasAlice) // true
+console.log('Has Alice?', hasAlice)  // true
+
+// 6. CONSTRUCT query
+const graph = db.queryConstruct(`
+  PREFIX foaf: <http://xmlns.com/foaf/0.1/>
+  PREFIX ex: <http://example.org/>
+
+  CONSTRUCT { ?p foaf:knows ?f }
+  WHERE { ?p foaf:knows ?f }
+`)
+console.log('Extracted graph:', graph)
+
+// 7. Count and cleanup
+console.log('Triple count:', db.count())  // 11
+db.clear()
+```
+
+### Save to File
+
+```typescript
+import { writeFileSync } from 'fs'
+
+// Save as N-Triples
+const db = new GraphDB('http://example.org/export')
+db.loadTtl(`<http://example.org/s> <http://example.org/p> "value" .`, null)
 
-// Count triples
-console.log(db.count()) // 5
+const ntriples = db.queryConstruct(`CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o }`)
+writeFileSync('output.nt', ntriples)
 ```
 
-## 🔥 WCOJ Execution Examples (v0.1.8)
+---
 
-### Star Query (50-100x Faster!)
+## SPARQL 1.1 Features (100% W3C Compliant)
+
+### Query Forms
 
 ```typescript
-// Find people with name, age, and email
-const starQuery = db.querySelect(`
-  PREFIX foaf: <http://xmlns.com/foaf/0.1/>
+// SELECT - return bindings
+db.querySelect('SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10')
 
-  SELECT ?person ?name ?age ?email WHERE {
-    ?person foaf:name ?name .
-    ?person foaf:age ?age .
-    ?person foaf:email ?email .
-  }
+// ASK - boolean existence check
+db.queryAsk('ASK { <http://example.org/x> ?p ?o }')
+
+// CONSTRUCT - build new graph
+db.queryConstruct('CONSTRUCT { ?s <http://new/prop> ?o } WHERE { ?s ?p ?o }')
+```
+
+### Aggregates
+
+```typescript
+db.querySelect(`
+  SELECT ?type (COUNT(*) AS ?count) (AVG(?value) AS ?avg)
+  WHERE { ?s a ?type ; <http://ex/value> ?value }
+  GROUP BY ?type
+  HAVING (COUNT(*) > 5)
+  ORDER BY DESC(?count)
 `)
+```
+
+### Property Paths
 
-// Automatically uses WCOJ execution for optimal performance
-// Expected speedup: 50-100x over nested loop joins
+```typescript
+// Transitive closure (rdfs:subClassOf*)
+db.querySelect('SELECT ?class WHERE { ?class rdfs:subClassOf* <http://top/Class> }')
+
+// Alternative paths
+db.querySelect('SELECT ?name WHERE { ?x (foaf:name|rdfs:label) ?name }')
+
+// Sequence paths
+db.querySelect('SELECT ?grandparent WHERE { ?x foaf:parent/foaf:parent ?grandparent }')
 ```
 
-### Complex Join (100-1000x Faster!)
+### Named Graphs
 
 ```typescript
-// Find coworker connections
-const complexJoin = db.querySelect(`
-  PREFIX org: <http://example.org/>
-
-  SELECT ?person1 ?person2 ?company WHERE {
-    ?person1 org:worksAt ?company .
-    ?person2 org:worksAt ?company .
-    ?person1 org:name ?name1 .
-    ?person2 org:name ?name2 .
-    FILTER(?person1 != ?person2)
+// Load into named graph
+db.loadTtl('<http://s> <http://p> "o" .', 'http://example.org/graph1')
+
+// Query specific graph
+db.querySelect(`
+  SELECT ?s ?p ?o WHERE {
+    GRAPH <http://example.org/graph1> { ?s ?p ?o }
   }
 `)
+```
+
+### UPDATE Operations
 
-// WCOJ automatically selected for 4+ pattern joins
-// Expected speedup: 100-1000x over nested loop
+```typescript
+// INSERT DATA
+db.updateInsert(`
+  INSERT DATA { <http://ex/new> <http://ex/prop> "value" }
+`)
+
+// DELETE WHERE
+db.updateDelete(`
+  DELETE WHERE { ?s <http://ex/deprecated> ?o }
+`)
 ```
 
-### Chain Query (10-20x Faster!)
+---
+
+## Sample Application
+
+### Knowledge Graph Demo
+
+A complete, production-ready sample application demonstrating enterprise knowledge graph capabilities is available in the repository.
+
+**Location**: [`examples/knowledge-graph-demo/`](../../examples/knowledge-graph-demo/)
+
+**Features Demonstrated**:
+- Complete organizational knowledge graph (employees, departments, projects, skills)
+- SPARQL SELECT queries with star and chain patterns (WCOJ-optimized)
+- Aggregations (COUNT, AVG, GROUP BY, HAVING)
+- Property paths for transitive closure (organizational hierarchy)
+- SPARQL ASK and CONSTRUCT queries
+- Named graphs for multi-tenant data isolation
+- Data export to Turtle format
+
+**Run the Demo**:
+
+```bash
+cd examples/knowledge-graph-demo
+npm install
+npm start
+```
+
+**Sample Output**:
+
+The demo creates a realistic knowledge graph with:
+- 5 employees across 4 departments
+- 13 technical and soft skills
+- 2 software projects
+- Reporting hierarchies and salary data
+- Named graph for sensitive compensation data
+
+**Example Query from Demo** (finds all direct and indirect reports):
 
 ```typescript
-// Friend-of-friend pattern
-const chainQuery = db.querySelect(`
+const pathQuery = `
+  PREFIX ex: <http://example.org/>
   PREFIX foaf: <http://xmlns.com/foaf/0.1/>
 
-  SELECT ?person1 ?person2 ?person3 WHERE {
-    ?person1 foaf:knows ?person2 .
-    ?person2 foaf:knows ?person3 .
+  SELECT ?employee ?name WHERE {
+    ?employee ex:reportsTo+ ex:alice .  # Transitive closure
+    ?employee foaf:name ?name .
   }
-`)
-
-// WCOJ optimizes chain patterns
-// Expected speedup: 10-20x over nested loop
+  ORDER BY ?name
+`
+const results = db.querySelect(pathQuery)
 ```
 
-## 📚 Full API Reference
+**Learn More**: See the [demo README](../../examples/knowledge-graph-demo/README.md) for full documentation, query examples, and how to customize the knowledge graph.
+
+---
+
+## API Reference
 
 ### GraphDB Class
 
 ```typescript
 class GraphDB {
-  // Create database
-  static inMemory(): GraphDB
-  constructor(baseUri: string)
+  constructor(baseUri: string)           // Create with base URI
+  static inMemory(): GraphDB             // Create anonymous in-memory DB
 
-  // Data loading
-  loadTtl(data: string, graphName: string | null): void
-  loadNTriples(data: string, graphName: string | null): void
+  // Data Loading
+  loadTtl(data: string, graph: string | null): void
+  loadNTriples(data: string, graph: string | null): void
 
-  // SPARQL queries (WCOJ execution in v0.1.8!)
+  // SPARQL Queries (WCOJ-optimized)
   querySelect(sparql: string): Array<Record<string, string>>
   queryAsk(sparql: string): boolean
-  queryConstruct(sparql: string): string
+  queryConstruct(sparql: string): string  // Returns N-Triples
 
-  // SPARQL updates
+  // SPARQL Updates
   updateInsert(sparql: string): void
   updateDelete(sparql: string): void
 
-  // Database operations
+  // Database Operations
   count(): number
   clear(): void
-
-  // Metadata
   getVersion(): string
 }
 ```
 
-### Node Class (Triple Construction)
+### Node Class
 
 ```typescript
 class Node {
@@ -245,165 +477,91 @@ class Node {
 }
 ```
 
-## 🎓 Advanced Usage
+---
 
-### SPARQL UPDATE Operations
+## Performance Characteristics
 
-```typescript
-// INSERT DATA
-db.updateInsert(`
-  PREFIX foaf: <http://xmlns.com/foaf/0.1/>
+### Complexity Analysis
 
-  INSERT DATA {
-    <http://example.org/charlie> foaf:name "Charlie" ;
-                                  foaf:age 35 .
-  }
-`)
+| Operation | Complexity | Notes |
+|-----------|------------|-------|
+| Triple lookup | O(1) | Hash-based SPOC index |
+| Pattern scan | O(k) | k = matching triples |
+| Star join (WCOJ) | O(n log n) | LeapFrog intersection |
+| Complex join (WCOJ) | O(n log n) | Trie-based |
+| Transitive closure | O(n²) worst | CSR matrix optimization |
+| Bulk insert | O(n) | Batch indexing |
 
-// DELETE WHERE
-db.updateDelete(`
-  PREFIX foaf: <http://xmlns.com/foaf/0.1/>
+### Memory Layout
 
-  DELETE WHERE {
-    ?person foaf:age ?age .
-    FILTER(?age < 18)
-  }
-`)
 ```
-
-### Named Graphs
-
-```typescript
-// Load into named graph
-db.loadTtl(`
-  <http://example.org/resource> <http://purl.org/dc/terms/title> "Title" .
-`, 'http://example.org/graph1')
-
-// Query specific graph
-const results = db.querySelect(`
-  SELECT ?s ?p ?o WHERE {
-    GRAPH <http://example.org/graph1> {
-      ?s ?p ?o .
-    }
-  }
-`)
-```
-
-### SPARQL 1.1 Aggregates
-
-```typescript
-// COUNT, AVG, MIN, MAX, SUM
-const aggregates = db.querySelect(`
-  PREFIX foaf: <http://xmlns.com/foaf/0.1/>
-
-  SELECT
-    (COUNT(?person) AS ?count)
-    (AVG(?age) AS ?avgAge)
-    (MIN(?age) AS ?minAge)
-    (MAX(?age) AS ?maxAge)
-  WHERE {
-    ?person foaf:age ?age .
-  }
-`)
+Triple: 24 bytes
+├── Subject:   8 bytes (dictionary ID)
+├── Predicate: 8 bytes (dictionary ID)
+└── Object:    8 bytes (dictionary ID)
+
+String Interning: All URIs/literals stored once in Dictionary
+Index Overhead: ~4x base triple size (4 indexes)
+Total: ~120 bytes/triple including indexes
 ```
 
-### SPARQL 1.1 Property Paths
-
-```typescript
-// Transitive closure with *
-const transitiveKnows = db.querySelect(`
-  PREFIX foaf: <http://xmlns.com/foaf/0.1/>
-
-  SELECT ?person ?connected WHERE {
-    <http://example.org/alice> foaf:knows* ?connected .
-  }
-`)
-
-// Alternative paths with |
-const nameOrLabel = db.querySelect(`
-  PREFIX foaf: <http://xmlns.com/foaf/0.1/>
-  PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
-
-  SELECT ?resource ?name WHERE {
-    ?resource (foaf:name|rdfs:label) ?name .
-  }
-`)
-```
+---
 
-## 🏗️ Architecture
+## Version History
 
-- **Core**: Pure Rust implementation with zero-copy semantics
-- **Bindings**: NAPI-RS for native Node.js addon
-- **Storage**: Pluggable backends (InMemory, RocksDB, LMDB)
-- **Indexing**: SPOC, POCS, OCSP, CSPO quad indexes
-- **Query Optimizer**: Automatic WCOJ detection and execution
-- **WCOJ Engine**: LeapFrog TrieJoin with variable ordering analysis
+### v0.1.9 (2025-12-01) - SIMD + PGO Release
 
-## 📈 Version History
+- **44.5% average speedup** via SIMD + PGO compiler optimizations
+- WCOJ execution with LeapFrog TrieJoin
+- Release automation infrastructure
+- All packages updated to gonnect-uk namespace
 
-### v0.1.8 (2025-12-01) - WCOJ Execution!
+### v0.1.8 (2025-12-01) - WCOJ Execution
 
-- ✅ **WCOJ Execution Path Activated** - LeapFrog TrieJoin for multi-way joins
-- ✅ **Variable Ordering Analysis** - Frequency-based optimization for WCOJ
-- ✅ **50-100x Speedup** for star queries (3+ patterns with shared variable)
-- ✅ **100-1000x Speedup** for complex joins (4+ patterns)
-- ✅ **577 Tests Passing** - Comprehensive end-to-end verification
-- ✅ **Zero Regressions** - All existing queries work unchanged
+- WCOJ execution path activated
+- Variable ordering analysis for optimal joins
+- 577 tests passing
 
 ### v0.1.7 (2025-11-30)
 
 - Query optimizer with automatic strategy selection
 - WCOJ algorithm integration (planning phase)
-- Query plan visualization API
 
 ### v0.1.3 (2025-11-18)
 
-- Initial TypeScript SDK release
+- Initial TypeScript SDK
 - 100% W3C SPARQL 1.1 compliance
 - 100% W3C RDF 1.2 compliance
 
-## 🔬 Testing
-
-```bash
-# Run test suite
-npm test
-
-# Run specific tests
-npm test -- --testNamePattern="star query"
-```
-
-## 🤝 Contributing
+---
 
-Contributions are welcome! Please see [CONTRIBUTING.md](https://github.com/gonnect-uk/rust-kgdb/blob/main/CONTRIBUTING.md)
+## Use Cases
 
-## 📄 License
+| Domain | Application |
+|--------|-------------|
+| **Knowledge Graphs** | Enterprise ontologies, taxonomies |
+| **Semantic Search** | Structured queries over unstructured data |
+| **Data Integration** | ETL with SPARQL CONSTRUCT |
+| **Compliance** | SHACL validation, provenance tracking |
+| **Graph Analytics** | Pattern detection, community analysis |
+| **Mobile Apps** | Embedded RDF on iOS/Android |
 
-Apache License 2.0 - See [LICENSE](https://github.com/gonnect-uk/rust-kgdb/blob/main/LICENSE)
+---
 
-## 🔗 Links
+## Links
 
 - [GitHub Repository](https://github.com/gonnect-uk/rust-kgdb)
 - [Documentation](https://github.com/gonnect-uk/rust-kgdb/tree/main/docs)
 - [CHANGELOG](https://github.com/gonnect-uk/rust-kgdb/blob/main/CHANGELOG.md)
-- [W3C SPARQL 1.1 Spec](https://www.w3.org/TR/sparql11-query/)
-- [W3C RDF 1.2 Spec](https://www.w3.org/TR/rdf12-concepts/)
+- [W3C SPARQL 1.1](https://www.w3.org/TR/sparql11-query/)
+- [W3C RDF 1.2](https://www.w3.org/TR/rdf12-concepts/)
 
-## 💡 Use Cases
-
-- **Knowledge Graphs** - Build semantic data models
-- **Semantic Search** - Query structured data with SPARQL
-- **Data Integration** - Combine data from multiple sources
-- **Ontology Reasoning** - RDFS and OWL inference
-- **Graph Analytics** - Complex pattern matching with WCOJ
-- **Mobile Apps** - Embedded RDF database for iOS/Android
+---
 
-## 🎯 Roadmap
+## License
 
-- [x] v0.1.8: WCOJ execution + SIMD + PGO optimizations (35-55% faster!)
-- [ ] v0.1.9: Manual SIMD vectorization for 2-4x additional speedup
-- [ ] v0.2.0: Windows ARM64 support + distributed query execution
-- [ ] v0.3.0: Graph analytics and reasoning engines
+Apache License 2.0
 
 ---
 
-**Built with ❤️ using Rust and NAPI-RS**
+**Built with Rust + NAPI-RS**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-kgdb",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "High-performance RDF/SPARQL database with 100% W3C compliance and WCOJ execution",
   "main": "index.js",
   "types": "index.d.ts",
@@ -21,7 +21,7 @@
     "build:debug": "napi build --platform native/rust-kgdb-napi",
     "prepublishOnly": "napi prepublish -t npm",
     "test": "jest",
-    "version": "0.1.9"
+    "version": "0.1.11"
   },
   "keywords": [
     "rdf",
@@ -56,10 +56,10 @@
     "*.node"
   ],
   "optionalDependencies": {
-    "rust-kgdb-win32-x64-msvc": "0.1.9",
-    "rust-kgdb-darwin-x64": "0.1.9",
-    "rust-kgdb-linux-x64-gnu": "0.1.9",
-    "rust-kgdb-darwin-arm64": "0.1.9",
-    "rust-kgdb-linux-arm64-gnu": "0.1.9"
+    "rust-kgdb-win32-x64-msvc": "0.1.11",
+    "rust-kgdb-darwin-x64": "0.1.11",
+    "rust-kgdb-linux-x64-gnu": "0.1.11",
+    "rust-kgdb-darwin-arm64": "0.1.11",
+    "rust-kgdb-linux-arm64-gnu": "0.1.11"
   }
 }