@soulcraft/cor 3.0.0-rc.1 → 3.0.1

package/README.md

@@ -1,328 +1,211 @@
-# @soulcraft/cor
+<p align="center">
+  <img src="https://raw.githubusercontent.com/soulcraftlabs/brainy/main/brainy.png" alt="Cor" width="180">
+</p>
+
+<h1 align="center">Cor</h1>
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/soulcraftlabs/brainy/main/brainy.png" alt="Soulcraft" width="180">
+  <b>One engine. Any scale. Your hardware.</b><br>
+  The native accelerator for <a href="https://www.npmjs.com/package/@soulcraft/brainy">@soulcraft/brainy</a> — billion-entity vector + graph + metadata<br>
+  search on a single machine, with zero code changes and zero configuration.
 </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/v/@soulcraft/cor.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/docs"><img src="https://img.shields.io/badge/docs-soulcraft.com-blue.svg" alt="Documentation"></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
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#exact-filters-inside-the-vector-walk">Filter pushdown</a> ·
+  <a href="#feature-tour">Features</a> ·
+  <a href="#one-box-hundreds-of-brains--or-one-brain-at-billion-scale">Scale</a> ·
+  <a href="#measured-not-promised">Benchmarks</a> ·
+  <a href="#learn-more">Docs</a>
 </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`)*:
+[Brainy](https://github.com/soulcraftlabs/brainy) is the open-source knowledge database — vectors, relationships, metadata, and full-text in one MIT-licensed engine. Cor swaps compiled Rust in under every hot path. **No code changes. No configuration.** Install it and brainy (≥ 8.0.9) auto-detects it — loudly: activation prints `Providers: 10/10 native`, a missing license warns by name, and a broken install makes `init()` throw rather than quietly run slow. **Remove it and everything keeps working** on the same files, at open-source speed. That's the contract in both directions.
 
-- **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.
+| Brainy runs it as | Cor replaces it with | You get |
+|---|---|---|
+| HNSW vector index (in-RAM) | **Adaptive DiskANN** — mmap-native, self-tuning, streaming segments | billion-scale ANN on one box; recall@10 **0.96 at 100M** (measured) |
+| `find()` composed in JS | one fused native query: metadata ∩ graph ∩ vector | exact filters **inside** the vector walk, not after it |
+| JSON field index | LSM postings + columnar sort/aggregate, mmap-durable | cold open serves instantly — restart = warm (measured) |
+| graph adjacency in JS maps | u64 LSM adjacency + native traversal/analytics | whole-graph reads as single cursor walks |
+| JS distance loops | SIMD kernels (f32, SQ8, SQ4-packed) | the hot inner loop in vector search, compiled |
+| WASM embedding model | Candle ML runtime, in-process | batch on-box embeddings — no API fees, no data egress |
+| time-travel reads in JS | generation-pinned reads across all three substrates | `asOf()` at native speed |
 
-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
+## Quick start
 
 ```bash
-bun add @soulcraft/brainy @soulcraft/cor
+npm install @soulcraft/cor    # or: bun add @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' })
-```
+import { Brainy, NounType, VerbType } from '@soulcraft/brainy'
 
-### Activate your license
+const brain = new Brainy({ storage: { type: 'filesystem', path: './data' } })
+await brain.init() // cor auto-detected (brainy ≥ 8.0.9) — look for "Providers: 10/10 native"
 
-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:
+const cor = await brain.add({
+  data: 'Cor swaps compiled Rust in under every Brainy hot path',
+  type: NounType.Concept,
+  subtype: 'library',
+  metadata: { layer: 'native', year: 2026 },
+})
+const brainy = await brain.add({
+  data: 'Brainy is the open-source knowledge database',
+  type: NounType.Concept,
+  subtype: 'library',
+  metadata: { layer: 'engine', year: 2026 },
+})
+await brain.relate({ from: cor, to: brainy, type: VerbType.DependsOn, subtype: 'runtime' })
 
-```bash
-npx @soulcraft/cor activate CX-XXXX-XXXX
+const hits = await brain.find({
+  query: 'native acceleration',   // vector — what it means
+  where: { layer: 'native' },     // metadata — pushed INTO the walk
+  connected: { to: brainy },      // graph — what it touches
+})                                // one call, three indexes, fused
 ```
 
-This creates a `.soulcraft.json` in your project — commit it to your repository and it works everywhere (dev, staging, prod, Docker, CI).
+**Activate** (paid tiers; free = just use brainy):
 
-**Other CLI commands:**
 ```bash
