@soulcraft/cor 3.0.12 → 3.0.13

package/dist/graph/NativeGraphAdjacencyIndex.d.ts

@@ -150,8 +150,12 @@ export declare class GraphAdjacencyIndex implements GraphIndexProvider {
      * 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.
+     * compute ready from the resident SSTables and never reach the probe.
+     * Truly edgeless brains (no canonical verbs) stay ready, so the
+     * boot-rebuild/502 class stays dead. The size() guard is honest under
+     * partial loads (3.0.13): the native count degrades to memtable-resident
+     * when the manifest's claim is not fully loaded, so a damaged durable set
+     * can no longer suppress this probe.
      */
     private probeCanonicalCoverage;
     /**

package/dist/graph/NativeGraphAdjacencyIndex.js

@@ -243,8 +243,12 @@ export class GraphAdjacencyIndex {
      * 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.
+     * compute ready from the resident SSTables and never reach the probe.
+     * Truly edgeless brains (no canonical verbs) stay ready, so the
+     * boot-rebuild/502 class stays dead. The size() guard is honest under
+     * partial loads (3.0.13): the native count degrades to memtable-resident
+     * when the manifest's claim is not fully loaded, so a damaged durable set
+     * can no longer suppress this probe.
      */
     async probeCanonicalCoverage() {
         if (this.native.isReady() || this.native.size() > 0)
@@ -566,14 +570,24 @@ export class GraphAdjacencyIndex {
         // 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
-        // is false and brainy correctly rebuilds.
         const raw = this.native.getStats();
         const s = typeof raw === 'string' ? JSON.parse(raw) : raw;
+        // 3.0.13: the native engine reports manifest-vs-resident truth. A
+        // manifest naming SSTables that are not ALL resident means the graph
+        // would serve a subset of its edges — never ready (brainy's gate
+        // rebuilds; the rebuild persists a truthful manifest and clears this).
+        // Absent on pre-3.0.13 binaries (undefined ≠ false → skip).
+        if (s?.loadComplete === false)
+            return false;
+        // Native reported not-ready with a complete (or absent) durable set.
+        // Ready ⇔ there is nothing durable to load: no SSTables and empty
+        // memtables across ALL FOUR trees (the verbs trees were structurally
+        // invisible here before 3.0.13 — a dead verbs-source with a live
+        // source tree slipped through as "empty").
         const durableEmpty = Number(s?.sourceSstableCount ?? 0) === 0 &&
             Number(s?.targetSstableCount ?? 0) === 0 &&
+            Number(s?.verbsSourceSstableCount ?? 0) === 0 &&
+            Number(s?.verbsTargetSstableCount ?? 0) === 0 &&
             Number(s?.sourceMemTableSize ?? 0) === 0 &&
             Number(s?.targetMemTableSize ?? 0) === 0;
         return durableEmpty;

package/dist/native/types.d.ts

@@ -461,6 +461,20 @@ export interface GraphAdjacencyStats {
     verbIdCountBig: bigint;
     /** BigInt relationship type count. */
     relationshipTypeCountBig: bigint;
+    /**
+     * Verbs-source tree SSTable count (3.0.13 — the readiness fallback was
+     * structurally blind to the verbs trees before these fields existed).
+     * Absent on pre-3.0.13 binaries.
+     */
+    verbsSourceSstableCount?: number;
+    /** Verbs-target tree SSTable count. Absent on pre-3.0.13 binaries. */
+    verbsTargetSstableCount?: number;
+    /**
+     * Whether every manifest-named SSTable across all four trees is actually
+     * resident. `false` = the graph would serve a subset of its durable edges
+     * and reports not-ready. Absent on pre-3.0.13 binaries.
+     */
+    loadComplete?: boolean;
 }
 /**
  * Result from flushing a tree's MemTable to binary .sst format

package/dist/utils/NativeColumnStore.d.ts

@@ -86,6 +86,18 @@ export declare class NativeColumnStore implements ColumnStoreProvider {
      * TS copy is what gets persisted to `DELETED.bin` and re-applied on init.
      */
     private readonly deletedEntities;
+    /**
+     * Fields whose persisted state could not be FULLY loaded because a read
+     * FAULTED (threw) — as opposed to a blob being cleanly absent. A faulted
+     * field's column index may be silently partial (missing segments) or
+     * resurrect deleted rows (tombstones unapplied), so serving queries from
+     * it would return wrong results with no error. Queries against a faulted
+     * field THROW instead ({@link assertFieldServable}) — loud errors, never
+     * quiet losses. Cleared by {@link reset} (a rebuild repopulates cleanly)
+     * and {@link close}. Ready for brainy's loadBinaryBlob fault-vs-absent
+     * tightening (EIO throws instead of returning null).
+     */
+    private readonly faultedFields;
     /**
      * Create a native column store. Call {@link init} before queries that need
      * storage (loading persisted segments). Writes work immediately — the Rust
@@ -122,6 +134,15 @@ export declare class NativeColumnStore implements ColumnStoreProvider {
      * @param entityIntId - The entity's u32 id.
      */
     removeEntity(entityIntId: number): void;
+    /**
+     * @description Refuse to serve a field whose persisted column state
+     * faulted at load — a partial segment set or unapplied tombstones would
+     * return WRONG results silently. Throwing names the field and the heal
+     * path; the caller's error surfaces where a silent empty/partial result
+     * would have been invisible.
+     * @param field - Field about to be served.
+     */
+    private assertFieldServable;
     /**
      * @description Point filter: entity int ids whose `field` equals `value`.
      * Routes to the numeric/float/string Rust filter by the field's value type.

package/dist/utils/NativeColumnStore.js

@@ -105,6 +105,18 @@ export class NativeColumnStore {
      * TS copy is what gets persisted to `DELETED.bin` and re-applied on init.
      */
     deletedEntities = new Map();
+    /**
+     * Fields whose persisted state could not be FULLY loaded because a read
+     * FAULTED (threw) — as opposed to a blob being cleanly absent. A faulted
+     * field's column index may be silently partial (missing segments) or
+     * resurrect deleted rows (tombstones unapplied), so serving queries from
+     * it would return wrong results with no error. Queries against a faulted
+     * field THROW instead ({@link assertFieldServable}) — loud errors, never
+     * quiet losses. Cleared by {@link reset} (a rebuild repopulates cleanly)
+     * and {@link close}. Ready for brainy's loadBinaryBlob fault-vs-absent
+     * tightening (EIO throws instead of returning null).
+     */
+    faultedFields = new Set();
     /**
      * Create a native column store. Call {@link init} before queries that need
      * storage (loading persisted segments). Writes work immediately — the Rust
@@ -164,8 +176,13 @@ export class NativeColumnStore {
                 await this.loadDeletedBitmap(field);
             }
             catch (error) {
-                prodLog.warn(`NativeColumnStore: failed to load column field '${field}' — skipping it; ` +
-                    `other fields are unaffected`, error);
+                // The field's manifest/segments faulted wholesale — mark it faulted
+                // so queries THROW instead of silently returning empty (the
+                // pre-3.0.13 behavior: fieldTypes never set → filter() returned an
+                // empty bitmap with no error).
+                this.faultedFields.add(field);
+                prodLog.error(`NativeColumnStore: failed to load column field '${field}' — marked ` +
+                    `unavailable (queries will throw); other fields are unaffected`, error);
             }
         }
     }
@@ -216,6 +233,22 @@ export class NativeColumnStore {
             deleted.add(entityIntId);
         }
     }
+    /**
+     * @description Refuse to serve a field whose persisted column state
+     * faulted at load — a partial segment set or unapplied tombstones would
+     * return WRONG results silently. Throwing names the field and the heal
+     * path; the caller's error surfaces where a silent empty/partial result
+     * would have been invisible.
+     * @param field - Field about to be served.
+     */
+    assertFieldServable(field) {
+        if (this.faultedFields.has(field)) {
+            throw new Error(`NativeColumnStore: column index for field '${field}' is UNAVAILABLE — ` +
+                `a persisted segment or tombstone read FAULTED at load (not merely ` +
+                `absent), so serving it would silently return partial/wrong results. ` +
+                `Heal: restore storage health and restart, or rebuild the metadata index.`);
+        }
+    }
     /**
      * @description Point filter: entity int ids whose `field` equals `value`.
      * Routes to the numeric/float/string Rust filter by the field's value type.
@@ -224,6 +257,7 @@ export class NativeColumnStore {
      * @returns Roaring bitmap of matching entity int ids.
      */
     async filter(field, value) {
+        this.assertFieldServable(field);
         const type = this.fieldTypes.get(field);
         if (type === undefined)
             return new RoaringBitmap32();
@@ -283,6 +317,7 @@ export class NativeColumnStore {
      * @returns Roaring bitmap of matching entity int ids.
      */
     async rangeQuery(field, min, max) {
+        this.assertFieldServable(field);
         const type = this.fieldTypes.get(field);
         if (type === undefined)
             return new RoaringBitmap32();
@@ -323,6 +358,7 @@ export class NativeColumnStore {
      * @returns Sorted array of entity int ids.
      */
     async sortTopK(field, order, k) {
+        this.assertFieldServable(field);
         if (k <= 0)
             return [];
         // Cor 3.0 Piece E: napi returns BigInt[]. The wrapper narrows
@@ -342,6 +378,7 @@ export class NativeColumnStore {
      * @returns Sorted array of entity int ids, all present in `filterBitmap`.
      */
     async filteredSortTopK(filterBitmap, field, order, k) {
+        this.assertFieldServable(field);
         if (k <= 0 || filterBitmap.size === 0)
             return [];
         // Intersecting only the global top-K could drop matches when the filter is
@@ -371,6 +408,7 @@ export class NativeColumnStore {
      * @returns Distinct values stringified the way brainy renders them.
      */
     async getFilterValues(field) {
+        this.assertFieldServable(field);
         if (!this.native.hasField(field))
             return [];
         return this.native.distinctValues(field);
@@ -408,6 +446,7 @@ export class NativeColumnStore {
         this.manifests.clear();
         this.fieldTypes.clear();
         this.deletedEntities.clear();
+        this.faultedFields.clear();
         this.storage = null;
     }
     /**
@@ -439,11 +478,14 @@ export class NativeColumnStore {
             }
         }
         // Drop all native state by replacing the engine, then clear TS-side state.
+        // Faults clear too: the rebuild that follows repopulates every field
+        // cleanly from canonical, so the refusal-to-serve verdict is spent.
         const bindings = loadNativeModule();
         this.native = new bindings.NativeColumnStore();
         this.manifests.clear();
         this.fieldTypes.clear();
         this.deletedEntities.clear();
+        this.faultedFields.clear();
     }
     // =========================================================================
     // Internal helpers
@@ -596,9 +638,33 @@ export class NativeColumnStore {
                 prodLog.debug(`NativeColumnStore: mmap load failed for ${key}, trying buffer`, error);
             }
         }
-        const buf = fallbackBuffer ?? (await this.storage.loadBinaryBlob(key));
+        // Fault-vs-absent discrimination (spine law; ready for brainy's
+        // loadBinaryBlob tightening where an IO fault THROWS instead of
+        // returning null): a FAULTED read means the segment may exist but be
+        // unreadable — serving the field without it would silently return
+        // partial results, so the field is marked faulted (queries throw) and
+        // the remaining fields/segments continue loading. A clean null stays
+        // an absent segment (warn + skip, unchanged semantics).
+        let buf;
+        try {
+            buf = fallbackBuffer ?? (await this.storage.loadBinaryBlob(key));
+        }
+        catch (error) {
+            this.faultedFields.add(field);
+            prodLog.error(`NativeColumnStore: segment read FAULTED for ${key} — field ` +
+                `'${field}' marked unavailable (queries will throw, not return ` +
+                `partial results):`, error);
+            return;
+        }
         if (buf) {
-            this.native.loadSegmentFromBuffer(field, String(segId), buf);
+            try {
+                this.native.loadSegmentFromBuffer(field, String(segId), buf);
+            }
+            catch (error) {
+                this.faultedFields.add(field);
+                prodLog.error(`NativeColumnStore: segment attach FAULTED for ${key} (corrupt ` +
+                    `bytes?) — field '${field}' marked unavailable:`, error);
+            }
             return;
         }
         // No raw blob for this segment. A 2.x→3.0 upgrade does NOT read legacy
@@ -615,7 +681,21 @@ export class NativeColumnStore {
     async loadDeletedBitmap(field) {
         if (!this.storage)
             return;
-        const buf = await this.storage.loadBinaryBlob(deletedBlobKey(field));
+        // Fault-vs-absent: a FAULTED tombstone read leaves deleted rows
+        // resurrected in every query — worse than a missing segment, because
+        // the results are wrong rather than merely partial. Mark the field
+        // faulted (queries throw). A clean null = no tombstones, unchanged.
+        let buf;
+        try {
+            buf = await this.storage.loadBinaryBlob(deletedBlobKey(field));
+        }
+        catch (error) {
+            this.faultedFields.add(field);
+            prodLog.error(`NativeColumnStore: tombstone bitmap read FAULTED for field ` +
+                `'${field}' — deleted rows would resurrect; field marked ` +
+                `unavailable (queries will throw):`, error);
+            return;
+        }
         if (!buf)
             return;
         const bitmap = RoaringBitmap32.deserialize(buf, 'portable');

package/native/index.d.ts

@@ -1169,14 +1169,25 @@ export declare class NativeGraphAdjacencyIndex {
    * empty (a fresh brain with nothing persisted) and brainy should build
    * it.
    *
-   * **Edges-loaded semantics — never membership.** Returns `true` iff the
-   * graph actually holds edges through a durable or live path: the
-   * cold-load latch (set when an SSTable loads from binary/file, a manifest
-   * names ≥1 SSTable, or a memtable flushes to a persisted SSTable), or a
-   * currently non-empty memtable on any of the four trees. The verb-id
-   * membership bitmap — whose population is the deferred O(N) fast-follow —
-   * is deliberately NOT consulted, so a slow membership walk can never make
-   * a graph with queryable edges report "not ready".
+   * **Edges-loaded semantics — never membership, never a latch.**
+   * COMPUTED from actual residency (3.0.13; previously a boolean latched
+   * TRUE the moment a manifest merely NAMED an SSTable, before any file
+   * opened — a total load failure served ready forever):
+   *
+   * 1. If ANY tree's manifest names an SSTable that is not resident,
+   *    the graph is NOT ready — it would serve a silent subset of its
+   *    edges (e.g. verbs-source dead while getNeighbors works). This
+   *    clause dominates: live memtable writes cannot mask a partial
+   *    durable load.
+   * 2. Otherwise ready iff durable SSTables exist (all resident by
+   *    clause 1) or any memtable holds live edges. A fresh edgeless
+   *    brain reports false — the TS wrapper's edgeless-ready +
+   *    canonical-coverage logic owns that verdict.
+   *
+   * The verb-id membership bitmap — whose population is the deferred
+   * O(N) fast-follow — is deliberately NOT consulted, so a slow
+   * membership walk can never make a graph with queryable edges report
+   * "not ready".
    */
   isReady(): boolean
   /**
@@ -2752,6 +2763,19 @@ export interface GraphAdjacencyStats {
   verbIdCountBig: bigint
   /** Number of relationship types as a `BigInt`. */
   relationshipTypeCountBig: bigint
+  /**
+   * Verbs-source tree SSTable count (3.0.13 — the readiness fallback
+   * was structurally blind to the verbs trees before these fields).
+   */
+  verbsSourceSstableCount: number
+  /** Verbs-target tree SSTable count. */
+  verbsTargetSstableCount: number
+  /**
+   * Whether every manifest-named SSTable across all four trees is
+   * actually resident. False means the graph is serving (at most) a
+   * subset of its durable edges and `isReady()` reports not-ready.
+   */
+  loadComplete: boolean
 }
 
 /**

package/package.json

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