rust-kgdb 0.6.10 → 0.6.14

package/CHANGELOG.md

@@ -2,6 +2,152 @@
 
 All notable changes to the rust-kgdb TypeScript SDK will be documented in this file.
 
+## [0.6.14] - 2025-12-15
+
+### Industry Benchmarks, Control Plane Architecture & ProofDAG Visualization
+
+#### Documentation Enhancements
+
+**Industry Benchmark Comparison** (Factually Verified)
+- Added comprehensive comparison with Tentris, RDFox, Virtuoso, Blazegraph, AllegroGraph
+- All numbers from peer-reviewed papers (ISWC 2020, 2022, 2025) and official documentation
+- WCOJ algorithm comparison table
+- Unique advantages matrix
+- Honest assessment section with proper citations
+
+**Sources Added**:
+- [Tentris ISWC 2020](https://papers.dice-research.org/2020/ISWC_Tentris/iswc2020_tentris_public.pdf)
+- [Tentris WCOJ Update 2025](https://papers.dice-research.org/2025/ISWC_Tentris-WCOJ-Update/public.pdf)
+- [RDFox Oxford Semantic](https://www.oxfordsemantic.tech/rdfox)
+- [Virtuoso LUBM Benchmark](https://vos.openlinksw.com/owiki/wiki/VOS/VOSArticleLUBMBenchmark)
+
+**HyperMind as Intelligence Control Plane**
+- Added control plane architecture diagram
+- Referenced [Chang 2025 - "The Missing Layer of AGI"](https://arxiv.org/abs/2512.05765)
+- Explained semantic anchoring, goal-directed constraints, verification layer
+- Linked to foundational research: Curry-Howard, Spivak's Ologs
+
+**ProofDAG Visual Output**
+- Added ASCII art visualization of ProofDAG structure
+- Complete JSON schema for proof objects
+- Derivation chain example with real tools
+
+**Test Environment Note**
+- All benchmarks run on commodity hardware (Intel Mac laptop)
+- InMemoryBackend with zero-copy, no GC
+- Criterion.rs statistical benchmarking
+
+## [0.6.13] - 2025-12-15
+
+### Schema-Aware GraphDB, Context Theory & BYOO (Bring Your Own Ontology)
+
+Major release introducing enterprise-grade schema management with mathematical foundations.
+
+#### New Features
+
+**Schema-Aware GraphDB (v0.6.13)**
+- `SchemaAwareGraphDB` - Auto-extracts schema at load time
+- `createSchemaAwareGraphDB()` - Factory function for new databases
+- `wrapWithSchemaAwareness()` - Wrap existing GraphDB instances
+- `waitForSchema()` - Handles race conditions (Promise-based)
+- Schema extraction triggers ONLY on data modifications (not reads)
+
+```javascript
+const db = createSchemaAwareGraphDB('http://example.org/')
+db.loadTtl('...', null)  // Schema extracted automatically
+const schema = await db.waitForSchema()  // Race-condition safe
+```
+
+**Schema Caching (v0.6.12)**
+- `SchemaCache` - TTL-based cache (default: 5 minutes)
+- `SCHEMA_CACHE` - Global singleton for cross-agent sharing
+- `getOrCompute()` - Cache-aside pattern for automatic computation
+- `invalidate()` - Clear cache on data changes
+- Cache stats monitoring (`getStats()`)
+
+**Context Theory (v0.6.11)**
+- `SchemaContext` - Schema as category (Spivak's Ologs)
+  - Objects = Classes (owl:Class, rdfs:Class)
+  - Morphisms = Properties (owl:ObjectProperty, owl:DatatypeProperty)
+- `TypeJudgment` - Type judgments (Γ ⊢ t : T)
+- `QueryValidator` - Validate SPARQL against schema morphisms
+- `ProofDAG` - Curry-Howard proof witnesses with deterministic hashes
+
+**Bring Your Own Ontology (BYOO)**
+- `SchemaContext.fromOntology()` - Load enterprise ontologies (TTL/OWL)
+- `SchemaContext.merge()` - Combine ontology + KG-derived schemas
+- Support for FIBO, HL7 FHIR, and domain-specific ontologies
+- Enterprise governance: ontology teams define schemas centrally
+
+#### Mathematical Foundation
+
+Three pillars for predictable, verifiable AI:
+
+| Pillar | Guarantee | Implementation |
+|--------|-----------|----------------|
+| Type Theory | Input/output contracts | `kg.sparql.query: Query → BindingSet` |
+| Category Theory | Safe tool composition | Morphisms compose: `A → B → C` |
+| Proof Theory | Full provenance | ProofDAG with Curry-Howard witness |
+
+#### Schema-Aware Intent Classification
+
+Different words → Same SPARQL (LLM + Schema injection):
+- "high-risk providers" / "suspicious vendors" / "elevated risk" → Same query
+- LLM understands schema morphisms and maps synonyms correctly
+- No hallucinated predicates - uses YOUR actual schema
+
+#### Breaking Changes
+- None (fully backward compatible)
+
+#### Files Added
+- `ontology/agent-memory.ttl` - OWL ontology for agent memory
+
+## [0.6.10] - 2025-12-15
+
+### Complete KG Configuration & Default Settings Documentation
+
+Added comprehensive documentation to examples explaining KG storage modes and defaults:
+
+#### Knowledge Graph Storage Modes
+```javascript
+// MODE 1: IN-MEMORY (Default)
+const db = new GraphDB('http://example.org/')  // Zero config
+// - Storage: RAM (HashMap-based SPOC indexes)
+// - Performance: 2.78µs lookups, 146K triples/sec
+// - Persistence: None (data lost on restart)
+
+// MODE 2: ENDPOINT (Distributed Cluster)
+const agent = await HyperMindAgent.spawn({
+  endpoint: 'http://rust-kgdb-coordinator:8080',  // K8s service
+  ...
+})
+// - Storage: HDRF-partitioned across executors
+// - Persistence: RocksDB/LMDB per executor
+// - Consensus: Raft for distributed writes
+```
+
+#### Default Settings (When Not Specified)
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `storage` | `'inmemory'` | Not 'rocksdb' or 'lmdb' |
+| `endpoint` | `null` | Local mode, no network |
+| `graphUri` | `null` | Default graph |
+| `working.maxSize` | `1MB` | Current task context |
+| `episodic.retentionDays` | `30` | Conversation history |
+| `weights` | `{recency: 0.3, relevance: 0.5, importance: 0.2}` | Memory scoring |
+| `sandbox` | `null` | **⚠️ NO SANDBOX = full access** |
+
+#### Sandbox Warning
+```javascript
+// ⚠️ WITHOUT .withSandbox(), agent has UNRESTRICTED capabilities!
+// Always use sandbox in production:
+.withSandbox({
+  capabilities: ['ReadKG', 'ExecuteTool'],  // Whitelist only
+  fuelLimit: 1_000_000,  // Gas limit
+  maxExecTime: 30_000    // Timeout
+})
+```
+
 ## [0.6.9] - 2025-12-15
 
 ### Deep Technical Comparison: Why rust-kgdb Wins