-npx cor status       # show license info
-npx cor deactivate   # remove license
-npx cor help         # all commands
+npx @soulcraft/cor login          # browser sign-in, like `gh auth login`
+# or, for servers / CI:  export COR_LICENSE_KEY=sc_cor_...
 ```
 
-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)
+Keys verify **offline** in Rust — no network call at startup, no license server to run.
 
-| 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 | — |
+## Exact filters inside the vector walk
 
-**Quantize once at index time. Get 81× faster distances at every query.**
+Pure vector databases post-filter — search first, discard non-matches — so selective filters return too few or lower-recall results. Cor computes the exact matching set first (roaring-bitmap intersection), searches only that provably-correct space, and switches to an exact scan when the set is small (recall 1.0).
 
-### 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)**
-
----
+```typescript
+await brain.find({
+  query: 'quarterly revenue anomalies',
+  where: { region: 'EMEA', year: 2026 },   // resolved to an exact bitmap FIRST
+})
+// the vector walk only ever visits entities that already match —
+// selective filters get MORE accurate, not less
+```
 
-## 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).
+*Cor pushes the exact filter into the vector search; everyone else filters after.*
 
----
+## Feature tour
 
-## Verify Activation
+### Adaptive DiskANN — it tunes itself to your machine
 
-Check which providers are active after `brain.init()`:
+A 100% pure-Rust implementation of the DiskANN algorithm (Microsoft Research, NeurIPS 2019: Vamana graphs + product quantization + an mmap-native format). Zero knobs, by design:
 
 ```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' },
-//   ...
-// }
+const brain = new Brainy({ storage: { type: 'filesystem', path: './data' } })
+await brain.init()
+// that's the entire configuration — on every machine, at every scale
 ```
 
-Require specific providers in production — fail fast if something isn't native:
+It observes available RAM and picks in-memory / compressed / on-disk operation, widens its search with corpus size, shares the box fairly with sibling instances, and grows its id space to ~51B entities. Same binary, same files — from a laptop to a 128 GB server, it simply uses what it finds.
 
-```typescript
-brain.requireProviders(['distance', 'vectorIndex', 'embeddings', 'metadataIndex', 'graphIndex'])
-```
+**[How Adaptive DiskANN works](docs/diskann.md)** · **[ADR-002: why 100% Rust](docs/ADR-002-diskann-100-percent-rust.md)**
 
----
+### Streaming inserts that never freeze
 
-## License & Subscription
+Writes absorb instantly and flush to small immutable segments in **O(new-data)** — seconds at any corpus size, not hours of reindexing. Index maintenance runs off-thread; consolidation is rare, background, and **never blocks a read or a write**.
 
-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.
+```typescript
+// keep writing at any corpus size — reads stay live throughout
+for (const doc of firehose) await brain.add(doc)
+await brain.find({ query: 'still answering' })   // never waits on a rebuild
+```
 
-### Graceful Degradation
+A brain that grows fast never hits a rebuild wall.
 
-Cor **never hard-blocks** your process on a lapsed license. If your subscription lapses:
+### Time travel
 
-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
+Point-in-time queries across vectors, graph, and metadata together — plus speculative transactions. No other vector database ships this.
 
-```
-[cor] Subscription canceled. Renew at soulcraft.com/account. Grace period: 12 days remaining.
+```typescript
+const lastWeek = await brain.asOf(Date.now() - 7 * 86_400_000)
+await lastWeek.find({ query: 'what did we know then?' })   // full query surface, past state
 ```
 
-Renew at any time during the grace period to restore compute acceleration instantly on the next startup.
+**[ADR-003: semantic time travel](docs/ADR-003-semantic-time-travel.md)**
 
-### Key Source
+### Cold start = warm
 
-Cor reads `.soulcraft.json` from the project root (`process.cwd()`):
+Every index is mmap-durable — the files *are* the state. A restart serves identical results from the first query, with no rebuild and no warm-up phase (measured: cold-reopen recall matches warm exactly).
 
-```json
-{ "cor": "CX-7F3A-9B2D" }
-```
+**[Snapshot safety](docs/snapshot-safety.md)**
 
-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.
+### Local embeddings, embedded engine
 
