@soulcraft/cor 3.0.11 → 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
@@ -1030,8 +1044,33 @@ export interface NativeLsmEngineInstance {
      * data lives in both the log and the persisted SSTable, so the log copy is
      * safe to retire. No-op for in-memory engines (constructed without
      * `openWithDir`).
+     *
+     * Returns the number of records CARRIED FORWARD across the shard-log
+     * rotations — writes that landed between the flush's drain snapshot and
+     * this commit (the wrapper's `await`s on blob + manifest IO let the event
+     * loop run writes in that window). Carried records stay replayable in the
+     * fresh active logs and drain with the next flush; pre-3.0.12 rotations
+     * exiled them into never-replayed archives (CORTEX-RESTART-STRAND).
+     */
+    commitFlushThrough(throughEpoch: bigint): number;
+    /**
+     * Replay accounting from the memtable's cold open, as JSON:
+     * `{ activeRecords, archiveRecovered, archivesUnreadable, tornTailBytes,
+     * liveLogsRecreated, anomalousShards: string[] }`. Logged loudly at init
+     * when any anomaly is non-zero — the forensic record of what cold-open
+     * recovery found, captured BEFORE any rebuild wipes the evidence.
+     * `liveLogsRecreated > 0` or `archivesUnreadable > 0` is a strand verdict
+     * (unflushed records from a missing live log are unknowable).
+     */
+    replayStatsJson(): string;
+    /**
+     * Toggle bulk-load mode on the shard logs. `true` suspends the
+     * per-append msyncs — rebuild-from-canonical ONLY (canonical is the
+     * durability source; a crashed rebuild re-runs). `false` restores them
+     * and performs one full msync per shard: the rebuild's single durability
+     * point. Never used on the live write path.
      */
-    commitFlushThrough(throughEpoch: bigint): void;
+    setBulkLoad(on: boolean): void;
     /**
      * Update the budget ceiling. Driven by the wrapper's
      * `ResourceManager` subscriber callback. Pass `0xffffffffffffffffn`

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/dist/utils/NativeMetadataIndex.d.ts

@@ -889,6 +889,15 @@ export declare class MetadataIndexManager implements MetadataIndexProvider {
      * @returns the number of entities indexed (those carrying metadata).
      */
     private rebuildEntityMetadata;
+    /**
+     * Rebuild-path verify-read for a single entity's canonical metadata.
+     * Retries once on a thrown read, then rethrows — a rebuild must NEVER
+     * silently exclude an entity because a storage read faulted (that
+     * completes the rebuild under-posted and clears the strand verdict
+     * over missing data). A clean `null`/`undefined` result is returned
+     * as `null` — a genuinely metadata-less record, the caller counts it.
+     */
+    private readRebuildMetadataOrThrow;
     /**
      * Batch-load metadata for a page of noun/verb ids — prefers the storage
      * adapter's batch API, falls back to per-id reads.

package/dist/utils/NativeMetadataIndex.js

@@ -487,6 +487,35 @@ export class MetadataIndexManager {
                 engine.registerSstablePath(path);
             }
         }
+        // Cold-open replay forensics (CORTEX-RESTART-STRAND). The engine's
+        // open replayed the active shard logs AND recovered any records a
+        // prior session exiled into archives (pre-carry-forward rotations,
+        // mid-rotation crashes). Surface every anomaly LOUDLY here — this
+        // line is the evidence that survives even if a rebuild later wipes
+        // the on-disk state.
+        if (metaDir !== null && typeof this.lsmEngine.replayStatsJson === 'function') {
+            try {
+                const stats = JSON.parse(this.lsmEngine.replayStatsJson());
+                if (stats.archiveRecovered > 0 ||
+                    stats.archivesUnreadable > 0 ||
+                    stats.tornTailBytes > 0) {
+                    prodLog.error(`[NativeMetadataIndex] COLD-OPEN RECOVERY: replayed ` +
+                        `${stats.activeRecords} active-log record(s); RECOVERED ` +
+                        `${stats.archiveRecovered} record(s) exiled into archives by a ` +
+                        `prior session; ${stats.archivesUnreadable} unreadable ` +
+                        `archive(s); ${stats.tornTailBytes} torn-tail byte(s). ` +
+                        `Recovered records are served and drain with the next flush. ` +
+                        `Per-shard: ${stats.anomalousShards.join(' | ')}`);
+                }
+            }
+            catch (error) {
+                prodLog.warn('[NativeMetadataIndex] replay-forensics read failed (non-fatal):', error);
+            }
+        }
+        else if (metaDir !== null) {
+            prodLog.warn('[NativeMetadataIndex] replay forensics unavailable — the loaded ' +
+                'native binary predates 3.0.12; upgrade the paired .node build.');
+        }
     }
     /**
      * **LSM durability (steps 3-4) — the sync part.** Register the
@@ -766,7 +795,18 @@ export class MetadataIndexManager {
         // flushed data is safely in the new SSTable. Warn + continue rather than
         // abort the rebuild — the next clean flush retires the log.
         try {
-            engine.commitFlushThrough(result.lastDurableEpoch);
+            const carried = engine.commitFlushThrough(result.lastDurableEpoch);
+            // Writes that landed during THIS flush's blob/manifest awaits (the
+            // event loop runs between the drain and this commit) were carried
+            // into the fresh active logs — they stay replayable and drain with
+            // the next flush. Logged for the write-ack audit trail: pre-3.0.12
+            // rotations exiled exactly these records into never-replayed
+            // archives (CORTEX-RESTART-STRAND).
+            if (typeof carried === 'number' && carried > 0) {
+                prodLog.info(`flushLsm: carried ${carried} concurrent-write record(s) across ` +
+                    `the shard-log rotation for SSTable ${id} — they drain with the ` +
+                    `next flush.`);
+            }
         }
         catch (error) {
             prodLog.warn(`flushLsm: commitFlushThrough deferred for SSTable ${id} (it + the ` +
@@ -1197,6 +1237,36 @@ export class MetadataIndexManager {
     async detectDerivedStrand() {
         if (!this.lsmEngine || !this.lsmMetaDir)
             return;
+        // 0. Replay-stats verdict (3.0.12). The native open now RECREATES a
+        // missing live log and recovers what its archives hold, so the
+        // filename census below can no longer see the deleted-live-log
+        // signature — the native layer reports it instead. Either condition
+        // is a strand verdict: a recreated-with-archives shard may have held
+        // UNFLUSHED records that lived only in the missing live log
+        // (unknowable — rebuild is the only honest answer), and an
+        // unreadable archive means potentially-exiled records were
+        // unreachable to recovery.
+        try {
+            const engine = this.lsmEngine;
+            if (typeof engine.replayStatsJson === 'function') {
+                const stats = JSON.parse(engine.replayStatsJson());
+                const recreated = stats.liveLogsRecreated ?? 0;
+                const unreadable = stats.archivesUnreadable ?? 0;
+                if (recreated > 0 || unreadable > 0) {
+                    this.strandDetected = true;
+                    prodLog.error(`[NativeMetadataIndex] STRAND: cold-open replay reports ` +
+                        `${recreated} shard live log(s) MISSING (recreated; archives ` +
+                        `recovered what they held, but unflushed records from the ` +
+                        `missing logs are unknowable) and ${unreadable} unreadable ` +
+                        `archive(s). Reporting not-ready so the cold-open gate ` +
+                        `rebuilds from canonical. Per-shard: ` +
+                        `${(stats.anomalousShards ?? []).join(' | ')}`);
+                }
+            }
+        }
+        catch {
+            // Verdict probe is advisory — a stats read failure must not block open.
+        }
         // 1. Archive-orphan census over the memtable shard logs.
         try {
             const memtableDir = join(this.lsmMetaDir, 'memtable');
@@ -2584,8 +2654,31 @@ export class MetadataIndexManager {
             // branch loaded the whole corpus in a single getNouns/getVerbs({limit:1e6})
             // call (cap 1M), and the cloud branch capped at MAX_ITERATIONS(10000)×
             // batch(25) ≈ 250K. (#74 — perf-at-all-scales mandate.)
-            const totalNounsProcessed = await this.rebuildEntityMetadata('noun');
-            const totalVerbsProcessed = await this.rebuildEntityMetadata('verb');
+            // Bulk-load mode for the re-post walk: canonical is the durability
+            // source during a rebuild (a crash re-runs it), so the per-append
+            // shard-log msyncs — ~2 synchronous disk flushes per posting record,
+            // the mechanism behind memory-vm's MEASURED ~1.3-2 items/s (30 min
+            // for 2,354 entities on e2-standard-2, CORTEX-RESTART-STRAND) — are
+            // suspended and replaced by ONE full msync per shard at the end of
+            // the walk (setBulkLoad(false), inside finally so a failed rebuild
+            // can never leave the live write path in deferred mode).
+            const bulkCapable = this.lsmEngine !== null &&
+                typeof this.lsmEngine.setBulkLoad ===
+                    'function';
+            if (bulkCapable)
+                this.lsmEngine.setBulkLoad(true);
+            let totalNounsProcessed;
+            let totalVerbsProcessed;
+            try {
+                totalNounsProcessed = await this.rebuildEntityMetadata('noun');
+                totalVerbsProcessed = await this.rebuildEntityMetadata('verb');
+            }
+            finally {
+                // Leaving bulk mode performs the walk's single durability point
+                // (one full msync per shard log).
+                if (bulkCapable)
+                    this.lsmEngine.setBulkLoad(false);
+            }
             // Final flush
             await this.flushRebuildDirty();
             await this.flush();
@@ -2616,6 +2709,7 @@ export class MetadataIndexManager {
         let hasMore = true;
         let processed = 0;
         let sinceFlush = 0;
+        let noMetadata = 0;
         while (hasMore) {
             const page = kind === 'noun'
                 ? await this.storage.getNouns({ pagination: { limit: PAGE, cursor } })
@@ -2626,7 +2720,16 @@ export class MetadataIndexManager {
             const ids = items.map((it) => it.id);
             const md = await this.loadRebuildMetadataBatch(kind, ids);
             for (const it of items) {
-                const metadata = md.get(it.id);
+                // An id enumerated by canonical but absent from the batch result
+                // gets an individual verify-read: a batch adapter may return a
+                // partial map on an internal fault, and silently skipping the
+                // entity would complete the rebuild UNDER-POSTED — the exact
+                // damage the strand detector exists to catch, laundered by its
+                // own healer (the 01:31 memory-vm rebuild's failure shape). The
+                // verify-read retries once, then FAILS THE REBUILD loudly; a
+                // clean null (a genuinely metadata-less record) is counted +
+                // reported, never silently dropped.
+                const metadata = md.get(it.id) ?? (await this.readRebuildMetadataOrThrow(kind, it.id));
                 if (metadata) {
                     await this.addToIndex(it.id, metadata, true, true);
                     processed++;
@@ -2635,13 +2738,49 @@ export class MetadataIndexManager {
                         sinceFlush = 0;
                     }
                 }
+                else {
+                    noMetadata++;
+                }
             }
             hasMore = page.hasMore;
             cursor = page.nextCursor;
             await this.yieldToEventLoop();
         }
+        if (noMetadata > 0) {
+            prodLog.warn(`[NativeMetadataIndex] rebuild(${kind}): ${noMetadata} enumerated ` +
+                `entit${noMetadata === 1 ? 'y' : 'ies'} carried no canonical ` +
+                `metadata (verified by direct read) and were not indexed — ` +
+                `expected only for metadata-less legacy records.`);
+        }
         return processed;
     }
+    /**
+     * Rebuild-path verify-read for a single entity's canonical metadata.
+     * Retries once on a thrown read, then rethrows — a rebuild must NEVER
+     * silently exclude an entity because a storage read faulted (that
+     * completes the rebuild under-posted and clears the strand verdict
+     * over missing data). A clean `null`/`undefined` result is returned
+     * as `null` — a genuinely metadata-less record, the caller counts it.
+     */
+    async readRebuildMetadataOrThrow(kind, id) {
+        const read = () => kind === 'noun'
+            ? this.storage.getNounMetadata(id)
+            : this.storage.getVerbMetadata(id);
+        try {
+            return (await read()) ?? null;
+        }
+        catch {
+            try {
+                return (await read()) ?? null;
+            }
+            catch (error) {
+                throw new Error(`[NativeMetadataIndex] rebuild(${kind}): canonical metadata read ` +
+                    `for '${id}' faulted twice — failing the rebuild rather than ` +
+                    `silently excluding the entity (an under-posted rebuild is the ` +
+                    `strand bug reintroduced by its own healer). Cause: ${String(error)}`);
+            }
+        }
+    }
     /**
      * Batch-load metadata for a page of noun/verb ids — prefers the storage
      * adapter's batch API, falls back to per-id reads.
@@ -2656,14 +2795,13 @@ export class MetadataIndexManager {
         }
         const m = new Map();
         for (const id of ids) {
-            try {
-                const md = kind === 'noun'
-                    ? await this.storage.getNounMetadata(id)
-                    : await this.storage.getVerbMetadata(id);
-                if (md)
-                    m.set(id, md);
-            }
-            catch { }
+            // Retry-once-then-throw (readRebuildMetadataOrThrow): a faulted
+            // read must fail the rebuild loudly, never silently exclude the
+            // entity — a swallowed fault here completed the rebuild
+            // under-posted (the strand bug re-created by its own healer).
+            const md = await this.readRebuildMetadataOrThrow(kind, id);
+            if (md)
+                m.set(id, md);
         }
         return m;
     }

package/docs/snapshot-safety.md

@@ -128,7 +128,13 @@ is the reference implementation.
    tail offset; live writers append past that offset without
    affecting what the snapshot reader sees. On compaction
    commit the delta is renamed to a `.archive` sibling and a
-   fresh empty delta replaces it.
+   fresh delta replaces it, carrying forward any record newer
+   than the commit watermark — a record appended while the
+   commit's durability IO was in flight stays replayable in the
+   fresh delta, never exiled to the archive. Opens also scan
+   retained archives for records above the watermark and
+   recover them, so even a rotation interrupted between its two
+   renames loses nothing.
 
 3. **Atomic head pointer** (`head`) — a tiny text file named by
    `PointerFile` (`diskann::pointer_file`). Names the current

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
   /**
@@ -1260,8 +1271,34 @@ export declare class NativeLsmEngine {
    *
    * No-op for in-memory engines (constructed without
    * `openWithDir`).
-   */
-  commitFlushThrough(throughEpoch: bigint): void
+   *
+   * Returns the number of records carried forward across the
+   * shard-log rotations — writes that landed between the flush's
+   * drain snapshot and this commit (the wrapper's async
+   * durability-IO window; the JS event loop runs writes there).
+   * They stay replayable in the fresh active logs and drain with
+   * the next flush. The wrapper logs non-zero counts for the
+   * write-ack audit trail.
+   */
+  commitFlushThrough(throughEpoch: bigint): number
+  /**
+   * Toggle bulk-load mode on the shard logs. `true` suspends the
+   * per-append msyncs — for rebuild-from-canonical ONLY (canonical
+   * is the durability source; a crashed rebuild re-runs). `false`
+   * restores them and performs one full msync per shard: the
+   * rebuild's single durability point. Never used on the live
+   * write path, whose ack contract requires the per-append msync.
+   */
+  setBulkLoad(on: boolean): void
+  /**
+   * Replay accounting from the memtable's cold open, as JSON:
+   * `{ activeRecords, archiveRecovered, archivesUnreadable,
+   * tornTailBytes, anomalousShards: string[] }`. The wrapper logs
+   * this at init when any anomaly is non-zero — the forensic
+   * record of what cold-open recovery found, captured BEFORE any
+   * rebuild wipes the evidence (CORTEX-RESTART-STRAND).
+   */
+  replayStatsJson(): string
   /** `"u32"` or `"u64"`. */
   idSpace(): string
   /**
@@ -2726,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.11",
+  "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.2",
+    "@soulcraft/brainy": "8.2.6",
     "@types/node": "^22.0.0",
     "pg": "^8.21.0",
     "tsx": "^4.21.0",