@soulcraft/cor 3.0.0-rc.1

package/LICENSE

@@ -0,0 +1,16 @@
+Soulcraft Cor - 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,328 @@
+# @soulcraft/cor
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/soulcraftlabs/brainy/main/brainy.png" alt="Soulcraft" width="180">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@soulcraft/cor"><img src="https://badge.fury.io/js/%40soulcraft%2Fcor.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@soulcraft/cor"><img src="https://img.shields.io/npm/dm/@soulcraft/cor.svg" alt="npm downloads"></a>
+  <a href="https://soulcraft.com/pricing?focus=cor"><img src="https://img.shields.io/badge/license-commercial-blue.svg" alt="Commercial License"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg" alt="TypeScript"></a>
+</p>
+
+<p align="center">
+  <strong>Native Rust acceleration for <a href="https://www.npmjs.com/package/@soulcraft/brainy">@soulcraft/brainy</a>.</strong>
+</p>
+
+<p align="center">
+  Adaptive DiskANN to 1 B+ vectors · Triple-intelligence find() (metadata ∩ graph ∩ vector) · Time-travel reads (<code>db.asOf(g)</code>) · Sub-millisecond vector search at 1 M · 13–18× pgvector index latency on the reference host
+</p>
+
+```bash
+bun add @soulcraft/cor    # or: npm install @soulcraft/cor
+```
+
+**[soulcraft.com/docs](https://soulcraft.com/docs)** · **[Pricing](https://soulcraft.com/pricing?focus=cor)** · **[Benchmarks](https://github.com/soulcraftlabs/cor/blob/main/docs/performance.md)** · **[Comparison](https://github.com/soulcraftlabs/cor/blob/main/docs/comparison.md)**
+
+---
+
+Brainy handles your knowledge graph. Cor makes it fast — and scales it from one workspace to a billion vectors on a single machine.
+
+When performance matters — at scale, in production, with large embedding models — Cor automatically swaps in compiled Rust implementations for distance calculations, vector index, metadata filtering, graph adjacency, and embeddings. No code changes. No configuration changes. Add the package and it activates.
+
+**New in cor 3.0** *(measured numbers on bxl9000 — Ryzen 9 7950X3D / 184 GB / NVMe; reproducible from `scripts/verify-*.mjs`)*:
+
+- **Triple-intelligence find()** — Combines metadata filter + graph hop + vector similarity in a single query. **Substrate-composition p50 ≈ 0.230 ms at 1 M** (per-stage measured; this run is on a synthetic corpus, so end-to-end latency **and** recall are being re-validated on real-manifold data (SIFT) — see [docs/comparison.md](docs/comparison.md) honesty note).
+- **Adaptive DiskANN** — 100 % pure-Rust Vamana + PQ. Auto-engages on local storage. **MEASURED: p50 0.85 ms at 1 M** (`mode=auto`).
+- **Time-travel reads** (`db.asOf(g)` / `db.with(...)`) — Pin a generation, read the brain as it existed at that moment. All three shadow-page substrates (UUID↔int + verb endpoints) participate in the pin lifecycle.
+- **Competitive position: 13–18× pgvector index latency** (p50, reference host bxl9000), sub-millisecond p99 at 1 M. Latency, not a blanket "faster" — the recall-matched, real-data library A/B is in progress. See **[docs/comparison.md](https://github.com/soulcraftlabs/cor/blob/main/docs/comparison.md)** for methodology + honesty notes.
+
+Architecture: **[docs/diskann.md](https://github.com/soulcraftlabs/cor/blob/main/docs/diskann.md)** · Time-travel contract: **[docs/snapshot-safety.md](https://github.com/soulcraftlabs/cor/blob/main/docs/snapshot-safety.md)** · Performance budget: **[docs/performance-budget.md](https://github.com/soulcraftlabs/cor/blob/main/docs/performance-budget.md)** · Full verification: **[docs/verification-report.md](https://github.com/soulcraftlabs/cor/blob/main/docs/verification-report.md)** · **Upgrading from 2.x?** **[docs/migration-3.0.md](https://github.com/soulcraftlabs/cor/blob/main/docs/migration-3.0.md)**
+
+---
+
+## Quick Start
+
+```bash
+bun add @soulcraft/brainy @soulcraft/cor
+```
+
+```typescript
+import { Brainy, NounType } from '@soulcraft/brainy'
+
+const brain = new Brainy({
+  storage: { type: 'filesystem', rootDirectory: './data' },
+  plugins: ['@soulcraft/cor']
+})
+await brain.init()
+// [brainy] Plugin activated: @soulcraft/cor
+// All native providers registered — same API, Rust speed.
+
+await brain.add({ data: 'Native Rust SIMD acceleration', type: NounType.Concept })
+const results = await brain.find({ query: 'fast vector search' })
+```
+
+### Activate your license
+
+Free tier activates automatically — no key needed. For Pro/Enterprise:
+
+1. Get your activation code from [soulcraft.com/account](https://soulcraft.com/account)
+2. Run in your project directory:
+
+```bash
+npx @soulcraft/cor activate CX-XXXX-XXXX
+```
+
+This creates a `.soulcraft.json` in your project — commit it to your repository and it works everywhere (dev, staging, prod, Docker, CI).
+
+**Other CLI commands:**
+```bash
+npx cor status       # show license info
+npx cor deactivate   # remove license
+npx cor help         # all commands
+```
+
+License validation runs **locally in Rust** — no network calls at startup. Get a key at **[soulcraft.com/pricing](https://soulcraft.com/pricing?focus=cor)**.
+
+---
+
+## What Gets Accelerated
+
+Every provider listed here is a drop-in replacement — Brainy's plugin system wires them in automatically based on your license tier.
+
+| Subsystem | What Cor Provides |
+|-----------|---------------------|
+| **Adaptive DiskANN** | 100% pure-Rust Vamana α-pruned graph + Product Quantization. Single-machine billion-vector ANN search; MEASURED p50 0.85 ms at 1 M on bxl9000. Auto-engages on local-storage installs |
+| **Triple-intelligence find()** | Composes metadata filter + graph hop + vector ANN in one query. Substrate-composition p50 ≈ 0.230 ms at 1 M (per-stage measured on synthetic; end-to-end SIFT re-validation in progress) |
+| **Time-travel reads** | `db.asOf(g)` / `db.with(...)` — pin a generation, read the brain as it existed at that moment. All 3 substrates participate in the pin lifecycle |
+| **SIMD distance** | Float32 cosine; SQ8 uint8 cosine (81× faster); SQ4 nibble-packed |
+| **Embeddings** | Candle ML runtime — in-process, no Python sidecar, no HTTP roundtrip. CPU and Apple Metal |
+| **Batch embeddings** | Single Rust forward pass for bulk import and reindex |
+| **Metadata index** | Rust LSM-tree query/mutation engine with CRoaring bitmap posting lists. MEASURED 525 K inserts/sec at 100 M |
+| **Graph adjacency** | 4 LSM-trees + verb-endpoints shadow-page store with typed verb tracking |
+| **Entity ID mapper** | Mmap'd UUID ↔ u64 with shadow-page snapshot safety; supports 2 B+ entities |
+| **Vector quantization** | SQ8 (4× memory), SQ4 (8× memory), Product Quantization (16–32×) |
+| **Graph compression** | Delta-varint encoded connection lists |
+| **Roaring bitmaps** | CRoaring bindings — binary-compatible with `roaring-wasm` |
+| **Msgpack** | Native encode/decode |
+| **mmap storage** | Zero-copy SSTable reads via memory-mapped files; shadow-page LSM for snapshot safety |
+| **Aggregation engine** | Incremental updates with Rayon parallel rebuild |
+| **Compaction** | Pin-aware (respects `min_pinned_generation` for time-travel) + graph-aware BFS ordering for disk locality |
+
+### Scale envelope at a glance
+
+> **MEASURED at 1 M / 10 M / 100 M on bxl9000.** Source files cited in
+> `docs/verification-report.md`. 1 B numbers are projected from SIFT1B
+> trends + 100 M measured + Subramanya et al. (NeurIPS 2019) algorithm
+> latency model.
+
+| Vectors | RAM | DiskANN p50 | LSM filter p50 | Graph 2-hop p50 | **Composed find() p50** | Source |
+|--------:|---:|---:|---:|---:|---:|:---|
+| 1 M | 0.5–2 GB | **0.85 ms** | **23.8 µs** | **14.3 µs** | **0.230 ms** | bxl9000, measured |
+| 10 M | 1–5 GB | _running_ | **537 µs** | _running_ | _projected_ | bxl9000, partial |
+| 100 M | 5–20 GB | _projected_ | **5.85 ms** | _projected_ | _projected_ | bxl9000, LSM only |
+| **1 B** | **20–70 GB** | **5–10 ms** (PROJECTED) | _projected_ | _projected_ | _projected_ | SIFT1B reference |
+
+All numbers are for the search engine itself. End-to-end query latency adds entity hydration; see **[docs/scaling.md](https://github.com/soulcraftlabs/cor/blob/main/docs/scaling.md#operational-ceiling-at-1-b)** for the honest full-stack story.
+
+**Running many brains per box (per-tenant pools, e.g. one brain per user)?** Cor auto-raises its own soft open-file limit on startup and warns you (with the exact fix) if the OS file/mmap limits would bottleneck a pool before RAM. The hard `ulimit -n` + Linux `vm.max_map_count` must be set by your deployment — copy-paste Docker / Compose / Kubernetes / host config in **[docs/deployment-limits.md](https://github.com/soulcraftlabs/cor/blob/main/docs/deployment-limits.md)**.
+
+---
+
+## Performance
+
+All numbers **measured** with `vitest bench` on Linux x64.
+
+### Distance Calculations — 384-dimensional vectors (all-MiniLM-L6-v2)
+
+| Operation | Throughput | Latency | vs full-precision |
+|-----------|----------:|--------:|:-----------------:|
+| `cosineDistance` (float32) | 45,965 ops/s | 21.8 μs | baseline |
+| `cosineDistanceSq8` (quantized) | 3,715,855 ops/s | 0.27 μs | **81×** |
+| `cosineDistanceSq8Batch` (1K vectors) | 2,142 ops/s | 467 μs | **28×** |
+| `cosineDistanceBatch` (float32, 1K) | 77 ops/s | 13.0 ms | — |
+| `quantizeSq8` (encode 384-dim) | 74,020 ops/s | 13.5 μs | — |
+
+**Quantize once at index time. Get 81× faster distances at every query.**
+
+### Aggregation Engine
+
+| Operation | Throughput | Latency |
+|-----------|----------:|--------:|
+| `incrementalUpdate` (1K entities, 3 metrics) | 809 ops/s | 1.2 ms |
+| `rebuildAggregate` (10K entities, 5 groups) | 475 ops/s | 2.1 ms |
+| `rebuildAggregate` (100K entities, Rayon) | 66 ops/s | 15.2 ms |
+| `queryAggregate` (1K groups, sort + paginate) | 986 ops/s | 1.0 ms |
+
+### Serialization
+
+| Operation | Throughput | Latency |
+|-----------|----------:|--------:|
+| `msgpackEncode` (1K entities) | 235 ops/s | 4.3 ms |
+| `msgpackDecode` (1K entities) | 355 ops/s | 2.8 ms |
+| `RoaringBitmap32.serialize` (10K elements) | 361,258 ops/s | 2.8 μs |
+| `RoaringBitmap32.deserialize` (10K elements) | 548,714 ops/s | 1.8 μs |
+| `encodeConnections` (1K lists) | 913 ops/s | 1.1 ms |
+| `decodeConnections` (1K lists) | 1,078 ops/s | 928 μs |
+
+Full breakdown: **[docs/performance.md](https://github.com/soulcraftlabs/cor/blob/main/docs/performance.md)** · Side-by-side comparison: **[docs/comparison.md](https://github.com/soulcraftlabs/cor/blob/main/docs/comparison.md)**
+
+---
+
+## Free Tier vs Pro
+
+| Feature | Free | Pro / Enterprise |
+|---------|:----:|:----------------:|
+| mmap-enhanced filesystem storage | ✓ | ✓ |
+| **Adaptive DiskANN billion-scale index** | — | ✓ |
+| **Triple-intelligence find() composition** | — | ✓ |
+| **Time-travel reads (`db.asOf(g)`)** | — | ✓ |
+| SIMD distance (float32, SQ8, SQ4) | — | ✓ |
+| Vector quantization (SQ8, SQ4, PQ) | — | ✓ |
+| Candle ML embeddings (CPU / Metal) | — | ✓ |
+| Native metadata index (LSM + CRoaring) | — | ✓ |
+| Graph adjacency index (4 LSM-trees + verb endpoints) | — | ✓ |
+| Entity ID mapper (mmap UUID ↔ u64) | — | ✓ |
+| Snapshot-safe shadow-page LSM stores | — | ✓ |
+| CRoaring bitmap bindings | — | ✓ |
+| Native msgpack encode/decode | — | ✓ |
+| Incremental aggregation engine | — | ✓ |
+| Pin-aware + graph-aware compaction | — | ✓ |
+
+Free tier activates automatically with no key. Pro/Enterprise require a license key — see [soulcraft.com/pricing](https://soulcraft.com/pricing?focus=cor).
+
+---
+
+## Verify Activation
+
+Check which providers are active after `brain.init()`:
+
+```typescript
+const diag = brain.diagnostics()
+console.log(diag.providers)
+// {
+//   distance:      { source: 'plugin' },
+//   vectorIndex:   { source: 'plugin' },   // Adaptive DiskANN
+//   embeddings:    { source: 'plugin' },
+//   metadataIndex: { source: 'plugin' },
+//   graphIndex:    { source: 'plugin' },
+//   ...
+// }
+```
+
+Require specific providers in production — fail fast if something isn't native:
+
+```typescript
+brain.requireProviders(['distance', 'vectorIndex', 'embeddings', 'metadataIndex', 'graphIndex'])
+```
+
+---
+
+## License & Subscription
+
+Cor uses a **subscription license** with offline validation. Your key is an Ed25519-signed JWT verified entirely in Rust at process start — no network call required. A background heartbeat runs once every 24 hours to check subscription status.
+
+### Graceful Degradation
+
+Cor **never hard-blocks** your process on a lapsed license. If your subscription lapses:
+
+1. A warning appears on the next process start
+2. A **14-day grace period** begins
+3. After the grace period, Cor silently degrades to free tier — storage keeps working, compute acceleration pauses
+
+```
+[cor] Subscription canceled. Renew at soulcraft.com/account. Grace period: 12 days remaining.
+```
+
+Renew at any time during the grace period to restore compute acceleration instantly on the next startup.
+
+### Key Source
+
+Cor reads `.soulcraft.json` from the project root (`process.cwd()`):
+
+```json
+{ "cor": "CX-7F3A-9B2D" }
+```
+
+On first use, short codes are exchanged for a JWT via `soulcraft.com/api/license/exchange` and cached in memory for the process lifetime. The file itself is never rewritten — each cold start re-exchanges if needed.
+
+Run `npx @soulcraft/cor activate CX-XXXX-XXXX` to create this file.
+
+---
+
+## Platform Support
+
+Pre-built binaries ship inside the npm package. No compile step needed.
+
+| Platform | Architecture | Binary Included |
+|----------|-------------|:---------------:|
+| Linux | x64 (glibc 2.17+) | ✓ |
+| Linux | arm64 (glibc) | ✓ |
+| macOS | arm64 (Apple Silicon) | ✓ |
+| macOS | x64 (Intel) | ✓ |
+| Windows | x64 | ✓ |
+
+> **GPU / CUDA acceleration** is available for Enterprise customers. [Contact us](https://soulcraft.com/contact-sales) to discuss your requirements.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---------|-------------|-----|
+| `[cor] missing sc_cor_ prefix` | `.soulcraft.json` contains wrong key or non-cor key | Re-run `npx @soulcraft/cor activate CX-XXXX-XXXX` |
+| `[cor] license expired` | Key is past its expiry date | Renew at [soulcraft.com/account](https://soulcraft.com/account) |
+| `[cor] invalid signature` | Key was truncated or corrupted | Re-activate: `npx @soulcraft/cor activate CX-XXXX-XXXX` |
+| `[cor] invalid product: workshop` | Workshop key used for Cor | Keys are product-specific — get a Cor key at [soulcraft.com/account](https://soulcraft.com/account) |
+| `[cor] native module unavailable` | Native binary not found for current platform | Check platform table above |
+| Compute providers inactive, no warning | No key set — free tier is active | Run `npx @soulcraft/cor activate CX-XXXX-XXXX` |
+| `[cor] License lapsed. Compute acceleration disabled.` | Grace period expired | Renew at [soulcraft.com/account](https://soulcraft.com/account) |
+| `[cor] License suspended. Contact support.` | Account suspended | Open a ticket at [soulcraft.com/issues](https://soulcraft.com/issues) |
+
+---
+
+## Direct Native Access
+
+For advanced use cases — custom pipelines, tooling, benchmarks — access the Rust bindings directly without Brainy:
+
+```typescript
+import { loadNativeModule, isNativeAvailable } from '@soulcraft/cor'
+
+if (isNativeAvailable()) {
+  const native = loadNativeModule()
+  const dist = native.cosineDistance(vectorA, vectorB)
+  const encoded = native.msgpackEncode(data)
+}
+```
+
+---
+
+## Requirements
+
+- **Bun 1.0+** (recommended) or **Node.js 22 LTS**
+- `@soulcraft/brainy >= 7.15.4`
+
+```bash
+bun add @soulcraft/brainy @soulcraft/cor    # Bun — best performance
+npm install @soulcraft/brainy @soulcraft/cor # Node.js — fully supported
+```
+
+---
+
+## Learn More
+
+- **[Brainy documentation](https://soulcraft.com/docs)** — Full Brainy API reference
+- **[Plugin system](https://github.com/soulcraftlabs/brainy/blob/main/docs/PLUGINS.md)** — How Brainy plugins work
+- **[Performance benchmarks](https://github.com/soulcraftlabs/cor/blob/main/docs/performance.md)** — Full benchmark table with methodology
+- **[Brainy vs Cor comparison](https://github.com/soulcraftlabs/cor/blob/main/docs/comparison.md)** — Side-by-side feature and speed comparison
+- **[soulcraft.com/pricing](https://soulcraft.com/pricing?focus=cor)** — Pro and Enterprise plans
+
+---
+
+## License
+
+Commercial — [soulcraft.com/pricing](https://soulcraft.com/pricing?focus=cor)
+
+Free tier (mmap storage) is available without a license key.
+Pro and Enterprise tiers require a paid subscription.

package/dist/aggregation/NativeAggregationEngine.d.ts

@@ -0,0 +1,118 @@
+/**
+ * NativeAggregationEngine — TypeScript wrapper implementing Brainy's AggregationProvider.
+ *
+ * Delegates all computation to the Rust NativeAggregationEngine:
+ * - Incremental updates with BTreeMap precise MIN/MAX
+ * - Rayon parallel rebuild across CPU cores
+ * - Welford's online stddev/variance
+ * - Integer timestamp bucketing (no Date object allocation)
+ * - Compiled source filters on rebuild path
+ *
+ * Architecture:
+ * - Rust owns: all metric computation, group key calculation, state management
+ * - TS owns: provider interface conformance, Brainy ↔ Rust type translation
+ *
+ * The wrapper implements Brainy's AggregationProvider interface so it can be
+ * registered via `context.registerProvider('aggregation', ...)` and used
+ * transparently by AggregationIndex.
+ */
+import type { AggregateDefinition, AggregateGroupState, AggregateQueryParams, AggregateResult, AggregationProvider, GroupByDimension } from '@soulcraft/brainy';
+/**
+ * Native Rust-accelerated aggregation provider.
+ *
+ * Implements AggregationProvider for transparent use by Brainy's AggregationIndex.
+ * All metric computation happens in Rust; results are translated back to
+ * Brainy's TypeScript types at the FFI boundary.
+ *
+ * @example
+ * ```typescript
+ * // Registered automatically by cor plugin — no user action needed.
+ * // When cor is installed, AggregationIndex uses this provider for:
+ * // - 50x faster incremental updates
+ * // - 100x faster rebuilds (Rayon parallel)
+ * // - Precise MIN/MAX after deletes (BTreeMap, never stale)
+ * // - Online stddev/variance (Welford's algorithm)
+ * ```
+ */
+export declare class NativeAggregationProvider implements AggregationProvider {
+    private engine;
+    constructor();
+    /**
+     * Register an aggregate definition with the Rust engine.
+     * Compiles the definition for efficient hot-path processing.
+     * Called by AggregationIndex.defineAggregate().
+     */
+    defineAggregate(def: AggregateDefinition): void;
+    /**
+     * Remove a registered aggregate definition and its internal state.
+     * Called by AggregationIndex.removeAggregate().
+     */
+    removeAggregate(name: string): void;
+    /**
+     * Incrementally update aggregation state for an entity change.
+     *
+     * The entity is passed directly to Rust via NAPI serde-json (no JSON.stringify
+     * needed — NAPI converts JS objects to serde_json::Value automatically).
+     *
+     * Returns the modified group states for Brainy to merge into its state maps.
+     *
+     * @param name - Aggregate name
+     * @param def - Full aggregate definition (for compatibility; Rust uses cached version)
+     * @param entity - The entity that changed
+     * @param op - Operation type: 'add', 'update', or 'delete'
+     * @param prev - Previous entity state (required for 'update' ops)
+     * @returns Modified group states
+     */
+    incrementalUpdate(name: string, def: AggregateDefinition, entity: Record<string, unknown>, op: 'add' | 'update' | 'delete', prev?: Record<string, unknown>): AggregateGroupState[];
+    /**
+     * Compute the group key for an entity given GROUP BY dimensions.
+     *
+     * Uses integer timestamp arithmetic for time-windowed dimensions
+     * (no Date object allocation).
+     *
+     * @param entity - Entity to compute group key for
+     * @param groupBy - GROUP BY dimensions
+     * @returns Group key object
+     */
+    computeGroupKey(entity: Record<string, unknown>, groupBy: GroupByDimension[]): Record<string, string | number>;
+    /**
+     * Rebuild an entire aggregate from scratch using Rayon parallel iteration.
+     *
+     * Distributes entities across CPU cores. Each thread accumulates into
+     * thread-local state maps, merged at the end using Chan-Golub-LeVeque
+     * parallel variance formula for correct Welford's M2 merging.
+     *
+     * For 100K entities on 8 cores: ~50ms vs ~5s in JS (100x speedup).
+     *
+     * @param def - Aggregate definition
+     * @param entities - All entities to rebuild from
+     * @returns Map of serialized group key → group state
+     */
+    rebuildAggregate(def: AggregateDefinition, entities: Array<Record<string, unknown>>): Map<string, AggregateGroupState>;
+    /**
+     * Query aggregate state with filtering, sorting, and pagination.
+     *
+     * Uses internal Rust state when available, falls back to parsing
+     * the provided state map.
+     *
+     * @param state - State map from Brainy (used as fallback)
+     * @param params - Query parameters (where, orderBy, limit, offset)
+     * @returns Sorted, filtered, paginated query results
+     */
+    queryAggregate(state: Map<string, AggregateGroupState>, params: AggregateQueryParams): AggregateResult[];
+    /**
+     * Restore previously serialized Rust state.
+     * Called during AggregationIndex.init() with persisted state data.
+     */
+    restoreState(data: string): void;
+    /**
+     * Serialize internal Rust state for persistence.
+     * Called during AggregationIndex.flush().
+     */
+    serializeState(): string;
+    /**
+     * Get engine statistics: definition count, total groups, etc.
+     */
+    getStats(): Record<string, unknown>;
+}
+//# sourceMappingURL=NativeAggregationEngine.d.ts.map

package/dist/aggregation/NativeAggregationEngine.js

@@ -0,0 +1,186 @@
+/**
+ * NativeAggregationEngine — TypeScript wrapper implementing Brainy's AggregationProvider.
+ *
+ * Delegates all computation to the Rust NativeAggregationEngine:
+ * - Incremental updates with BTreeMap precise MIN/MAX
+ * - Rayon parallel rebuild across CPU cores
+ * - Welford's online stddev/variance
+ * - Integer timestamp bucketing (no Date object allocation)
+ * - Compiled source filters on rebuild path
+ *
+ * Architecture:
+ * - Rust owns: all metric computation, group key calculation, state management
+ * - TS owns: provider interface conformance, Brainy ↔ Rust type translation
+ *
+ * The wrapper implements Brainy's AggregationProvider interface so it can be
+ * registered via `context.registerProvider('aggregation', ...)` and used
+ * transparently by AggregationIndex.
+ */
+import { loadNativeModule } from '../native/index.js';
+/**
+ * Native Rust-accelerated aggregation provider.
+ *
+ * Implements AggregationProvider for transparent use by Brainy's AggregationIndex.
+ * All metric computation happens in Rust; results are translated back to
+ * Brainy's TypeScript types at the FFI boundary.
+ *
+ * @example
+ * ```typescript
+ * // Registered automatically by cor plugin — no user action needed.
+ * // When cor is installed, AggregationIndex uses this provider for:
+ * // - 50x faster incremental updates
+ * // - 100x faster rebuilds (Rayon parallel)
+ * // - Precise MIN/MAX after deletes (BTreeMap, never stale)
+ * // - Online stddev/variance (Welford's algorithm)
+ * ```
+ */
+export class NativeAggregationProvider {
+    engine;
+    constructor() {
+        const native = loadNativeModule();
+        this.engine = new native.NativeAggregationEngine();
+    }
+    /**
+     * Register an aggregate definition with the Rust engine.
+     * Compiles the definition for efficient hot-path processing.
+     * Called by AggregationIndex.defineAggregate().
+     */
+    defineAggregate(def) {
+        this.engine.defineAggregate(JSON.stringify(def));
+    }
+    /**
+     * Remove a registered aggregate definition and its internal state.
+     * Called by AggregationIndex.removeAggregate().
+     */
+    removeAggregate(name) {
+        this.engine.removeAggregate(name);
+    }
+    /**
+     * Incrementally update aggregation state for an entity change.
+     *
+     * The entity is passed directly to Rust via NAPI serde-json (no JSON.stringify
+     * needed — NAPI converts JS objects to serde_json::Value automatically).
+     *
+     * Returns the modified group states for Brainy to merge into its state maps.
+     *
+     * @param name - Aggregate name
+     * @param def - Full aggregate definition (for compatibility; Rust uses cached version)
+     * @param entity - The entity that changed
+     * @param op - Operation type: 'add', 'update', or 'delete'
+     * @param prev - Previous entity state (required for 'update' ops)
+     * @returns Modified group states
+     */
+    incrementalUpdate(name, def, entity, op, prev) {
+        // Ensure definition is registered (idempotent if already registered)
+        this.engine.defineAggregate(JSON.stringify(def));
+        const resultJson = this.engine.incrementalUpdate(name, entity, op, prev);
+        const rawGroups = JSON.parse(resultJson);
+        return rawGroups.map(normalizeGroupState);
+    }
+    /**
+     * Compute the group key for an entity given GROUP BY dimensions.
+     *
+     * Uses integer timestamp arithmetic for time-windowed dimensions
+     * (no Date object allocation).
+     *
+     * @param entity - Entity to compute group key for
+     * @param groupBy - GROUP BY dimensions
+     * @returns Group key object
+     */
+    computeGroupKey(entity, groupBy) {
+        const resultJson = this.engine.computeGroupKey(entity, JSON.stringify(groupBy));
+        return JSON.parse(resultJson);
+    }
+    /**
+     * Rebuild an entire aggregate from scratch using Rayon parallel iteration.
+     *
+     * Distributes entities across CPU cores. Each thread accumulates into
+     * thread-local state maps, merged at the end using Chan-Golub-LeVeque
+     * parallel variance formula for correct Welford's M2 merging.
+     *
+     * For 100K entities on 8 cores: ~50ms vs ~5s in JS (100x speedup).
+     *
+     * @param def - Aggregate definition
+     * @param entities - All entities to rebuild from
+     * @returns Map of serialized group key → group state
+     */
+    rebuildAggregate(def, entities) {
+        const resultJson = this.engine.rebuildAggregate(JSON.stringify(def), JSON.stringify(entities));
+        const rawGroups = JSON.parse(resultJson);
+        const stateMap = new Map();
+        for (const raw of rawGroups) {
+            const group = normalizeGroupState(raw);
+            const serialized = serializeGroupKey(group.groupKey);
+            stateMap.set(serialized, group);
+        }
+        return stateMap;
+    }
+    /**
+     * Query aggregate state with filtering, sorting, and pagination.
+     *
+     * Uses internal Rust state when available, falls back to parsing
+     * the provided state map.
+     *
+     * @param state - State map from Brainy (used as fallback)
+     * @param params - Query parameters (where, orderBy, limit, offset)
+     * @returns Sorted, filtered, paginated query results
+     */
+    queryAggregate(state, params) {
+        // Serialize state for Rust (convert Map to array)
+        const groups = Array.from(state.values());
+        const stateJson = JSON.stringify(groups);
+        const resultJson = this.engine.queryAggregate(stateJson, JSON.stringify(params));
+        return JSON.parse(resultJson);
+    }
+    /**
+     * Restore previously serialized Rust state.
+     * Called during AggregationIndex.init() with persisted state data.
+     */
+    restoreState(data) {
+        this.engine.restoreState(data);
+    }
+    /**
+     * Serialize internal Rust state for persistence.
+     * Called during AggregationIndex.flush().
+     */
+    serializeState() {
+        return this.engine.serializeState();
+    }
+    /**
+     * Get engine statistics: definition count, total groups, etc.
+     */
+    getStats() {
+        return JSON.parse(this.engine.stats);
+    }
+}
+/**
+ * Normalize raw Rust output to Brainy's AggregateGroupState format.
+ * Handles null → Infinity/NegInfinity conversion for min/max.
+ */
+function normalizeGroupState(raw) {
+    const metrics = {};
+    for (const [name, state] of Object.entries(raw.metrics)) {
+        metrics[name] = {
+            sum: state.sum,
+            count: state.count,
+            min: state.min ?? Infinity,
+            max: state.max ?? -Infinity,
+            m2: state.m2 ?? 0
+        };
+    }
+    return {
+        groupKey: raw.groupKey,
+        metrics,
+        materializedEntityId: raw.materializedEntityId ?? undefined,
+        lastUpdated: raw.lastUpdated
+    };
+}
+/**
+ * Serialize a group key to a deterministic string.
+ * Must match Brainy's `serializeGroupKey()` for state compatibility.
+ */
+function serializeGroupKey(groupKey) {
+    const sorted = Object.keys(groupKey).sort();
+    return sorted.map(k => `${k}=${groupKey[k]}`).join('|');
+}
+//# sourceMappingURL=NativeAggregationEngine.js.map

package/dist/cli.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * cor CLI — license management for @soulcraft/cor
+ *
+ * Commands:
+ *   activate <code-or-key>   Write activation code or JWT to .soulcraft.json
+ *   status                   Show current license configuration and validation result
+ *   deactivate               Remove the cor license from .soulcraft.json
+ *   help                     Print this help text
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map