-Run `npx @soulcraft/cor activate CX-XXXX-XXXX` to create this file.
+An on-box ML runtime (Candle) — no per-document API fees, no data egress, fully offline-capable. And the whole thing is a library, not a database server: nothing to deploy, monitor, or operate.
 
----
+### Automatic upgrades
 
-## Platform Support
+Opening an older-format brain triggers a coordinated, observable migration: progress reporting, an automatic pre-upgrade backup, and a guarantee it never serves half-built state or loses a write.
 
-Pre-built binaries ship inside the npm package. No compile step needed.
+**[Upgrading from 2.x / brainy 7.x](docs/migration-3.0.md)**
 
-| Platform | Architecture | Binary Included |
-|----------|-------------|:---------------:|
-| Linux | x64 (glibc 2.17+) | ✓ |
-| Linux | arm64 (glibc) | ✓ |
-| macOS | arm64 (Apple Silicon) | ✓ |
-| macOS | x64 (Intel) | ✓ |
-| Windows | x64 | ✓ |
+## One box, hundreds of brains — or one brain at billion scale
 
-> **GPU / CUDA acceleration** is available for Enterprise customers. [Contact us](https://soulcraft.com/contact-sales) to discuss your requirements.
+The same zero-config design serves both extremes. **Per-user isolation:** run one brain per user or customer — each a physically separate database (own files, own indexes; no shared store, no cross-tenant query surface to secure). Every brain sizes itself from *observed RAM ÷ active brains*, a resource manager rebalances budgets at runtime, and mmap paging means idle tenants cost almost nothing — hundreds of isolated brains fit one commodity box. **Or scale one up:** the identical engine takes a single brain to billions of entities on that same box. No sharding tier, no "multi-tenant edition" — one design, both shapes.
 
----
+**[Scaling: sizing, tenants, limits](docs/scaling.md)**
 
-## Troubleshooting
+## Measured, not promised
 
-| 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) |
+SIFT benchmarks on commodity-class hardware; reproducible via `scripts/verify-*.mjs`; methodology + honesty notes in [docs/comparison.md](docs/comparison.md).
 
----
+| Scale | Recall@10 | Median latency |
+|---|---|---|
+| 1M | **0.9942** | 0.31 ms |
+| 10M | **0.9647** | 1.33 ms |
+| 100M | **0.9559** | ~7 ms — one box, at the published DiskANN billion-scale operating point |
+| 1B | in validation | measured run in progress; labeled projected until it lands |
 
-## Direct Native Access
+Cold-reopen recall matches warm exactly (measured). The write path holds flat RSS from 100k → 1M entities (measured). Billion-scale claims stay labeled until the 1B run completes — that's the house rule.
 
-For advanced use cases — custom pipelines, tooling, benchmarks — access the Rust bindings directly without Brainy:
+## Built for teams that can't send data anywhere
 
-```typescript
-import { loadNativeModule, isNativeAvailable } from '@soulcraft/cor'
+Everything runs on your hardware, in your process: search, storage, **and embedding generation** (the on-box ML runtime means documents never leave the machine, even to be vectorized). Air-gapped deployments work — license keys verify offline, and the daily license ping (key id, machine fingerprint, size bucket; never data) degrades gracefully when there's no route out. Point-in-time queries give you an audit dimension most databases can't: *what did the system know, and when?*
 
-if (isNativeAvailable()) {
-  const native = loadNativeModule()
-  const dist = native.cosineDistance(vectorA, vectorB)
-  const encoded = native.msgpackEncode(data)
-}
-```
+## Licensing that never breaks your app
 
