@soulcraft/cor 3.0.10 → 3.0.12

package/dist/native/types.d.ts

@@ -1030,8 +1030,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/NativeMetadataIndex.d.ts

@@ -103,6 +103,18 @@ export declare class MetadataIndexManager implements MetadataIndexProvider {
      * cold-open rebuild gate never skips over an index that has not loaded yet.
      */
     private readinessInitialized;
+    /**
+     * A derived-state strand was detected at cold open (CORTEX-CONSOLIDATION-
+     * SILENT-DROP, memory-vm 2026-07-12): postings lost while canonical is
+     * intact — e.g. memtable log shards deleted out from under the engine (15
+     * of 64 on the incident brain), whose histories silently vanish because a
+     * missing shard log is recreated empty on next touch. Set by
+     * {@link detectDerivedStrand} (archive-orphan census + the
+     * |canonical| == |posted| invariant); forces {@link isReady} to report
+     * `false` so brainy's cold-open gate runs the one rebuild that re-posts
+     * everything from canonical. Cleared by a completed {@link rebuild}.
+     */
+    private strandDetected;
     /**
      * **#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
@@ -518,6 +530,31 @@ export declare class MetadataIndexManager implements MetadataIndexProvider {
      * @returns `true` when a cold-open rebuild would be redundant.
      */
     isReady(): boolean;
+    /**
+     * Detect a derived-state STRAND at cold open: canonical is the source of
+     * truth, so any loss in the derived posting state — however it happened —
+     * surfaces as one of two signals checked here. Both are cheap (a directory
+     * listing + one bitmap-cardinality read + one canonical count probe), run
+     * once per open, never on a hot path. Advisory on storage adapters that
+     * can't answer (no blob paths / no exact counts): detection skips rather
+     * than false-positives. CORTEX-CONSOLIDATION-SILENT-DROP.
+     *
+     * 1. **Archive-orphan census.** The memtable log rotates
+     *    `memtable-shard-NN.log` → `*.archive` siblings and always recreates
+     *    the live file — so an archive WITHOUT its live log proves the live
+     *    log was deleted (the deleter's signature on memory-vm: 15 of 64
+     *    shards). A missing shard log silently replays nothing and is
+     *    recreated empty on next touch; without this census the loss is
+     *    invisible.
+     * 2. **The |canonical| == |posted| invariant.** Every live entity carries
+     *    exactly one `noun` posting, so the engine's total posted-entity count
+     *    must equal canonical's noun count. `posted < canonical` = stranded
+     *    entities (the incident's ~35 unqueryable writes); `posted > canonical`
+     *    = orphaned postings (egress-guarded at read time, reconciled by the
+     *    same rebuild). Skipped at/above the u32 saturation point of
+     *    `getTotalEntityCount` (a saturated count would make equality lie).
+     */
+    private detectDerivedStrand;
     /**
      * **#72 Phase C.** Build the shared mmap `BinaryIdMapper` from the
      * brain's `_id_mapper/*` storage paths and inject it into the Rust
@@ -852,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

@@ -15,7 +15,7 @@
  * Buffer exchange pattern: TS loads data from storage, passes JSON to Rust.
  * Rust operates in-memory, returns serialized state for TS to persist.
  */
-import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { prodLog, getGlobalCache, FieldTypeInference, resolveEntityField } from '@soulcraft/brainy/internals';
 import { compareCodePoints } from './collation.js';
@@ -177,6 +177,18 @@ export class MetadataIndexManager {
      * cold-open rebuild gate never skips over an index that has not loaded yet.
      */
     readinessInitialized = false;
+    /**
+     * A derived-state strand was detected at cold open (CORTEX-CONSOLIDATION-
+     * SILENT-DROP, memory-vm 2026-07-12): postings lost while canonical is
+     * intact — e.g. memtable log shards deleted out from under the engine (15
+     * of 64 on the incident brain), whose histories silently vanish because a
+     * missing shard log is recreated empty on next touch. Set by
+     * {@link detectDerivedStrand} (archive-orphan census + the
+     * |canonical| == |posted| invariant); forces {@link isReady} to report
+     * `false` so brainy's cold-open gate runs the one rebuild that re-posts
+     * everything from canonical. Cleared by a completed {@link rebuild}.
+     */
+    strandDetected = 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
@@ -475,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
@@ -754,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 ` +
@@ -1101,6 +1153,13 @@ export class MetadataIndexManager {
         await this.warmCache();
         await this.lazyLoadCounts();
         this.syncTypeCountsToFixed();
+        // Strand detection (CORTEX-CONSOLIDATION-SILENT-DROP): the LSM can load
+        // "durable state" that is silently MISSING postings — deleted shard logs
+        // replay nothing and are recreated empty on next touch, so the index
+        // serves healthy-while-broken. Detect it here, before the readiness
+        // contract reports ready, so brainy's gate heals via rebuild-from-
+        // canonical instead of trusting a partial index.
+        await this.detectDerivedStrand();
         // **#18 migration kick — LAST, after the index is fully constructed.** If the
         // epoch guard flagged a large stale brain (outcome 4), start the coordinated
         // blocking migration NOW: `start()` flips the lock (`isMigrating()` → true)
@@ -1145,8 +1204,140 @@ export class MetadataIndexManager {
             return false;
         if (this.knownFields.size > 0 && !this.lsmHasDurableState())
             return false;
+        // A detected strand (postings lost while canonical is intact) means a
+        // rebuild is NOT redundant — see {@link detectDerivedStrand}.
+        if (this.strandDetected)
+            return false;
         return true;
     }
+    /**
+     * Detect a derived-state STRAND at cold open: canonical is the source of
+     * truth, so any loss in the derived posting state — however it happened —
+     * surfaces as one of two signals checked here. Both are cheap (a directory
+     * listing + one bitmap-cardinality read + one canonical count probe), run
+     * once per open, never on a hot path. Advisory on storage adapters that
+     * can't answer (no blob paths / no exact counts): detection skips rather
+     * than false-positives. CORTEX-CONSOLIDATION-SILENT-DROP.
+     *
+     * 1. **Archive-orphan census.** The memtable log rotates
+     *    `memtable-shard-NN.log` → `*.archive` siblings and always recreates
+     *    the live file — so an archive WITHOUT its live log proves the live
+     *    log was deleted (the deleter's signature on memory-vm: 15 of 64
+     *    shards). A missing shard log silently replays nothing and is
+     *    recreated empty on next touch; without this census the loss is
+     *    invisible.
+     * 2. **The |canonical| == |posted| invariant.** Every live entity carries
+     *    exactly one `noun` posting, so the engine's total posted-entity count
+     *    must equal canonical's noun count. `posted < canonical` = stranded
+     *    entities (the incident's ~35 unqueryable writes); `posted > canonical`
+     *    = orphaned postings (egress-guarded at read time, reconciled by the
+     *    same rebuild). Skipped at/above the u32 saturation point of
+     *    `getTotalEntityCount` (a saturated count would make equality lie).
+     */
+    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');
+            if (existsSync(memtableDir)) {
+                const files = readdirSync(memtableDir);
+                const live = new Set(files.filter((f) => /^memtable-shard-\d{2}\.log$/.test(f)));
+                const orphaned = [];
+                for (const f of files) {
+                    const m = /^(memtable-shard-\d{2}\.log)\..+\.archive$/.exec(f);
+                    if (m && !live.has(m[1]) && !orphaned.includes(m[1])) {
+                        orphaned.push(m[1]);
+                    }
+                }
+                if (orphaned.length > 0) {
+                    this.strandDetected = true;
+                    prodLog.error(`[NativeMetadataIndex] STRAND: ${orphaned.length} memtable shard ` +
+                        `log(s) have archive rotations but the live log is MISSING ` +
+                        `(${orphaned.join(', ')}) — the live logs were deleted and their ` +
+                        `posting history is gone. Reporting not-ready so the cold-open ` +
+                        `gate rebuilds from canonical.`);
+                }
+            }
+        }
+        catch {
+            // Census is advisory — an unreadable dir must not block open.
+        }
+        // 2. |canonical| == |posted| invariant.
+        try {
+            const getNouns = this.storage.getNouns;
+            if (typeof getNouns === 'function') {
+                const probe = await getNouns.call(this.storage, { pagination: { limit: 1 } });
+                const canonical = probe?.totalCount;
+                if (typeof canonical === 'number' &&
+                    Number.isFinite(canonical) &&
+                    canonical < 0xffff_ffff) {
+                    // Posted count = Σ per-type snapshot cardinalities over brainy's
+                    // CLOSED 42-noun vocabulary (wire-stable, validated at the storage
+                    // boundary — no type outside it can exist in canonical).
+                    // getEntityCountByType reads the LSM SNAPSHOT (memtable + SSTables),
+                    // so it is reopen-true; getTotalEntityCount is NOT (it counts the
+                    // in-process field registry, which is empty at cold open). O(42)
+                    // bitmap-cardinality reads, no id materialization — scale-safe.
+                    // Raw (unmapped) cardinality is acceptable here: at cold open there
+                    // is no mapper-eviction churn to inflate it.
+                    const { NounType } = await import('@soulcraft/brainy');
+                    let posted = 0;
+                    for (const t of Object.values(NounType)) {
+                        posted += this.native.getEntityCountByType(t);
+                    }
+                    // LOWER-BOUND invariant, not equality: the adapter's totalCount
+                    // EXCLUDES system-routed entities (e.g. the VFS root) while the
+                    // index posts them, so healthy brains sit at posted ≥ canonical.
+                    // posted < canonical therefore proves lost postings. A strand
+                    // smaller than the (1–2 entity) system skew is masked here and
+                    // falls to the archive census above; the exact invariant (a
+                    // persisted posted-count stamp) is CORTEX-BILLION-SCALE-SPINE work.
+                    if (posted < canonical) {
+                        this.strandDetected = true;
+                        prodLog.error(`[NativeMetadataIndex] STRAND: canonical holds ${canonical} ` +
+                            `entities but the index has postings for only ${posted} — ` +
+                            `${canonical - posted}+ entities are durable in canonical but ` +
+                            `UNQUERYABLE (lost postings). Reporting not-ready so the ` +
+                            `cold-open gate rebuilds from canonical.`);
+                    }
+                }
+            }
+        }
+        catch {
+            // Invariant probe is advisory — a failed canonical read must not block open.
+        }
+    }
     // ==========================================================================
     // Storage I/O helpers
     // ==========================================================================
@@ -2463,12 +2654,39 @@ 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();
             prodLog.info(`Metadata index rebuild completed! Processed ${totalNounsProcessed} nouns and ${totalVerbsProcessed} verbs`);
+            // A completed rebuild re-posted every canonical entity into a freshly
+            // re-opened engine (reopenLsmEngineFresh wiped the stale shard set) —
+            // any cold-open strand verdict is now satisfied.
+            this.strandDetected = false;
         }
         finally {
             this.isRebuilding = false;
@@ -2491,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 } })
@@ -2501,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++;
@@ -2510,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.
@@ -2531,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

@@ -1260,8 +1260,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
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/cor",
-  "version": "3.0.10",
+  "version": "3.0.12",
   "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.5",
     "@types/node": "^22.0.0",
     "pg": "^8.21.0",
     "tsx": "^4.21.0",