@soulcraft/cor 3.0.4 → 3.0.5

package/dist/hnsw/NativeDiskAnnWrapper.d.ts

@@ -210,6 +210,14 @@ export declare class NativeDiskAnnWrapper implements VectorIndexProvider {
     /** Segment-manifest cold-load memo (see {@link ensureSegments}). */
     private segmentsLoaded;
     private segmentsLoading;
+    /**
+     * True when a durable base index was present on disk but failed to load
+     * (corrupt file, or a missing slotmap sidecar). Distinct from a fresh brain
+     * (no file at all): drives {@link isReady} to report NOT-ready so brainy's
+     * cold-open gate recovers via `rebuild()` instead of skipping an unusable
+     * index. Set in {@link tryOpenExisting}; cleared by a successful rebuild.
+     */
+    private durableBaseLoadFailed;
     /** Serializes manifest writes: the storage adapter has no per-key write
      * ordering, so two in-flight saves (a flush racing a consolidation) could
      * physically land out of order and persist a STALE segment list — losing a
@@ -325,6 +333,24 @@ export declare class NativeDiskAnnWrapper implements VectorIndexProvider {
      * @returns `true` when the brain must not be read from or written to.
      */
     isMigrating(): boolean;
+    /**
+     * @description **Readiness contract (brainy ≥ 8.0.12).** Honest durability
+     * signal for brainy's per-leg cold-open rebuild gate: `true` ⇔ the persisted
+     * index is loaded (or there is none to load) and a rebuild from canonical
+     * would be redundant. Brainy defers to this INSTEAD of the `size()===0`
+     * heuristic — a disk-native index legitimately reports zero resident nodes
+     * while fully durable, which is exactly why `size()` is the wrong gate.
+     *
+     * Returns `false` only when a durable base index was present but FAILED to
+     * load ({@link durableBaseLoadFailed}) — never claim ready over a failed load,
+     * or the gate would serve silent-empty results instead of recovering via
+     * `rebuild()`. A fresh brain (no durable index) is ready: loading nothing
+     * succeeds and a rebuild is a no-op. Partially-skipped L0 segments do NOT make
+     * it not-ready — their entries remain in canonical and heal via consolidation
+     * (see {@link loadSegmentManifest}).
+     * @returns `true` when a cold-open rebuild would be redundant.
+     */
+    isReady(): boolean;
     /**
      * @description **#18 migration lock — structured progress** Brainy relays into
      * `getIndexStatus().migration`. `null` unless a migration is in flight.
@@ -392,10 +418,18 @@ export declare class NativeDiskAnnWrapper implements VectorIndexProvider {
     /** Membership across the base + every L0 segment (int → any slot). */
     private hasIntAnywhere;
     /**
-     * @description Provider init — brainy feature-detects and awaits it. Cold-loads
-     * the segment manifest so a reopened brain serves its L0 segments from the
-     * first query (the wrapper's own async paths also call {@link ensureSegments},
-     * so a caller that skips init() still gets the segments lazily).
+     * @description **Readiness contract (brainy ≥ 8.0.12).** Provider init — brainy
+     * feature-detects and awaits it once during brain open, after the metadata
+     * provider's `init()` (id-mapper hydrated) and BEFORE its cold-open rebuild
+     * gate. The base index is mmap-attached in the constructor ({@link
+     * tryOpenExisting}); this eager cold-load attaches the L0 **segment** set too,
+     * so `size()`/{@link isReady} reflect the FULL persisted index at the gate
+     * rather than the base alone. Without it the async segment cold-load defers
+     * past the gate, `size()` reads low/zero, and brainy rebuilds from canonical on
+     * every open (the 48s-per-boot class). An mmap attach — O(pages touched), never
+     * an O(N) rebuild — so it stays cheap at billion scale. (The wrapper's own
+     * async paths also call {@link ensureSegments}, so a caller that skips init()
+     * still gets the segments lazily; only the pre-gate timing needs init().)
      */
     init(): Promise<void>;
     /** Memoized segment-manifest cold-load. */

package/dist/hnsw/NativeDiskAnnWrapper.js

@@ -312,6 +312,14 @@ export class NativeDiskAnnWrapper {
     /** Segment-manifest cold-load memo (see {@link ensureSegments}). */
     segmentsLoaded = false;
     segmentsLoading = null;
+    /**
+     * True when a durable base index was present on disk but failed to load
+     * (corrupt file, or a missing slotmap sidecar). Distinct from a fresh brain
+     * (no file at all): drives {@link isReady} to report NOT-ready so brainy's
+     * cold-open gate recovers via `rebuild()` instead of skipping an unusable
+     * index. Set in {@link tryOpenExisting}; cleared by a successful rebuild.
+     */
+    durableBaseLoadFailed = false;
     /** Serializes manifest writes: the storage adapter has no per-key write
      * ordering, so two in-flight saves (a flush racing a consolidation) could
      * physically land out of order and persist a STALE segment list — losing a
@@ -715,6 +723,31 @@ export class NativeDiskAnnWrapper {
     isMigrating() {
         return this.migrationCoordinatorGetter?.()?.isMigrating() ?? false;
     }
+    /**
+     * @description **Readiness contract (brainy ≥ 8.0.12).** Honest durability
+     * signal for brainy's per-leg cold-open rebuild gate: `true` ⇔ the persisted
+     * index is loaded (or there is none to load) and a rebuild from canonical
+     * would be redundant. Brainy defers to this INSTEAD of the `size()===0`
+     * heuristic — a disk-native index legitimately reports zero resident nodes
+     * while fully durable, which is exactly why `size()` is the wrong gate.
+     *
+     * Returns `false` only when a durable base index was present but FAILED to
+     * load ({@link durableBaseLoadFailed}) — never claim ready over a failed load,
+     * or the gate would serve silent-empty results instead of recovering via
+     * `rebuild()`. A fresh brain (no durable index) is ready: loading nothing
+     * succeeds and a rebuild is a no-op. Partially-skipped L0 segments do NOT make
+     * it not-ready — their entries remain in canonical and heal via consolidation
+     * (see {@link loadSegmentManifest}).
+     * @returns `true` when a cold-open rebuild would be redundant.
+     */
+    isReady() {
+        if (this.durableBaseLoadFailed)
+            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.
+        return this.segmentsLoaded;
+    }
     /**
      * @description **#18 migration lock — structured progress** Brainy relays into
      * `getIndexStatus().migration`. `null` unless a migration is in flight.
@@ -1056,6 +1089,9 @@ export class NativeDiskAnnWrapper {
         // the #72 Phase A+B win. slot ↔ uuid resolution flows through the
         // mmap slotmaps + the canonical mapper on every query.
         this.native = newNative;
+        // A completed rebuild regenerates the base index + its slotmap sidecar, so
+        // any prior failed-durable-load state is now resolved — the index is ready.
+        this.durableBaseLoadFailed = false;
         // Reconcile the LIVE delta/tombstones against the fold snapshot: only
         // entries the fold actually baked in are cleared. Adds/updates/removes
         // that landed during the async build stay behind for the next fold (an
@@ -1094,7 +1130,32 @@ export class NativeDiskAnnWrapper {
      * size for parity with HNSW's flush contract.
      */
     async flush() {
-        return this.delta.size;
+        // **Durable close (readiness contract).** Persist the in-memory delta to a
+        // durable L0 segment. brainy calls flush() on shutdown/close (never per
+        // write — verified against its flushOnShutdown + close paths), so a brain
+        // that added fewer than the soft auto-fold threshold ({@link
+        // DELTA_SOFT_FOLD_BYTES}) still lands ALL its writes durably on a clean
+        // close. WITHOUT this, that sub-threshold delta lived only in canonical
+        // storage and the vector index rebuilt it from canonical on the NEXT open —
+        // a cold-open rebuild on every restart (the 48s-per-boot class; a small
+        // brain never folds, so it paid it forever). After this flush the durable
+        // base + segments reflect every persisted entity, so {@link isReady}
+        // reports true at brainy's cold-open gate and the rebuild is skipped.
+        //
+        // Drain any in-flight fold first (it may already be persisting this delta),
+        // then persist whatever remains. flushDeltaToL0 no-ops on an empty delta and
+        // coalesces with a concurrent flush; a transient base/L0 overlap is
+        // deduplicated at search time by the per-hit authority check. Bounded cost:
+        // repeated small closes make small L0s that consolidation merges at
+        // L0_COMPACT_THRESHOLD.
+        const pending = this.delta.size;
+        if (this.flushInFlight)
+            await this.flushInFlight;
+        if (this.rebuildInFlight)
+            await this.rebuildInFlight;
+        if (this.delta.size > 0)
+            await this.flushDeltaToL0();
+        return pending;
     }
     getPersistMode() {
         return this.persistMode;
@@ -1114,10 +1175,18 @@ export class NativeDiskAnnWrapper {
         return false;
     }
     /**
-     * @description Provider init — brainy feature-detects and awaits it. Cold-loads
-     * the segment manifest so a reopened brain serves its L0 segments from the
-     * first query (the wrapper's own async paths also call {@link ensureSegments},
-     * so a caller that skips init() still gets the segments lazily).
+     * @description **Readiness contract (brainy ≥ 8.0.12).** Provider init — brainy
+     * feature-detects and awaits it once during brain open, after the metadata
+     * provider's `init()` (id-mapper hydrated) and BEFORE its cold-open rebuild
+     * gate. The base index is mmap-attached in the constructor ({@link
+     * tryOpenExisting}); this eager cold-load attaches the L0 **segment** set too,
+     * so `size()`/{@link isReady} reflect the FULL persisted index at the gate
+     * rather than the base alone. Without it the async segment cold-load defers
+     * past the gate, `size()` reads low/zero, and brainy rebuilds from canonical on
+     * every open (the 48s-per-boot class). An mmap attach — O(pages touched), never
+     * an O(N) rebuild — so it stays cheap at billion scale. (The wrapper's own
+     * async paths also call {@link ensureSegments}, so a caller that skips init()
+     * still gets the segments lazily; only the pre-gate timing needs init().)
      */
     async init() {
         await this.ensureSegments();
@@ -1228,7 +1297,17 @@ export class NativeDiskAnnWrapper {
         const builtDelta = new Map(this.delta);
         if (builtDelta.size === 0)
             return;
-        const dim = this.config.dimensions;
+        // Resolve the vector dimension robustly. `this.config.dimensions` is the
+        // declared dim, but brainy's zero-config vector factory does not always pass
+        // it (the wrapper marks it "required", yet a provider constructed without it
+        // must still flush on close). Fall back to the attached base index's header,
+        // then to the delta's own vectors — every vector in a brain shares one dim
+        // (brainy enforces the embedding model's). Without this fallback, flush()
+        // on a zero-config brain threw `≠ index dim undefined` on every close.
+        const firstVec = builtDelta.values().next().value;
+        const dim = this.config.dimensions ??
+            (this.native ? this.native.header().dim : undefined) ??
+            firstVec.length;
         const mapper = this.mapper();
         const deltaBuf = new Float32Array(builtDelta.size * dim);
         const slotIdsArr = new BigUint64Array(builtDelta.size);
@@ -1320,15 +1399,26 @@ export class NativeDiskAnnWrapper {
             // .slots.json parse). No mapper is needed here; slot↔uuid
             // resolution happens lazily at query/rebuild time.
             if (!this.native.slotmapReady()) {
+                // The base index file is present but its slotmap sidecar is missing —
+                // the index exists on disk but can't map hits to entity ints. It must
+                // be regenerated by rebuild(); until then this is a FAILED durable load,
+                // not a fresh/empty brain. isReady() reports it so brainy's gate
+                // recovers via rebuild instead of skipping over an unusable index.
                 this.native = null;
+                this.durableBaseLoadFailed = true;
             }
             else {
                 this.removeLegacySlotsSidecar();
             }
         }
         catch {
-            // No existing file — index stays empty until first rebuild().
+            // openExisting threw. Distinguish a fresh brain (no file — normal, index
+            // stays empty until the first rebuild) from a corrupt/unreadable durable
+            // index that IS on disk (a failed load that needs rebuild recovery).
             this.native = null;
+            const path = this.config.indexPath;
+            if (path !== undefined && existsSync(path))
+                this.durableBaseLoadFailed = true;
         }
     }
     /**

package/dist/utils/NativeMetadataIndex.d.ts

@@ -97,6 +97,12 @@ export declare class MetadataIndexManager implements MetadataIndexProvider {
     private config;
     private native;
     private isRebuilding;
+    /**
+     * True once {@link init} has finished loading the durable derived state
+     * (registry + LSM cold-load + column store). Gates {@link isReady} so brainy's
+     * cold-open rebuild gate never skips over an index that has not loaded yet.
+     */
+    private readinessInitialized;
     /**
      * **#18** — set true by {@link guardIndexEpoch} outcome 4 (large stale brain,
      * auto-migrate enabled) and read once at the END of {@link init}, which kicks the
@@ -497,6 +503,21 @@ export declare class MetadataIndexManager implements MetadataIndexProvider {
      */
     getIdMapper(): EntityIdMapperLike;
     init(): Promise<void>;
+    /**
+     * @description **Readiness contract (brainy ≥ 8.0.12).** Honest durability
+     * signal for brainy's per-leg cold-open rebuild gate: `true` ⇔ this metadata
+     * index is loaded and a rebuild from canonical would be redundant. Brainy
+     * defers to this INSTEAD of the `getStats().totalEntries === 0` heuristic.
+     *
+     * Returns `false` when: `init()` has not completed; a migration is in flight
+     * (the gate skips a migrating leg, and the migration itself rebuilds); or the
+     * field registry lists fields but the LSM engine recovered NO durable state —
+     * the derived index is genuinely missing and a rebuild must run (never let the
+     * gate skip a legitimate recovery). Otherwise (durable LSM loaded, or a
+     * genuinely empty brain) a rebuild is redundant and this returns `true`.
+     * @returns `true` when a cold-open rebuild would be redundant.
+     */
+    isReady(): boolean;
     /**
      * **#72 Phase C.** Build the shared mmap `BinaryIdMapper` from the
      * brain's `_id_mapper/*` storage paths and inject it into the Rust

package/dist/utils/NativeMetadataIndex.js

@@ -171,6 +171,12 @@ export class MetadataIndexManager {
     config;
     native;
     isRebuilding = false;
+    /**
+     * True once {@link init} has finished loading the durable derived state
+     * (registry + LSM cold-load + column store). Gates {@link isReady} so brainy's
+     * cold-open rebuild gate never skips over an index that has not loaded yet.
+     */
+    readinessInitialized = false;
     /**
      * **#18** — set true by {@link guardIndexEpoch} outcome 4 (large stale brain,
      * auto-migrate enabled) and read once at the END of {@link init}, which kicks the
@@ -1108,11 +1114,39 @@ export class MetadataIndexManager {
         // `.catch` only prevents an unhandled rejection on the start() promise when a
         // failed migration surfaces (it is logged loudly and keeps the brain locked). No coordinator
         // wired (raw-napi test / non-migrating tier) → no-op.
+        // Readiness contract (brainy ≥ 8.0.12): everything durable has now been
+        // loaded (registry + LSM cold-load + column store) or determined absent.
+        // Set BEFORE the migration kick — during a migration isReady() reports
+        // not-ready via isMigrating(), and brainy's gate skips a migrating leg anyway.
+        this.readinessInitialized = true;
         if (this.epochMigrationPending) {
             this.epochMigrationPending = false;
             this.migrationCoordinatorGetter?.()?.start().catch(() => { });
         }
     }
+    /**
+     * @description **Readiness contract (brainy ≥ 8.0.12).** Honest durability
+     * signal for brainy's per-leg cold-open rebuild gate: `true` ⇔ this metadata
+     * index is loaded and a rebuild from canonical would be redundant. Brainy
+     * defers to this INSTEAD of the `getStats().totalEntries === 0` heuristic.
+     *
+     * Returns `false` when: `init()` has not completed; a migration is in flight
+     * (the gate skips a migrating leg, and the migration itself rebuilds); or the
+     * field registry lists fields but the LSM engine recovered NO durable state —
+     * the derived index is genuinely missing and a rebuild must run (never let the
+     * gate skip a legitimate recovery). Otherwise (durable LSM loaded, or a
+     * genuinely empty brain) a rebuild is redundant and this returns `true`.
+     * @returns `true` when a cold-open rebuild would be redundant.
+     */
+    isReady() {
+        if (!this.readinessInitialized)
+            return false;
+        if (this.isMigrating())
+            return false;
+        if (this.knownFields.size > 0 && !this.lsmHasDurableState())
+            return false;
+        return true;
+    }
     // ==========================================================================
     // Storage I/O helpers
     // ==========================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/cor",
-  "version": "3.0.4",
+  "version": "3.0.5",
   "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",
@@ -82,7 +82,7 @@
   },
   "devDependencies": {
     "@napi-rs/cli": "^3.0.0",
-    "@soulcraft/brainy": "8.0.11",
+    "@soulcraft/brainy": "8.0.12",
     "@types/node": "^22.0.0",
     "pg": "^8.21.0",
     "tsx": "^4.21.0",