----
+Start free on brainy. When you outgrow it, `npm install @soulcraft/cor` — nothing else changes. And in the other direction: no key — or an expired one, or no network — means cor quietly steps aside and you're running open-source brainy on the same files. **There is no kill switch, and we will never build one.** Pricing follows the size of your brain, not seats or nodes: free under 1M entities (that's brainy), then simple tiers as you grow. Once a day cor reports its key id, a machine fingerprint, and a coarse size bucket — never data, queries, or content. See [soulcraft.com/pricing](https://soulcraft.com/pricing?focus=cor).
 
 ## Requirements
 
-- **Bun 1.0+** (recommended) or **Node.js 22 LTS**
-- `@soulcraft/brainy >= 7.15.4`
+- Node.js ≥ 22 (Bun ≥ 1.1 as a runtime) · TypeScript-native, ESM
+- `@soulcraft/brainy` ≥ 8.0 · local filesystem storage (mmap requires real files)
+- 32 GB RAM serves ~1B entities; 64 GB recommended — see [docs/scaling.md](docs/scaling.md)
 
-```bash
-bun add @soulcraft/brainy @soulcraft/cor    # Bun — best performance
-npm install @soulcraft/brainy @soulcraft/cor # Node.js — fully supported
-```
+## Learn more
 
----
+| Topic | Doc |
+|---|---|
+| How Adaptive DiskANN works | [docs/diskann.md](docs/diskann.md) · [ADR-002: why 100% Rust](docs/ADR-002-diskann-100-percent-rust.md) |
+| Benchmarks + methodology | [docs/performance.md](docs/performance.md) · [docs/comparison.md](docs/comparison.md) · [docs/verification-report.md](docs/verification-report.md) |
+| Scaling: sizing, tenants, limits | [docs/scaling.md](docs/scaling.md) · [docs/billion-scale.md](docs/billion-scale.md) · [docs/deployment-limits.md](docs/deployment-limits.md) |
+| Durability + snapshots | [docs/snapshot-safety.md](docs/snapshot-safety.md) |
+| Time travel | [ADR-003: semantic time travel](docs/ADR-003-semantic-time-travel.md) |
+| Upgrading from 2.x / brainy 7.x | [docs/migration-3.0.md](docs/migration-3.0.md) |
 
-## Learn More
+## The open-core promise
 
-- **[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
+Every accelerated path has a working JavaScript default in brainy (MIT). You upgrade for speed, not capability — and you can downgrade at any time with zero migration, because cor works on brainy's files, not its own. Your data is never hostage to a subscription.
 
 ---
 
-## 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.
+<p align="center">
+  <a href="https://soulcraft.com/docs">Documentation</a> ·
+  <a href="https://soulcraft.com/pricing?focus=cor">Pricing</a> ·
+  <a href="https://github.com/soulcraftlabs/brainy">Brainy (open source)</a> ·
+  <a href="https://soulcraft.com/support">Support</a>
+</p>

package/dist/cli.js

@@ -10,7 +10,7 @@
  */
 import { join } from 'node:path';
 import { readConfig, writeConfig, isShortCode, exchangeShortCode, readLicenseToken } from './license.js';
-import { SHORT_CODE_PATTERN, CONFIG_FILE } from './license/constants.js';
+import { SHORT_CODE_PATTERN, CONFIG_FILE, DEVICE_START_URL, DEVICE_TOKEN_URL } from './license/constants.js';
 const JWT_PREFIX = 'sc_cor_';
 // Legacy prefix still accepted during the cortex→cor rename transition.
 const LEGACY_JWT_PREFIX = 'sc_cortex_';
@@ -37,6 +37,83 @@ function resolveLicenseSource(config) {
         return { source: 'file', value: fileValue };
     return { source: 'none', value: undefined };
 }
+/**
+ * `cor login` — RFC 8628 device-authorization flow (the `gh auth login` UX):
+ * request a device code, show the user code + verification URL, poll until the
+ * browser approval lands, write the issued JWT to `.soulcraft.json`. The env
+ * var (`COR_LICENSE_KEY`) remains the CI/headless path; `activate <code>`
+ * remains the offline fallback.
+ */
+async function cmdLogin() {
+    let start;
+    try {
+        const res = await fetch(DEVICE_START_URL, { method: 'POST' });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        start = await res.json();
+    }
+    catch (error) {
+        console.error('[cor] Could not reach soulcraft.com to start login.');
+        console.error(`[cor] (${error instanceof Error ? error.message : String(error)})`);
+        console.error('[cor] Offline? Use: npx @soulcraft/cor activate <code-or-key>');
+        process.exit(1);
+    }
+    // RFC 8628 field names, tolerating camelCase servers.
+    const deviceCode = start.device_code ?? start.deviceCode;
+    const userCode = start.user_code ?? start.userCode;
+    const uri = start.verification_uri ?? start.verificationUri ?? 'https://soulcraft.com/activate';
+    let intervalS = Number(start.interval ?? 5) || 5;
+    const expiresIn = Number(start.expires_in ?? start.expiresIn ?? 900) || 900;
+    if (!deviceCode || !userCode) {
+        console.error('[cor] Login service returned an unexpected response. Try again, or use `activate <code>`.');
+        process.exit(1);
+    }
+    console.log('');
+    console.log(`  Open:  ${uri}`);
+    console.log(`  Code:  ${userCode}`);
+    console.log('');
+    console.log('  Waiting for approval in the browser…');
+    const deadline = Date.now() + expiresIn * 1000;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, intervalS * 1000));
+        let body;
+        try {
+            const res = await fetch(DEVICE_TOKEN_URL, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ device_code: deviceCode }),
+            });
+            body = await res.json().catch(() => ({}));
+            if (res.ok && (body.token ?? body.access_token)) {
+                const token = body.token ?? body.access_token;
+                const config = await readConfig();
+                delete config.cortex; // retire the legacy key on a fresh login
+                config.cor = token;
+                await writeConfig(config);
+                console.log(`  ✓ Logged in. License saved to ${CONFIG_FILE} — cor acceleration is active.`);
+                return;
+            }
+        }
+        catch {
+            continue; // transient network error — keep polling until the deadline
+        }
+        const err = body?.error;
+        if (err === 'authorization_pending')
+            continue;
+        if (err === 'slow_down') {
+            intervalS += 5;
+            continue;
+        }
+        if (err === 'expired_token')
+            break;
+        if (err === 'access_denied') {
+            console.error('  ✗ Login was denied in the browser.');
+            process.exit(1);
+        }
+    }
+    console.error('  ✗ Login timed out. Run `npx @soulcraft/cor login` again.');
+    process.exit(1);
+}
 function printHelp() {
     console.log(`
 cor — license management for @soulcraft/cor
@@ -45,6 +122,7 @@ USAGE
   npx @soulcraft/cor <command> [args]
 
 COMMANDS
+  login                    Sign in via the browser (device flow) — the easy path
   activate <code-or-key>   Activate with a short code (CO-XXXX-XXXX) or JWT
   status                   Show current license status
   deactivate               Remove the cor license key
@@ -213,6 +291,9 @@ async function cmdDeactivate() {
 }
 const [, , command, ...args] = process.argv;
 switch (command) {
+    case 'login':
+        await cmdLogin();
+        break;
     case 'activate':
         await cmdActivate(args[0]);
         break;

package/dist/license/constants.d.ts

@@ -13,6 +13,9 @@ export declare const ONLINE_VALIDATION_TIMEOUT_MS = 10000;
 export declare const API_URL = "https://soulcraft.com/api/license/validate";
 /** Short code exchange API URL */
 export declare const EXCHANGE_URL = "https://soulcraft.com/api/license/exchange";
+/** RFC 8628 device-authorization endpoints (`cor login`). */
+export declare const DEVICE_START_URL = "https://soulcraft.com/api/license/device/start";
+export declare const DEVICE_TOKEN_URL = "https://soulcraft.com/api/license/device/token";
 /** Pricing URL for license purchase */
 export declare const PRICING_URL = "https://soulcraft.com/pricing?focus=pro";
 /**

package/dist/license/constants.js

@@ -13,6 +13,9 @@ export const ONLINE_VALIDATION_TIMEOUT_MS = 10_000;
 export const API_URL = 'https://soulcraft.com/api/license/validate';
 /** Short code exchange API URL */
 export const EXCHANGE_URL = 'https://soulcraft.com/api/license/exchange';
+/** RFC 8628 device-authorization endpoints (`cor login`). */
+export const DEVICE_START_URL = 'https://soulcraft.com/api/license/device/start';
+export const DEVICE_TOKEN_URL = 'https://soulcraft.com/api/license/device/token';
 /** Pricing URL for license purchase */
 export const PRICING_URL = 'https://soulcraft.com/pricing?focus=pro';
 /**

package/dist/license/onlineValidator.d.ts

@@ -9,6 +9,16 @@
  * No signature verification here — that's in Rust.
  * Default 24h heartbeat interval, 14-day grace period.
  */
+export declare function setEntityCountSource(source: () => number | undefined): void;
+/** Coarse size bucket for metering — the pricing ladder's rungs. */
+export declare function entityBucketFor(count: number | undefined): string | undefined;
+/**
+ * Stable, non-identifying machine fingerprint: a truncated hash of
+ * hostname|platform|arch. Lets Portal count concurrent instances per key
+ * (the anti-sharing backstop — soft: an email, never a block) without
+ * transmitting the hostname itself.
+ */
+export declare function machineFingerprint(): string;
 interface HeartbeatCache {
     lastCheck: string;
     nextCheckAt?: string;

package/dist/license/onlineValidator.js

@@ -11,7 +11,46 @@
  */
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { hostname, platform, arch } from 'node:os';
 import { API_URL, CACHE_DIR, HEARTBEAT_FILE, GRACE_PERIOD_DAYS, DEFAULT_CHECK_INTERVAL_MS, ONLINE_VALIDATION_TIMEOUT_MS, } from './constants.js';
+/**
+ * Lazy source of the brain's indexed entity count, wired by the plugin
+ * (`setEntityCountSource`). The heartbeat reports only a coarse SIZE BUCKET —
+ * never data — per the licensing transparency contract ("once a day: key id,
+ * machine fingerprint, size bucket"). Undefined (unwired / probe failure)
+ * reports no bucket.
+ */
+let entityCountSource = null;
+export function setEntityCountSource(source) {
+    entityCountSource = source;
+}
+/** Coarse size bucket for metering — the pricing ladder's rungs. */
+export function entityBucketFor(count) {
+    if (count === undefined || !Number.isFinite(count) || count < 0)
+        return undefined;
+    if (count < 1_000_000)
+        return '<1M';
+    if (count < 10_000_000)
+        return '1M-10M';
+    if (count < 100_000_000)
+        return '10M-100M';
+    if (count < 1_000_000_000)
+        return '100M-1B';
+    return '1B+';
+}
+/**
+ * Stable, non-identifying machine fingerprint: a truncated hash of
+ * hostname|platform|arch. Lets Portal count concurrent instances per key
+ * (the anti-sharing backstop — soft: an email, never a block) without
+ * transmitting the hostname itself.
+ */
+export function machineFingerprint() {
+    return createHash('sha256')
+        .update(`${hostname()}|${platform()}|${arch()}`)
+        .digest('hex')
+        .slice(0, 16);
+}
 function getDefaultCacheDir() {
     return join(process.cwd(), CACHE_DIR);
 }
@@ -98,7 +137,12 @@ async function callApi(token) {
         const response = await fetch(API_URL, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ licenseKey: token }),
+            body: JSON.stringify({
+                licenseKey: token,
+                ver: 2,
+                sid: machineFingerprint(),
+                entityBucket: entityBucketFor(entityCountSource?.()),
+            }),
             signal: controller.signal,
         });
         if (!response.ok) {

package/dist/license/types.d.ts

@@ -4,7 +4,7 @@
 /** Result of license validation */
 export interface LicenseResult {
     valid: boolean;
-    tier: 'free' | 'pro' | 'enterprise' | 'internal';
+    tier: 'free' | 'startup' | 'pro' | 'growth' | 'scale' | 'enterprise' | 'internal';
     email: string;
     expiresAt: number;
     error?: string;

package/dist/license.d.ts

@@ -12,7 +12,7 @@
  */
 export interface LicenseResult {
     valid: boolean;
-    tier: 'free' | 'pro' | 'enterprise' | 'internal';
+    tier: 'free' | 'startup' | 'pro' | 'growth' | 'scale' | 'enterprise' | 'internal';
     email: string;
     expiresAt: number;
     error?: string;

package/dist/plugin.js

@@ -45,6 +45,8 @@
 import { loadNativeModule, isNativeAvailable } from './native/index.js';
 import { validateLicense, readLicenseToken, readConfig, isShortCode } from './license.js';
 import { MigrationCoordinator } from './migration/MigrationCoordinator.js';
+import { prodLog } from '@soulcraft/brainy/internals';
+import { setEntityCountSource } from './license/onlineValidator.js';
 const PRICING_URL = 'https://soulcraft.com/pricing?focus=pro';
 // `brainyRange` engages brainy 8.0's version-coupling gate (handoff LV.3): a
 // brainy outside this range fails loud at init() instead of silently dropping to
@@ -162,7 +164,10 @@ const corPlugin = {
             const { readHeartbeatCache, isGracePeriodExpired } = await import('./license/onlineValidator.js');
             const cachedState = await readHeartbeatCache();
             if (cachedState?.gracePeriodStart && isGracePeriodExpired(cachedState.gracePeriodStart)) {
-                console.warn('[cor] License lapsed. Compute acceleration disabled. Renew at soulcraft.com/account');
+                // LOUD (prodLog stays on even in silent mode): grace exhausted is the
+                // one licensing state an operator must notice — acceleration is now
+                // OFF and queries run at open-source speed until the key renews.
+                prodLog.error('[cor] License grace period EXPIRED — native acceleration disabled; running at open-source (brainy) speed. Renew at soulcraft.com/account');
                 return true;
             }
         }
@@ -354,6 +359,16 @@ const corPlugin = {
         // ResourceManager runs internally (adaptive cache sizing, wired above) — it is
         // not registered as a provider since brainy has no consumer for it.
         resourceManager.startRebalancing();
+        // Metering source for the heartbeat: the brain's indexed entity count
+        // (O(1) from the vector index), reported as a coarse size bucket only.
+        setEntityCountSource(() => {
+            try {
+                return vectorInstance?.size();
+            }
+            catch {
+                return undefined;
+            }
+        });
         // Background heartbeat with forceCheck — always checks Portal on startup.
         // Updates the cache so the next startup sees current subscription state.
         // Runs after providers are registered (non-blocking for the user).
@@ -366,7 +381,8 @@ const corPlugin = {
                     .then(result => {
                     if (result.degrade) {
                         const msg = result.warning ?? 'License lapsed. Compute acceleration disabled. Renew at soulcraft.com/account';
-                        console.warn(`[cor] ${msg}`);
+                        // Loud even in silent mode — see the grace-expiry note above.
+                        prodLog.error(`[cor] ${msg}`);
                     }
                     else if (result.warning) {
                         console.warn(`[cor] ${result.warning}`);

package/docs/scaling.md

@@ -36,6 +36,28 @@ Moving up a tier is `rsync` plus restart at the single-machine side, and adding
 a routing layer at the horizontal side. The Brainy API doesn't change — your
 code looks the same whether you're running one instance or 256.
 
+## Build time vs serve time — the number that matters is milliseconds
+
+A common first worry: "if a billion-vector index takes days to build, will my users wait days?"
+No user ever waits on a build. The two costs are completely different things:
+
+| | What it is | How long | Who experiences it |
+|---|---|---|---|
+| **Serving** | answering queries | **milliseconds** (measured: ~1 ms @ 10M, ~7 ms @ 100M) | your users, constantly |
+| **Inserting** | new data becoming searchable | **instant** (bounded buffer + O(new-data) segment flush) | your writers, constantly |
+| **Building** | constructing the optimized graph | minutes at 1M · ~hours at 100M · days at 1B | **nobody waits** — it runs in the background while serving continues |
+
+Why building is expensive: a query is *one* walk through the graph; building makes *every*
+vector do that walk to wire itself in — a billion queries' worth of work, performed once.
+This is the DiskANN design working as intended (build once, serve from disk forever), and
+the same physics applies to every vector database at this scale.
+
+Why nobody waits: brains grow incrementally — every insert is searchable in seconds via the
+segment tier, and the big consolidation runs off-thread with live progress while reads and
+writes flow uninterrupted. Even a one-time bulk migration of a pre-existing billion-vector
+corpus serves queries the whole time; only *peak* performance arrives when the background
+build completes.
+
 ## Single machine
 
 The default unit of deployment is **one Brainy instance** (the data layer —

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@soulcraft/cor",
-  "version": "3.0.0-rc.1",
-  "description": "Native Rust acceleration for Brainy — SIMD distance, vector quantization, zero-copy mmap, native embeddings. Free tier for storage, Pro license for compute acceleration.",
+  "version": "3.0.1",
+  "description": "Native Rust acceleration for Brainy \u2014 SIMD distance, vector quantization, zero-copy mmap, native embeddings. Free tier for storage, Pro license for compute acceleration.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -78,11 +78,11 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@soulcraft/brainy": ">=8.0.0-rc.1 <9.0.0"
+    "@soulcraft/brainy": ">=8.0.0 <9.0.0"
   },
   "devDependencies": {
     "@napi-rs/cli": "^3.0.0",
-    "@soulcraft/brainy": "8.0.0-rc.9",
+    "@soulcraft/brainy": "8.0.7",
     "@types/node": "^22.0.0",
     "pg": "^8.21.0",
     "tsx": "^4.21.0",