@soulcraft/cortex 1.3.1

package/LICENSE

@@ -0,0 +1,16 @@
+Soulcraft Cortex - Proprietary License
+
+Copyright (c) 2026 Soulcraft Labs. All rights reserved.
+
+This software is proprietary and confidential. Unauthorized copying, distribution,
+modification, or use of this software, via any medium, is strictly prohibited.
+
+A valid license key is required to use this software. License keys can be purchased
+at https://soulcraft.com/pricing?focus=pro.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# @soulcraft/cortex
+
+Native Rust acceleration for [Brainy](https://github.com/soulcraftlabs/brainy). Drop-in performance upgrade — zero configuration required.
+
+## Pricing
+
+Cortex is a commercial add-on for Brainy. A license key is required after the 14-day trial.
+
+| Plan | Price | For |
+|------|-------|-----|
+| **Standard** | $199/year | Individuals and small teams |
+| **Enterprise** | $999/year | Companies, priority support |
+
+**[Purchase a license at soulcraft.com/pricing](https://soulcraft.com/pricing?focus=pro)**
+
+**14-day free trial** — starts automatically on first use, no signup required.
+
+## Installation
+
+```bash
+npm install @soulcraft/cortex
+```
+
+That's it. Brainy auto-detects cortex during `init()` and uses native implementations where available.
+
+## License Setup
+
+After purchasing, set your license key via environment variable or file:
+
+```bash
+# Option 1: Environment variable
+export SOULCRAFT_LICENSE=sc_cortex_<your-key>
+
+# Option 2: License file
+echo "sc_cortex_<your-key>" > ~/.soulcraft/license
+```
+
+License validation is offline-only — no network calls, no telemetry.
+
+## What Gets Accelerated
+
+| Subsystem | Native Implementation | Impact |
+|-----------|----------------------|--------|
+| Distance functions | SIMD cosine/euclidean/manhattan/dot product | Every vector search uses native distance |
+| Vector quantization | SIMD SQ8/SQ4 distance on compressed vectors | 4-8x memory reduction |
+| Product quantization | Native PQ codebook training and ADC lookup | 16-32x compression for large datasets |
+| Graph compression | Delta-varint encoded connection lists | 2-3x smaller graph storage |
+| Metadata index | Full Rust query/mutation engine with bitmap operations | Faster metadata filtering and mutations |
+| Graph adjacency | 4 LSM-trees with verb tracking in Rust | Faster relationship queries |
+| Embeddings | Candle ML (CPU, CUDA, Metal) | Native inference, no WASM compilation |
+| Roaring bitmaps | CRoaring bindings (binary-compatible) | Faster set operations on entity IDs |
+| Msgpack | Native encode/decode | Faster serialization |
+| Storage | MmapFileSystemStorage with zero-copy SSTables | Faster disk I/O for graph data |
+
+## Platform Support
+
+| Platform | Architecture | Status |
+|----------|-------------|--------|
+| Linux | x64 (glibc) | Supported |
+| Linux | arm64 (glibc) | Supported |
+| macOS | arm64 (Apple Silicon) | Supported |
+| macOS | x64 (Intel) | Supported |
+| Windows | x64 | Supported |
+
+## Usage
+
+```typescript
+import Brainy from '@soulcraft/brainy'
+
+// cortex is auto-detected — no import or config needed
+const brain = new Brainy({ storage: { type: 'filesystem', rootDirectory: './data' } })
+await brain.init()
+
+// Check if native acceleration is active
+console.log(brain.getActivePlugins())
+// → ['@soulcraft/cortex']
+```
+
+### Manual Registration
+
+If auto-detection doesn't suit your setup, register the plugin manually:
+
+```typescript
+import Brainy from '@soulcraft/brainy'
+import cortexPlugin from '@soulcraft/cortex'
+
+const brain = new Brainy({ storage: { type: 'memory' } })
+brain.use(cortexPlugin)
+await brain.init()
+```
+
+### MmapFileSystemStorage
+
+When cortex is installed, a new storage adapter becomes available:
+
+```typescript
+const brain = new Brainy({
+  storage: { type: 'mmap-filesystem', rootDirectory: './data' }
+})
+```
+
+This extends the standard FileSystemStorage with binary blob support for zero-copy mmap access to LSM-tree SSTables.
+
+## Requirements
+
+- `@soulcraft/brainy` >= 7.0.0
+- Node.js >= 22 or Bun >= 1.3.0
+- Platform: Linux/macOS/Windows (see table above)
+
+## Direct Access
+
+For advanced use cases, you can access native bindings directly:
+
+```typescript
+import { loadNativeModule, isNativeAvailable } from '@soulcraft/cortex'
+
+if (isNativeAvailable()) {
+  const native = loadNativeModule()
+  const distance = native.cosineDistance(vectorA, vectorB)
+}
+```
+
+## License
+
+Commercial. See [LICENSE](./LICENSE) for details.

package/dist/graph/NativeGraphAdjacencyIndex.d.ts

@@ -0,0 +1,92 @@
+/**
+ * NativeGraphAdjacencyIndex — Thin TS wrapper around the Rust graph engine
+ *
+ * Handles async storage I/O while the Rust engine handles all in-memory
+ * data operations (4 LSM-trees, verb tracking, relationship counts).
+ *
+ * Storage pattern: adapter-controlled I/O with 3-tier fallback.
+ * - Tier 1 (mmap): saveBinaryBlob + getBinaryBlobPath → zero-copy queries
+ * - Tier 2 (binary blob): saveBinaryBlob only → binary format in memory
+ * - Tier 3 (legacy): saveMetadata → base64 JSON
+ *
+ * UnifiedCache integration stays in TS (getVerbCached, getVerbsBatchCached)
+ * since it coordinates cross-subsystem caching and requires async storage access.
+ */
+import type { GraphVerb, StorageAdapter } from '@soulcraft/brainy';
+export interface GraphIndexConfig {
+    maxIndexSize?: number;
+    rebuildThreshold?: number;
+    autoOptimize?: boolean;
+    flushInterval?: number;
+    memTableThreshold?: number;
+    maxSSTablesPerLevel?: number;
+}
+export interface GraphIndexStats {
+    totalRelationships: number;
+    sourceNodes: number;
+    targetNodes: number;
+    memoryUsage: number;
+    lastRebuild: number;
+    rebuildTime: number;
+}
+export declare class GraphAdjacencyIndex {
+    private storage;
+    private native;
+    private unifiedCache;
+    private config;
+    private initialized;
+    private isRebuilding;
+    private flushTimer?;
+    private rebuildStartTime;
+    private totalRelationshipsIndexed;
+    private isCompacting;
+    private hasBinaryBlobs;
+    private hasMmapPaths;
+    get isInitialized(): boolean;
+    constructor(storage: StorageAdapter, config?: GraphIndexConfig);
+    private ensureInitialized;
+    private populateVerbIdSetFromStorage;
+    getNeighbors(id: string, optionsOrDirection?: {
+        direction?: 'in' | 'out' | 'both';
+        limit?: number;
+        offset?: number;
+    } | 'in' | 'out' | 'both'): Promise<string[]>;
+    getVerbIdsBySource(sourceId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<string[]>;
+    getVerbIdsByTarget(targetId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<string[]>;
+    getVerbCached(verbId: string): Promise<GraphVerb | null>;
+    getVerbsBatchCached(verbIds: string[]): Promise<Map<string, GraphVerb>>;
+    addVerb(verb: GraphVerb): Promise<void>;
+    removeVerb(verbId: string): Promise<void>;
+    size(): number;
+    getRelationshipCountByType(type: string): number;
+    getTotalRelationshipCount(): number;
+    getAllRelationshipCounts(): Map<string, number>;
+    getRelationshipStats(): {
+        totalRelationships: number;
+        relationshipsByType: Record<string, number>;
+        uniqueSourceNodes: number;
+        uniqueTargetNodes: number;
+        totalNodes: number;
+    };
+    getStats(): GraphIndexStats;
+    isHealthy(): boolean;
+    rebuild(): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    /** Blob key for an SSTable: "graph-lsm/{treeName}/{sstableId}" */
+    private blobKey;
+    private loadTreeFromStorage;
+    private loadTreeSSTables;
+    private flushTree;
+    private compactTree;
+    private saveTreeManifest;
+    private startAutoFlush;
+    private calculateMemoryUsage;
+}
+//# sourceMappingURL=NativeGraphAdjacencyIndex.d.ts.map