@soulcraft/cor 3.0.6 → 3.0.7

package/dist/graph/NativeGraphAdjacencyIndex.d.ts

@@ -72,6 +72,18 @@ export declare class GraphAdjacencyIndex implements GraphIndexProvider {
     private unifiedCache;
     private config;
     private initialized;
+    /**
+     * Canonical storage holds verbs but NO durable graph state exists — the
+     * 7.x → 3.0 migration / restore-dir shape. Detected once per cold open in
+     * {@link ensureInitialized} by a bounded O(1) canonical probe; suppresses
+     * the edgeless-graph ready verdict in {@link isReady} so brainy's cold-open
+     * gate runs the one rebuild that reconstructs the adjacency (without this, a
+     * migrated brain served empty neighbors()/related() with no error — the
+     * graph twin of the vector leg's silent-empty migration bug). Cleared by a
+     * completed {@link rebuild}, whose durable output also makes later boots
+     * skip the probe.
+     */
+    private canonicalUnindexed;
     private isRebuilding;
     private flushTimer?;
     private rebuildStartTime;
@@ -129,6 +141,19 @@ export declare class GraphAdjacencyIndex implements GraphIndexProvider {
      * graph on first touch.
      */
     private ensureInitialized;
+    /**
+     * Detect the canonical-but-unindexed cold-open shape: storage holds verbs
+     * while NO durable graph state loaded (edges-ready latch unset, zero
+     * resident relationships) — a 7.x → 3.0 migration dir or a restore that
+     * never built the graph LSM. The edgeless-ready rule (BR-8-BOOT-INDEX) is
+     * correct only when there are genuinely no relationships anywhere; here a
+     * rebuild is NOT redundant, and reporting ready serves empty adjacency.
+     * Bounded O(1): one single-verb canonical page, only on the nothing-durable
+     * path — after the gate-triggered rebuild persists the trees, later boots
+     * latch edges-ready and never reach the probe. Truly edgeless brains (no
+     * canonical verbs) stay ready, so the boot-rebuild/502 class stays dead.
+     */
+    private probeCanonicalCoverage;
     /**
      * Cold-load the four u64 LSM trees from persistence: load each tree's
      * manifest and register every persisted SSTable (mmap tier, then binary

package/dist/graph/NativeGraphAdjacencyIndex.js

@@ -76,6 +76,18 @@ export class GraphAdjacencyIndex {
     unifiedCache;
     config;
     initialized = false;
+    /**
+     * Canonical storage holds verbs but NO durable graph state exists — the
+     * 7.x → 3.0 migration / restore-dir shape. Detected once per cold open in
+     * {@link ensureInitialized} by a bounded O(1) canonical probe; suppresses
+     * the edgeless-graph ready verdict in {@link isReady} so brainy's cold-open
+     * gate runs the one rebuild that reconstructs the adjacency (without this, a
+     * migrated brain served empty neighbors()/related() with no error — the
+     * graph twin of the vector leg's silent-empty migration bug). Cleared by a
+     * completed {@link rebuild}, whose durable output also makes later boots
+     * skip the probe.
+     */
+    canonicalUnindexed = false;
     isRebuilding = false;
     flushTimer;
     rebuildStartTime = 0;
@@ -218,9 +230,41 @@ export class GraphAdjacencyIndex {
             return;
         }
         await this.openGraphLsmEngine();
+        await this.probeCanonicalCoverage();
         this.startAutoFlush();
         this.initialized = true;
     }
+    /**
+     * Detect the canonical-but-unindexed cold-open shape: storage holds verbs
+     * while NO durable graph state loaded (edges-ready latch unset, zero
+     * resident relationships) — a 7.x → 3.0 migration dir or a restore that
+     * never built the graph LSM. The edgeless-ready rule (BR-8-BOOT-INDEX) is
+     * correct only when there are genuinely no relationships anywhere; here a
+     * rebuild is NOT redundant, and reporting ready serves empty adjacency.
+     * Bounded O(1): one single-verb canonical page, only on the nothing-durable
+     * path — after the gate-triggered rebuild persists the trees, later boots
+     * latch edges-ready and never reach the probe. Truly edgeless brains (no
+     * canonical verbs) stay ready, so the boot-rebuild/502 class stays dead.
+     */
+    async probeCanonicalCoverage() {
+        if (this.native.isReady() || this.native.size() > 0)
+            return;
+        if (typeof this.storage?.getVerbs !== 'function')
+            return;
+        try {
+            const page = await this.storage.getVerbs({ pagination: { limit: 1 } });
+            if ((page?.items ?? []).length > 0) {
+                this.canonicalUnindexed = true;
+                prodLog.warn('GraphAdjacencyIndex: canonical storage holds verbs but no durable ' +
+                    'graph state exists (migration/restore dir) — reporting not-ready ' +
+                    'so the cold-open gate rebuilds the adjacency once from canonical');
+            }
+        }
+        catch {
+            // Probe is advisory: an unreadable canonical page must not block open.
+            // Worst case we report ready and behave as before the probe existed.
+        }
+    }
     /**
      * Cold-load the four u64 LSM trees from persistence: load each tree's
      * manifest and register every persisted SSTable (mmap tier, then binary
@@ -518,6 +562,10 @@ export class GraphAdjacencyIndex {
             return true;
         if (!this.initialized)
             return false;
+        // Canonical verbs exist with no durable graph state (migration/restore
+        // dir): a rebuild is NOT redundant — see {@link probeCanonicalCoverage}.
+        if (this.canonicalUnindexed)
+            return false;
         // Cold-load has run but the edges-ready latch is unset. Ready ⇔ there is
         // nothing durable to load: no SSTables and empty memtables on either the
         // source or target tree. If any durable edges exist but didn't load, this
@@ -667,6 +715,9 @@ export class GraphAdjacencyIndex {
             }
             const rebuildTime = Date.now() - this.rebuildStartTime;
             const memoryUsage = this.calculateMemoryUsage();
+            // The rebuild reconstructed the adjacency from canonical — the cold-open
+            // not-ready verdict (migration/restore dir) is satisfied.
+            this.canonicalUnindexed = false;
             prodLog.info(`GraphAdjacencyIndex: Rebuild complete in ${rebuildTime}ms`);
             prodLog.info(`  - Total verbs tracked: ${totalVerbs.toLocaleString()}`);
             if (reconstructAdjacency) {

package/dist/hnsw/NativeDiskAnnWrapper.d.ts

@@ -209,6 +209,17 @@ export declare class NativeDiskAnnWrapper implements VectorIndexProvider {
     private manifestNextId;
     /** Segment-manifest cold-load memo (see {@link ensureSegments}). */
     private segmentsLoaded;
+    /**
+     * Canonical storage holds vectored nouns but NO durable vector index exists —
+     * the 7.x → 3.0 migration / restore-dir shape. Detected once per cold open by
+     * {@link probeCanonicalCoverage}; makes {@link isReady} report `false` so
+     * brainy's cold-open gate runs the one rebuild that indexes the canonical
+     * vectors (without this, a migrated brain served silent-empty vector search —
+     * the gate-305/306 `indexEpochMigration` failure). Cleared by a completed
+     * {@link runRebuild}, whose durable output also makes every later boot skip
+     * the probe entirely.
+     */
+    private canonicalUnindexed;
     private segmentsLoading;
     /**
      * True when a durable base index was present on disk but failed to load
@@ -289,6 +300,14 @@ export declare class NativeDiskAnnWrapper implements VectorIndexProvider {
      * it loaded so an operator can see the reconstruction happen.
      *
      * @param dim - Index dimension; nouns whose vector width differs are skipped.
+     *   Optional: when absent (a zero-config brain with no base index or L0
+     *   segment to read it from), the width is adopted from the first canonical
+     *   vector — every vector in a brain shares one dim (brainy enforces the
+     *   embedder's). Passing `undefined` previously skipped EVERY vector
+     *   (`length !== undefined` is always true), silently rebuilding an empty
+     *   index on a zero-config restore.
+     * @returns The dimension actually used — the passed `dim`, or the width
+     *   adopted from canonical data, or `undefined` if nothing was read.
      */
     private hydrateDeltaFromStorage;
     search(queryVector: Vector, k?: number, filter?: (id: string) => Promise<boolean>, options?: {
@@ -432,8 +451,24 @@ export declare class NativeDiskAnnWrapper implements VectorIndexProvider {
      * still gets the segments lazily; only the pre-gate timing needs init().)
      */
     init(): Promise<void>;
-    /** Memoized segment-manifest cold-load. */
+    /** Memoized segment-manifest cold-load (+ canonical-coverage probe). */
     private ensureSegments;
+    /**
+     * Detect the canonical-but-unindexed cold-open shape: storage holds vectored
+     * nouns while NO durable vector artifact exists (no base index, no L0
+     * segment, empty delta) — a 7.x → 3.0 migration dir or a restore that never
+     * built the index. The readiness contract's "fresh brain is ready" rule is
+     * correct only when there is genuinely nothing to index; here a rebuild is
+     * NOT redundant, and reporting ready serves silent-empty vector search.
+     *
+     * Bounded O(32), never an O(N) walk (the 48s-per-boot mandate): one small
+     * canonical page, checked for any vectored noun. Runs only when the brain
+     * has zero durable vector state — after the gate-triggered rebuild persists
+     * its output, every later boot sees the durable base and skips the probe.
+     * Metadata-only brains (no vectors in the probe page) stay ready, so the
+     * boot-rebuild class this contract was built to kill stays dead.
+     */
+    private probeCanonicalCoverage;
     /**
      * Read `__vector_index_manifest__` and open every live L0 segment. A missing
      * manifest is the legacy single-index layout (the base at `indexPath` IS the

package/dist/hnsw/NativeDiskAnnWrapper.js

@@ -311,6 +311,17 @@ export class NativeDiskAnnWrapper {
     manifestNextId = 1;
     /** Segment-manifest cold-load memo (see {@link ensureSegments}). */
     segmentsLoaded = false;
+    /**
+     * Canonical storage holds vectored nouns but NO durable vector index exists —
+     * the 7.x → 3.0 migration / restore-dir shape. Detected once per cold open by
+     * {@link probeCanonicalCoverage}; makes {@link isReady} report `false` so
+     * brainy's cold-open gate runs the one rebuild that indexes the canonical
+     * vectors (without this, a migrated brain served silent-empty vector search —
+     * the gate-305/306 `indexEpochMigration` failure). Cleared by a completed
+     * {@link runRebuild}, whose durable output also makes every later boot skip
+     * the probe entirely.
+     */
+    canonicalUnindexed = false;
     segmentsLoading = null;
     /**
      * True when a durable base index was present on disk but failed to load
@@ -398,7 +409,12 @@ export class NativeDiskAnnWrapper {
      * `rebuild()` call, which folds the delta into the main index.
      */
     async addItem(item) {
-        const bytesPerVector = this.config.dimensions * 4;
+        // item.vector.length is the authoritative width for THIS write; fall back to
+        // it when the brain is zero-config (config.dimensions undefined). Otherwise
+        // bytesPerVector is NaN and every `NaN >= cap` backpressure/fold check is
+        // false — the delta grows unbounded and never folds (MEMORY-COR-RANGE-ERROR
+        // family: the same undefined-dim that broke consolidation).
+        const bytesPerVector = (this.config.dimensions ?? item.vector.length) * 4;
         // HARD cap — backpressure: the delta may not grow unbounded. Wait for
         // the in-flight fold (or start one) before accepting the write. Serving
         // is unaffected — the fold runs off the JS thread and reads keep
@@ -409,7 +425,19 @@ export class NativeDiskAnnWrapper {
             // safe (the rebuild folds only its snapshot; the new segment survives
             // its retirement filter and the serialized manifest saves keep the
             // on-disk list consistent).
-            await (this.flushInFlight ?? this.flushDeltaToL0());
+            //
+            // A committed write must NEVER fail on post-commit index maintenance — the
+            // caller would retry and double-write (MEMORY-COR-RANGE-ERROR isolation
+            // ask). A backpressure-flush failure is a loud alarm, not a rejected
+            // write: log it, keep the delta for the next trigger, accept the write.
+            try {
+                await (this.flushInFlight ?? this.flushDeltaToL0());
+            }
+            catch (error) {
+                prodLog.error(`NativeDiskAnnWrapper: backpressure flush failed (write accepted; ` +
+                    `delta retained for retry): ` +
+                    `${error instanceof Error ? error.message : String(error)}`);
+            }
         }
         if (this.tombstones.has(item.id)) {
             this.tombstones.delete(item.id);
@@ -475,6 +503,14 @@ export class NativeDiskAnnWrapper {
      * it loaded so an operator can see the reconstruction happen.
      *
      * @param dim - Index dimension; nouns whose vector width differs are skipped.
+     *   Optional: when absent (a zero-config brain with no base index or L0
+     *   segment to read it from), the width is adopted from the first canonical
+     *   vector — every vector in a brain shares one dim (brainy enforces the
+     *   embedder's). Passing `undefined` previously skipped EVERY vector
+     *   (`length !== undefined` is always true), silently rebuilding an empty
+     *   index on a zero-config restore.
+     * @returns The dimension actually used — the passed `dim`, or the width
+     *   adopted from canonical data, or `undefined` if nothing was read.
      */
     async hydrateDeltaFromStorage(dim) {
         // Best-effort: only when the storage adapter supports bulk noun reads
@@ -482,7 +518,8 @@ export class NativeDiskAnnWrapper {
         // 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')
-            return;
+            return dim;
+        let resolved = dim;
         let cursor = undefined;
         let hasMore = true;
         let loaded = 0;
@@ -498,7 +535,13 @@ export class NativeDiskAnnWrapper {
                 if (this.tombstones.has(noun.id))
                     continue;
                 const vector = noun.vector;
-                if (!vector || vector.length !== dim)
+                if (!vector)
+                    continue;
+                // Adopt the width from the first canonical vector when the caller
+                // couldn't supply it; thereafter enforce it (one dim per brain).
+                if (resolved === undefined)
+                    resolved = vector.length;
+                if (vector.length !== resolved)
                     continue;
                 this.delta.set(noun.id, vector);
                 loaded++;
@@ -510,6 +553,7 @@ export class NativeDiskAnnWrapper {
             prodLog?.info?.(`NativeDiskAnnWrapper: cold rebuild hydrated ${loaded} vectors from ` +
                 `canonical storage (#44 migration/restore path)`);
         }
+        return resolved;
     }
     async search(queryVector, k = 10, filter, options) {
         // Predicate pushdown: a SELECTIVE metadata∩graph universe is evaluated
@@ -743,6 +787,10 @@ export class NativeDiskAnnWrapper {
     isReady() {
         if (this.durableBaseLoadFailed)
             return false;
+        // Canonical vectors exist with no durable index (migration/restore dir):
+        // a rebuild is NOT redundant — see {@link probeCanonicalCoverage}.
+        if (this.canonicalUnindexed)
+            return false;
         // init() (or any prior async op) has attached the segment set. Before that,
         // report not-ready so the gate never skips over an unloaded index; brainy's
         // contract calls isReady() only after init(), where this is true.
@@ -978,15 +1026,36 @@ export class NativeDiskAnnWrapper {
         // (non-empty `liveOldSlots`) both skip it, so the hot paths pay
         // nothing. `hydrateDeltaFromStorage` only adds ids absent from the
         // delta, so any straggler already fed by restore is preserved.
+        // Resolve the vector dimension robustly — the SAME fallback flushDeltaToL0
+        // uses. brainy's zero-config vector factory does not always pass
+        // config.dimensions; consolidation must still resolve the width from an
+        // authoritative source, or it throws "≠ index dim undefined" and corrupts
+        // the fold buffers with a NaN stride on every zero-config consolidation
+        // (MEMORY-COR-RANGE-ERROR — the flush path was fixed for this, rebuild was
+        // not). Priority: declared config → attached base index header → any live
+        // L0 segment header → (below) cold-hydrated canonical data → the delta's
+        // own vectors.
+        let dim = this.config.dimensions ??
+            (this.native ? this.native.header().dim : undefined) ??
+            builtL0.find((s) => s.nodeCount > 0)?.native.header().dim;
         if (liveOldSlots.length === 0 && typeof this.storage?.getNouns === 'function') {
             const probe = await this.storage.getNouns({ pagination: { limit: 1 } });
             if (probe.totalCount === undefined || probe.totalCount > this.delta.size) {
-                await this.hydrateDeltaFromStorage(this.config.dimensions);
+                // Cold/restore rebuild: hydrate also adopts the dim from canonical data
+                // when we still don't have it, and returns the width it used.
+                dim = await this.hydrateDeltaFromStorage(dim);
             }
         }
         // Delta snapshot AFTER the cold-hydrate (which populates this.delta).
         const builtDelta = new Map(this.delta);
-        const dim = this.config.dimensions;
+        // Final fallback: the delta's own vectors (an addItem-only zero-config brain
+        // with no base index yet), mirroring flushDeltaToL0.
+        dim ??= builtDelta.values().next().value?.length;
+        if (dim === undefined) {
+            // Nothing to fold and no source to learn the width from → empty rebuild.
+            prodLog?.warn?.('NativeDiskAnnWrapper.rebuild: nothing to build (no vectors, no resolvable dimension)');
+            return;
+        }
         const deltaCount = builtDelta.size;
         let deltaBuf = null;
         const deltaInts = [];
@@ -1027,6 +1096,9 @@ export class NativeDiskAnnWrapper {
         }
         if (liveOldSlots.length + deltaCount + l0Entries.length === 0) {
             prodLog?.warn?.('NativeDiskAnnWrapper.rebuild: nothing to build');
+            // The rebuild ran over canonical and found nothing to index — its verdict
+            // supersedes the cold-open probe's; never leave the gate looping.
+            this.canonicalUnindexed = false;
             return;
         }
         const totalCount = liveOldSlots.length + deltaCount + l0Entries.length;
@@ -1123,6 +1195,9 @@ export class NativeDiskAnnWrapper {
                 }
             }
         }
+        // The rebuild's durable output now covers canonical — the cold-open
+        // not-ready verdict (migration/restore dir) is satisfied.
+        this.canonicalUnindexed = false;
     }
     /**
      * Flush the delta buffer to disk. For DiskANN the delta is in-memory
@@ -1191,18 +1266,58 @@ export class NativeDiskAnnWrapper {
     async init() {
         await this.ensureSegments();
     }
-    /** Memoized segment-manifest cold-load. */
+    /** Memoized segment-manifest cold-load (+ canonical-coverage probe). */
     async ensureSegments() {
         if (this.segmentsLoaded)
             return;
         if (this.segmentsLoading)
             return this.segmentsLoading;
-        this.segmentsLoading = this.loadSegmentManifest().finally(() => {
+        this.segmentsLoading = this.loadSegmentManifest()
+            .then(() => this.probeCanonicalCoverage())
+            .finally(() => {
             this.segmentsLoaded = true;
             this.segmentsLoading = null;
         });
         return this.segmentsLoading;
     }
+    /**
+     * Detect the canonical-but-unindexed cold-open shape: storage holds vectored
+     * nouns while NO durable vector artifact exists (no base index, no L0
+     * segment, empty delta) — a 7.x → 3.0 migration dir or a restore that never
+     * built the index. The readiness contract's "fresh brain is ready" rule is
+     * correct only when there is genuinely nothing to index; here a rebuild is
+     * NOT redundant, and reporting ready serves silent-empty vector search.
+     *
+     * Bounded O(32), never an O(N) walk (the 48s-per-boot mandate): one small
+     * canonical page, checked for any vectored noun. Runs only when the brain
+     * has zero durable vector state — after the gate-triggered rebuild persists
+     * its output, every later boot sees the durable base and skips the probe.
+     * Metadata-only brains (no vectors in the probe page) stay ready, so the
+     * boot-rebuild class this contract was built to kill stays dead.
+     */
+    async probeCanonicalCoverage() {
+        if (this.native || this.l0Segments.length > 0 || this.delta.size > 0)
+            return;
+        if (this.durableBaseLoadFailed)
+            return; // already not-ready, loudly
+        const storage = this.storage;
+        if (!storage || typeof storage.getNouns !== 'function')
+            return;
+        try {
+            const page = await storage.getNouns({ pagination: { limit: 32 } });
+            const vectored = (page?.items ?? []).some((n) => Array.isArray(n.vector) && n.vector.length > 0);
+            if (vectored) {
+                this.canonicalUnindexed = true;
+                prodLog?.warn?.('NativeDiskAnnWrapper: canonical storage holds vectors but no durable ' +
+                    'vector index exists (migration/restore dir) — reporting not-ready so ' +
+                    'the cold-open gate rebuilds once from canonical');
+            }
+        }
+        catch {
+            // Probe is advisory: an unreadable canonical page must not block open.
+            // Worst case we report ready and behave as before the probe existed.
+        }
+    }
     /**
      * Read `__vector_index_manifest__` and open every live L0 segment. A missing
      * manifest is the legacy single-index layout (the base at `indexPath` IS the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@soulcraft/cor",
-  "version": "3.0.6",
-  "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.",
+  "version": "3.0.7",
+  "description": "Native Rust acceleration for Brainy — 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",