@soulcraft/cor 3.0.2 → 3.0.4

package/dist/hnsw/NativeDiskAnnWrapper.js

@@ -470,7 +470,7 @@ export class NativeDiskAnnWrapper {
      */
     async hydrateDeltaFromStorage(dim) {
         // Best-effort: only when the storage adapter supports bulk noun reads
-        // (production FileSystemStorage/MmapFileSystemStorage do; some partial
+        // (production brainy FileSystemStorage does; some partial
         // adapters used in direct-construction tests do not). When absent, the
         // caller falls back to the in-memory rebuild.
         if (typeof this.storage?.getNouns !== 'function')

package/dist/utils/NativeColumnStore.d.ts

@@ -35,7 +35,8 @@ import type { ColumnStoreProvider, EntityIdMapperLike } from './columnStoreTypes
 import { ValueType } from './columnStoreTypes.js';
 import { RoaringBitmap32 } from '../native/NativeRoaringBitmap32.js';
 /**
- * @description The subset of cor's `MmapFileSystemStorage` that the column
+ * @description The subset of brainy's `FileSystemStorage` (whose index files cor
+ * memory-maps) that the column
  * store needs for billion-scale raw segment persistence. cor builds against
  * published `@soulcraft/brainy`, whose `StorageAdapter` type does not yet
  * declare these binary-blob methods, so we narrow the adapter to this local

package/dist/utils/NativeColumnStore.js

@@ -130,7 +130,7 @@ export class NativeColumnStore {
         if (!isBinaryBlobStorage(storage)) {
             throw new Error('NativeColumnStore requires a storage adapter with binary-blob support ' +
                 '(saveBinaryBlob/loadBinaryBlob/deleteBinaryBlob/getBinaryBlobPath). ' +
-                'Use cor MmapFileSystemStorage or another adapter implementing BinaryBlobStorage.');
+                'Use brainy FileSystemStorage or another adapter implementing BinaryBlobStorage.');
         }
         this.storage = storage;
         // Discover fields by listing manifest files under the column-index prefix.

package/dist/utils/NativeMetadataIndex.js

@@ -405,13 +405,31 @@ export class MetadataIndexManager {
         // Resolve the metadata directory for the persistent engine, mirroring
         // wireIdMapper's filesystem guard. `getBinaryBlobPath` returns null on
         // non-local adapters → fall back to the in-RAM engine.
-        const metaDir = typeof blobStorage.getBinaryBlobPath === 'function'
-            ? blobStorage.getBinaryBlobPath('_metadata')
-            : null;
+        const getBlobPath = blobStorage.getBinaryBlobPath;
+        const hasBlobPath = typeof getBlobPath === 'function';
+        const metaDir = hasBlobPath ? getBlobPath.call(blobStorage, '_metadata') : null;
         if (metaDir === null) {
             // Fallback: non-persistent in-RAM engine (the legacy `new` path).
             // U64 IdSpace matches the cor 3.0 production default + the metadata
             // index core constructed above.
+            //
+            // Two very different situations land here — do NOT let the durable one
+            // pass silently (the invisible-degrade the whole GA bar forbids):
+            //   - method ABSENT  → a genuinely non-local adapter (cloud/in-memory);
+            //     an in-RAM metadata engine is correct. Quiet.
+            //   - method PRESENT but returned null for '_metadata' → a filesystem-
+            //     class adapter that should have yielded a path but didn't. The
+            //     metadata index will run WITHOUT on-disk durability — every restart
+            //     rebuilds from canonical (the 48s-per-boot class). Announce it LOUD
+            //     so an operator sees it instead of silently paying the cost forever.
+            if (hasBlobPath) {
+                prodLog.error('[NativeMetadataIndex] getBinaryBlobPath("_metadata") returned null on ' +
+                    'an adapter that implements it — the metadata LSM is running IN-RAM, ' +
+                    'NOT persisted. Every restart will rebuild the index from canonical ' +
+                    '(slow cold opens). This is a durability misconfiguration, not normal ' +
+                    'operation — check the storage adapter/path. Reachable durable state is ' +
+                    'the "restart = warm" contract.');
+            }
             this.lsmEngine = new bindings.NativeLsmEngine({ idSpace: 'u64' });
             this.lsmManifest = null;
             this.lsmMetaDir = null;
@@ -1040,6 +1058,30 @@ export class MetadataIndexManager {
                             'NO rebuild.');
                         return;
                     }
+                    // **Tripwire — a rebuild here on a PREVIOUSLY-HEALTHY brain is a bug,
+                    // not routine.** A rebuild is legitimate exactly twice: a fresh brain
+                    // (no marker) and a 7.x→8.0 upgrade (stale marker) — both have no
+                    // durable derived state yet. But if the on-disk brain-format marker is
+                    // present AND current, an 8.x/3.x already fully built and STAMPED this
+                    // brain's indexes; their absence now means the field registry + LSM
+                    // both failed to persist/reload (the "restart = milliseconds" contract
+                    // broken — every boot pays an O(N) rebuild). That must never be
+                    // silent: surface it at ERROR with the entity count so it's caught the
+                    // first time, not after a customer measures a 48s boot.
+                    try {
+                        const marker = await readOnDiskBrainFormat(this.storage);
+                        if (!isEpochStale(marker)) {
+                            prodLog.error(`[NativeMetadataIndex] DURABILITY TRIPWIRE: rebuilding ${probe.totalCount ?? 'unknown'} ` +
+                                'entities on a brain whose format marker is present + current — the ' +
+                                'derived indexes (field registry AND LSM) should already be on disk. ' +
+                                'This is an unexpected full rebuild on a previously-healthy brain ' +
+                                '(the every-boot-rebuild class); please report it with the brain layout. ' +
+                                'Data is safe (canonical entities intact); only startup time is affected.');
+                        }
+                    }
+                    catch {
+                        // marker read failed — fall through to the normal rebuild path
+                    }
                     console.warn(`[NativeMetadataIndex] Field registry missing but ${probe.totalCount ?? 'unknown'} entities exist — rebuilding index`);
                     await this.rebuild();
                     return;

package/docs/ADR-003-semantic-time-travel.md

@@ -80,7 +80,7 @@ This means semantic time travel is a **brainy feature** that cor accelerates —
 **Guarantee (verified, 8.0.0-rc.2 + cor 3.0):** `db.asOf(g).find({ vector, where })` is set-correct, rank-correct (at-g embedding), and filter-correct (at-g metadata) — **for mutations committed via `brain.transact([...])`**.
 
 **Limits — all four are real; do not claim past them:**
-1. **`transact()`-only in the shipped brainy rc.2.** Single-op `brain.add()`/`brain.remove()` writes bump the generation counter but do **not** retain a before-image or register the generation (`generationStore.js:178 noteSingleOpWrite`), so `asOf(g)` silently resolves to **current** state for them. Time-travel-correct history requires `transact()`. Brainy's rc.3 Model-B is slated to retain single-op writes; the guard test (`semanticAsOf.test.ts`) flips red when it lands. (Handoff: IMMUTABILITY-TIMETRAVEL thread.)
+1. ~~**`transact()`-only.**~~ **RESOLVED before GA** — brainy's Model-B landed in 8.0.0-rc.3 (`5c3bb2c`): single-op `add()`/`remove()` writes ARE retained (per-write `persistSingleOp`/`commitSingleOp` generation-stamping), so `asOf(g)` is history-correct for BOTH `transact([...])` and single-op mutations. Regression-pinned in `src/native/semanticAsOf.test.ts` (runs green in the release gate vs the published 8.0.11). The rc.2-era gap this bullet used to describe no longer exists in any shipped 8.x.
 2. **The historical leg is brainy-JS-served this release.** `asOf(g)` builds an ephemeral reader brain and rebuilds a JS HNSW from the at-g vectors; cor's native vector index (`NativeDiskAnnWrapper`) is **not** on the historical path. cor accelerates only the live (`now`) leg in 3.0. (Open-core: brainy-alone is correct via JS rerank.)
 3. **O(n-at-g) rebuild per `asOf` Db — small/medium scale only.** One `addItem` per at-g vector into a fresh JS HNSW; this OOMs at billion-scale. Billion-scale historical semantic find is **Phase 1–2** (cor native rerank / overlay / tiered ANN; #35). Phase 0 is correctness, not scale.
 4. **No embedding-model-drift guard yet.** Comparing a query embedded with model vN against stored vectors from model vM is silently wrong across a model upgrade — detection lands in Phase 1, alignment in Phase 3.

package/docs/migration-3.0.md

@@ -355,7 +355,7 @@ Memory is the canonical first 3.0 consumer (production on Brainy 7.31.6 + Cortex
 
 **Memory-specific gotchas:**
 
-- **`mmap-filesystem` storage adapter** is filesystem-backed via Brainy's `MmapFileSystemStorage` — cor 3.0's DiskANN auto-engagement WILL fire here, which is what you want.
+- **Storage** is Brainy's standard `filesystem` adapter (there is no separate "mmap" storage class to configure — cor memory-maps its own index files under whatever filesystem path you give Brainy). cor 3.0's DiskANN auto-engagement WILL fire here, which is what you want.
 - **Per-user brain cold start** was 8.3 s on Brainy 7.31.3 + Cortex 2.7.0 (per the BRAINY-COR-MMAP-VECTOR-NOT-WIRED thread). On 8.0 + 3.0 with DiskANN + the cor shadow-page LSM, cold start should drop substantially — Adaptive DiskANN auto-selects `in-memory` mode at the per-user scale (each user is currently ≤ 1 K memories), giving sub-millisecond reads with no warm-up. Re-measure after upgrade and update the production-impact section of that thread.
 - **`db.asOf(g)` / `db.with(...)`** time-travel reads are now available — if Memory wants to surface "what did this user remember last week", that's a feature you can build on top of brainy 8.0's historical query surface without any cor-side work.
 - **No external Memory user has 1 M+ memories yet**, so the migration window is operationally cheap; do it during the morning low-traffic window per current ops practice.

package/docs/scaling.md

@@ -104,9 +104,11 @@ are evicted before small active ones).
 
 ### Memory-mapped storage
 
-Cor's `MmapFileSystemStorage` extends Brainy's filesystem storage with
-zero-copy binary I/O. The Rust native layer memory-maps data files via
-`memmap2`, letting the Linux kernel manage which pages stay in RAM.
+You use Brainy's standard `filesystem` storage — there is no separate
+storage class to choose. Cor's native engines memory-map their own index
+files (vectors, graph adjacency, metadata LSM) via `memmap2`, letting the
+Linux kernel manage which pages stay in RAM. Zero-copy binary I/O comes
+from the native layer, not from a special adapter.
 
 What mmap provides:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/cor",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "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",